<h1><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com%2Fu%2F231013899%3Fs%3D400%26v%3D4&mask=circle" width="38" height="38" valign="bottom" alt="Flemma's logo"> Flemma</h1>

An AI workspace inside Neovim where every conversation is a document you own.

https://github.com/user-attachments/assets/cd1c509d-faea-48e1-bd4d-d01e234d6856

[!IMPORTANT] Actively Evolving. See the roadmap for what's coming next. Pin a tag if you need a stable target.

What Is Flemma?

Flemma is an AI plugin for Neovim. You write in .chat files -- plain text with simple role markers -- and Flemma handles everything else: streaming responses, running tools, managing providers, and keeping the conversation clean and navigable.

@You:
Turn my rough notes into a project update for the team.

- Auth module now validates JWTs server-side.
- Migrated billing webhook to v2 API.
- Fixed the flaky CI timeout on integration tests.

Use `git log` for commit details.

@Assistant:
(response streams here)

What makes Flemma different from other AI tools is a simple design choice: the .chat file is the conversation. There's no database behind it, no hidden session state, no opaque storage. The file you see is the file the model sees. That one decision unlocks everything else.

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):

| Provider | Variable | | --------- | -------------------------------------------------------- | | Anthropic | ANTHROPIC_API_KEY | | OpenAI | OPENAI_API_KEY | | Moonshot | MOONSHOT_API_KEY | | Vertex AI | VERTEX_AI_ACCESS_TOKEN (or service-account flow below) |

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:

Create a service account with the Vertex AI User role.
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.
Ensure gcloud is on your $PATH -- Flemma uses gcloud auth print-access-token to refresh tokens.
Set project_id in your config or via :Flemma switch vertex gemini-3.1-pro-preview project_id=my-project.

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

</details>

Why Conversations as Files?

Most AI tools treat conversations as disposable. Some let you resume a session or rewind to a checkpoint, but you can't go back and edit a message you sent two turns ago and have the model treat it as if it was always there. The conversation is the tool's state, not yours. Flemma takes the opposite approach.

Your conversations are files. Save them. Reopen them tomorrow. git commit them. grep across months of work. Share a conversation with a colleague by sending them the file -- they open it in Flemma and pick up exactly where you left off, with the same model settings, the same system prompt, the same everything.

You can edit anything. The model hallucinated? Fix the response and resend. Went down the wrong path? Delete the last few turns and try again. Want to test how a different model handles the same prompt? Switch providers mid-conversation with :Flemma switch openai and press <kbd>Ctrl-]</kbd>. There's no hidden state to get out of sync because there is no hidden state.

Every conversation can have its own settings. One .chat file uses Claude for code review with full tool access. Another uses Gemini for brainstorming with thinking turned off. A third is a reusable template your team shares for incident postmortems. The settings live inside each file -- no global config changes needed.

You stay in Neovim. Vim motions, your keybindings, your colour scheme, your workflow. Flemma adds a handful of buffer-local mappings and gets out of the way.

What Can You Do With It?

Flemma is more than a chatbot. Here are some of the things people use it for:

Code with an AI agent. Give it a task -- "add error handling to the payment module" -- and let autopilot do the work. Flemma explores the codebase, reads files, writes code, runs tests, reads the output, fixes failures, and repeats. You approve each step or let it run fully autonomously, YOLO.
Write and create. Technical documents, project updates, architecture decisions, client proposals. Feed it rough notes and context files, get polished output.
Research and explore. Attach files with @./path/to/file, ask questions, iterate. Switch between Claude and GPT to compare perspectives on the same problem.
Build reusable prompts. A .chat file with a system prompt and variables becomes a template. Share it with your team. Each person fills in their details and gets consistent results.
Work across providers. Start a conversation with Anthropic, switch to OpenAI for a second opinion, try Vertex for the final draft. All in the same file, all without leaving Neovim.

Providers

Four built-in providers. Switch at any time -- even mid-conversation:

:Flemma switch openai gpt-5 temperature=0.3
:Flemma switch $fast  " named presets

| Provider | Default Model | | ------------- | ------------------------ | | Anthropic | claude-sonnet-4-6 | | OpenAI | gpt-5.4 | | Vertex AI | gemini-3.1-pro-preview | | Moonshot | kimi-k2.5 |

All four support extended thinking/reasoning through a single thinking parameter that Flemma maps to each provider's native format. Set thinking = "high" once and it works everywhere -- see the full mapping table in configuration.md. Prompt caching is handled automatically -- read more in prompt-caching.md.

Credentials are resolved automatically from environment variables or your platform keyring -- see Setting up credentials under Quick Start above.

Define presets for quick switching:

require("flemma").setup({
  presets = {
    ["$fast"] = "vertex gemini-2.5-flash thinking=minimal",
    ["$review"] = { provider = "anthropic", model = "claude-sonnet-4-6", max_tokens = 6000 },
  },
})

The Agent

Flemma can work autonomously. When the model needs to read a file, edit code, or run a command, it uses tools -- and with autopilot enabled (the default), the entire cycle happens without you pressing a key:

You send a message.
The model responds with tool calls (read a file, run a test, write a fix).
Flemma executes approved tools and sends the results back.
The model decides what to do next. Repeat until the task is done.

You can watch the whole thing happen in the buffer. Every tool call, every result, every decision is visible text that you can read, edit, or undo.

Built-in tools

| Tool | What it does | | ------- | --------------------------------------- | | bash | Runs shell commands | | read | Reads file contents | | edit | Find-and-replace in files | | write | Creates or overwrites files | | grep | Searches with ripgrep (experimental) | | find | Finds files by pattern (experimental) | | ls | Lists directory contents (experimental) |

Safety

Approval. By default, file tools (read, edit, write, grep, find, ls) are auto-approved. bash is auto-approved when the sandbox is available, or requires your review otherwise. You see a preview of what the tool will do before approving: bash: running tests -- $ make test. Customize approval with presets ($standard, $readonly) or write your own logic.
Sandbox. On Linux, shell commands run inside a Bubblewrap container with a read-only root filesystem. Only your project directory and /tmp are writable. Enabled by default. The sandbox is damage control, not a security boundary -- it limits the blast radius of common accidents, not deliberate attacks.
Turn limit. Autopilot stops after 100 consecutive turns to prevent runaway cost.
You're in control. Let it run fully autonomous, supervise and approve tools one at a time, or stop at any point, edit the conversation, and resume.

MCP support

Flemma supports the Model Context Protocol (MCP) through [MCPorter](https://g

Flemma.nvim

Install / Use

README