Quick Start

-- lazy.nvim (any plugin manager works):
{ "Flemma-Dev/flemma.nvim", opts = {} }

-- If your plugin manager doesn't auto-call setup(), add this to your config:
require("flemma").setup({})

export ANTHROPIC_API_KEY="sk-ant-..."   # or OPENAI_API_KEY, MOONSHOT_API_KEY

Create a file ending in .chat. Type your message after @You:. Press <kbd>Ctrl-]</kbd>.

Requirements: Neovim 0.11+, curl, Markdown Tree-sitter grammar. Optional: bwrap for sandboxing (Linux), file for MIME detection.

<details> <summary><strong>Setting up credentials</strong></summary>

Flemma never accepts API keys in your Lua config -- credentials stay in environment variables or your platform's secure keyring.

Environment variables (simplest approach):

Linux keyring (Secret Service) -- store once, reuse across all Neovim sessions:

secret-tool store --label="Anthropic API Key" service anthropic key api
secret-tool store --label="OpenAI API Key" service openai key api
secret-tool store --label="Moonshot API Key" service moonshot key api

macOS Keychain is also supported.

Vertex AI requires a Google Cloud service account:

1. Create a service account with the Vertex AI User role.
2. Export its JSON credentials via VERTEX_SERVICE_ACCOUNT='{"type": "..."}', or store them in the Linux keyring with secret-tool store --label="Vertex AI Service Account" service vertex key api project_id your-project.
3. Ensure gcloud is on your $PATH -- Flemma uses gcloud auth print-access-token to refresh tokens.
4. Set project_id in your config or via :Flemma switch vertex gemini-3.1-pro-preview project_id=my-project.

Flemma tries each source in order and uses the first one that returns a credential. When everything fails, the notification tells you exactly which sources were tried and why each one couldn't help. You can also add custom sources for tools like Bitwarden or 1Password -- read more in extending.md.

</details>

---

Keymaps (buffer-local to `.chat` files, all configurable)

---

Configuration

Flemma works without arguments -- require("flemma").setup({}) uses sensible defaults. Here's a practical starting point:

require("flemma").setup({
  provider = "anthropic",               -- "anthropic" | "openai" | "vertex" | "moonshot"
  thinking = "high",                    -- unified across all providers
  presets = {
    ["$fast"] = "vertex gemini-2.5-flash thinking=minimal",
    ["$opus"] = "anthropic claude-opus-4-6 thinking=max",
  },
  sandbox = { backend = "required" },   -- warn if no sandbox backend is available
  editing = { auto_write = true },      -- save .chat files after each response
})

Individual .chat files can override any of these settings. Detailed references:

• configuration.md -- every option explained with inline comments
• tools.md -- tool approval, custom tools, and the resolver API
• mcp.md -- MCP support via MCPorter
• templates.md -- per-file settings, expressions, and file includes
• sandbox.md -- sandbox policies, path variables, and custom backends
• ui.md -- highlights, rulers, turns, notifications, and folding
• session-api.md -- programmatic access to token usage and cost data

---

FAQ

<details> <summary><strong>Can I use different models for different conversations?</strong></summary>

Yes. Each .chat file can set its own provider, model, and parameters. You can also switch mid-conversation with :Flemma switch openai gpt-5. Read more in configuration.md.

</details>

<details> <summary><strong>Can I attach files, images, or PDFs?</strong></summary>

Yes. Type @./path/to/file in your message and Flemma inlines the content before sending. Images and PDFs are base64-encoded and sent as multipart attachments where the provider supports it. MIME types are detected automatically. Read more in templates.md.

</details>

<details> <summary><strong>Can I build reusable prompt templates?</strong></summary>

Yes. A .chat file with a system prompt, variables, and expressions becomes a template. Define variables in a code block at the top of the file and reference them throughout your messages. You can also include other files and compose system prompts from building blocks. Read more in templates.md.

</details>

<details> <summary><strong>Can I control which tools the agent can use?</strong></summary>

Yes. Tools are governed by an approval system with built-in presets ($standard for file tools, $readonly for read-only access). You can auto-approve specific tools, require manual review for others, or write custom approval logic. Each .chat file can override the global policy. Read more in tools.md.

</details>

<details> <summary><strong>How do I store API keys securely?</strong></summary>

Flemma checks environment variables first, then your platform keyring (Linux Secret Service or macOS Keychain), then gcloud for Vertex AI. You never have to put keys in a config file. Read more in extending.md.

</details>

<details> <summary><strong>Can I add my own tools or integrate with other systems?</strong></summary>

Yes. Register custom tools, approval resolvers, credential resolvers, sandbox backends, and more -- everything plugs in through registries. For MCP servers (Slack, Linear, GitHub, etc.), enable the built-in MCPorter integration -- see mcp.md. For custom Lua tools, read tools.md and extending.md.

</details>

<details> <summary><strong>Who made this?</strong></summary>

<img src="https://images.weserv.nl/?url=gravatar.com%2Favatar%2Fea3f8f366bb2aa0855db031884e3a8e8%3Fs%3D400%26d%3Drobohash%26r%3Dg&mask=circle" valign="middle" align="left" width="18" height="18" alt="Photo of @StanAngeloff">&thinsp;@StanAngeloff. Flemma started as a personal tool for thinking, writing, and experimenting with AI inside Neovim. It's been used for everything from architecture documents and project planning to bedtime stories.

</details>

---

Troubleshooting

Start with :Flemma status. It shows a tree of everything Flemma knows about the current buffer -- provider, model, resolved parameters, sandbox state, enabled tools, approval policies, and which config layer set each value. Add verbose for the full picture. If something isn't working, this is the fastest way to find out why.

---