Flemma turns Neovim into a first-class AI workspace. It gives .chat buffers streaming conversations, reusable prompt templates, attachment support, cost tracking, and ergonomic commands for the three major providers: Anthropic Claude, OpenAI, and Google Vertex AI.

Q: What is this and who is it for?
A: Flemma is not a coding assistant. I [ @StanAngeloff] created Flemma as my AI workspace for everything else. [continued]

Flemma is for the technical writers, researchers, creators, and tinkerers, for those who occasionally get in hot water and need advice. It's for everyone who wants to experiment with AI.

• Multi-provider chat – work with Claude, OpenAI, and Vertex models through one command tree while keeping prompts in plain .chat buffers.
• .chat editing tools – get markdown folding, visual rulers, <thinking> highlighting, and message text objects tuned for chat transcripts.
• Structured templates – combine Lua or JSON frontmatter, inline {{ expressions }}, and include() helpers to assemble prompts without leaving Neovim.
• Context attachments – reference local files with @./path; Flemma handles MIME detection and surfaces warnings when a provider can’t ingest the asset.
• Reasoning visibility – stream Vertex thinking blocks into the buffer, expose OpenAI reasoning effort in lualine, and strip thought traces from the history sent back to models.
• Usage reporting – per-request and session notifications show token totals and costs using the bundled pricing tables.
• Presets and hooks – store favourite provider configurations, run on_request_* callbacks, auto-write finished chats, and recall the latest usage notification when auditing work.
• Contributor tooling – toggle structured logs, drop into the project’s Nix dev shell, and run the bundled headless tests without extra setup.

Flemma works with any plugin manager. With lazy.nvim you only need to declare the plugin – opts = {} triggers require("flemma").setup({}) automatically:

{
  "Flemma-Dev/flemma.nvim",
  opts = {},
}

For managers that do not wire opts, call require("flemma").setup({}) yourself after the plugin is on the runtime path.

secret-tool store --label="Claude API Key" service anthropic key api
secret-tool store --label="OpenAI API Key" service openai key api
secret-tool store --label="Vertex AI Service Account" service vertex key api project_id your-gcp-project

1. Configure the plugin:

   require("flemma").setup({})

2. Create a new file that ends with .chat. Flemma only activates on that extension.

3. Type a message, for example:

   @You: Turn the notes below into a short project update.
   - Added Vertex thinking budget support.
   - Refactored :Flemma command routing.
   - Documented presets in the README.

4. Press Ctrl-] (normal or insert mode) or run :Flemma send. Flemma freezes the buffer while the request is streaming and shows @Assistant: Thinking....

5. When the reply finishes, a floating notification lists token counts and cost for the request and the session.

Cancel an in-flight response with Ctrl-c or :Flemma cancel.

```lua
release = {
  version = "v25.10-1",
  focus = "command presets and UI polish",
}
notes = [[
- Presets appear first in :Flemma switch completion.
- Thinking tags have dedicated highlights.
- Logging toggles now live under :Flemma logging:*.
]]
```

@System: You turn engineering notes into concise changelog entries.

@You: Summarise {{release.version}} with emphasis on {{release.focus}} using the points below:
{{notes}}

@Assistant:
- Changelog bullets...
- Follow-up actions...

<thinking>
Model thoughts stream here and auto-fold.
</thinking>

• Frontmatter sits on the first line and must be fenced with triple backticks. Lua and JSON parsers ship with Flemma; you can register more via flemma.frontmatter.parsers.register("yaml", parser_fn).
• Messages begin with @System:, @You:, or @Assistant:. The parser is whitespace-tolerant and handles blank lines between messages.
• Thinking blocks appear only in assistant messages. Vertex AI models stream <thinking> sections; Flemma folds them automatically and keeps dedicated highlights for the tags and body.

Toggle folds with your usual mappings (za, zc, etc.). The fold text shows a snippet of the hidden content so you know whether to expand it.

Between messages, Flemma draws a ruler using the configured ruler.char and highlight. This keeps multi-step chats legible even with folds open.

Inside .chat buffers Flemma defines:

• ]m / [m – jump to the next/previous message header.
• im / am (configurable) – select the inside or entire message as a text object. Thinking blocks are skipped so yanking im never includes <thinking> sections unintentionally.
• Buffer-local mappings for send/cancel default to <C-]> and <C-c> in normal mode. Insert-mode <C-]> stops insert, sends, and re-enters insert when the response finishes.

Disable or remap these through the keymaps section (see Configuration reference).

Use the single entry point :Flemma {command}. Autocompletion lists every available sub-command.

• :Flemma switch (no arguments) opens two vim.ui.select pickers: first provider, then model.
• :Flemma switch openai gpt-5 temperature=0.3 changes provider, model, and overrides parameters in one go.
• :Flemma switch vertex project_id=my-project location=us-central1 thinking_budget=4096 demonstrates long-form overrides. Anything that looks like key=value is accepted; unknown keys are passed to the provider for validation.

Define reusable setups under the presets key. Preset names must begin with $; completions prioritise them above built-in providers.

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

Switch using :Flemma switch $fast or :Flemma switch $review temperature=0.1 to override individual values.

The full model cataloguel (including pricing) is in lua/flemma/models.lua. You can access it from Neovim with:

:lua print(vim.inspect(require("flemma.provider.config").models))

Flemma’s prompt pipeline runs through three stages: parse, evaluate, and send. Errors at any stage surface via diagnostics before the request leaves your editor.

• Place a fenced block on the first line (```lua or ```json).
• Return a table of variables to inject into the template environment.
• Errors (syntax problems, missing parser) block the request and show in a detailed notification with filename and line number.

```lua
recipient = "QA team"
notes = [[
- Verify presets list before providers.
- Check spinner no longer triggers spell checking.
- Confirm logging commands live under :Flemma logging:*.
]]
```

Use {{ expression }} inside any non-assistant message. Expressions run in a sandbox that exposes:

• Standard Lua libs (string, table, math, utf8).
• vim.fn (fnamemodify, getcwd) and vim.fs (normalize, abspath).
• Variables returned from frontmatter.

Outputs are converted to strings. Tables are JSON-encoded automatically.

@You: Draft a short update for {{recipient}} covering:
{{notes}}

Errors in expressions are downgraded to warnings. The request still sends, and the literal {{ expression }} remains in the prompt so you can see what failed.

Call include("relative/or/absolute/path") inside frontmatter or an expression to inline another template fragment. Includes are evaluated in isolation (they do not inherit your variables) and support their own {{ }} and @./ references.

Guards in place:

• Relative paths resolve against the file that called include().
• Circular includes raise a descriptive error with the include stack.
• Missing files or read errors raise warnings that block the request.

Flemma groups diagnostics by type in the notification shown before sending:

• Frontmatter errors (blocking) – malformed code, unknown parser, include issues.
• Expression warnings (non-blocking) – runtime errors during {{ }} evaluation.
• File reference warnings (non-blocking) – missing files, unsupported MIME types.

If any blocking error occurs the buffer becomes modifiable again and the request is cancelled before hitting the network.

Embed local context with @./relative/path (or @../up-one/path). Flemma handles:

1. Resolving the path against the .chat file (after decoding URL-escaped characters like %20).
2. Detecting the MIME type via file or the extension fallback.
3. Streaming the file in the provider-specific format.

Examples:

@You: Critique @./patches/fix.lua;type=text/x-lua.
@You: OCR this screenshot @./artifacts/failure.png.
@You: Compare these specs: @./specs/v1.pdf and @./specs/v2.pdf.

Trailing punctuation such as . or ) is ignored so you can keep natural prose. To coerce a MIME type, append ;type=<mime> as in the Lua example above.

If a file cannot be read or the provider refuses its MIME type, Flemma warns you (including line number) and continues with the raw reference so you can adjust your prompt.

Each completed request emits a floating report that names the provider/model, lists input/output tokens (reasoning tokens are counted under ⊂ thoughts), and – when pricing is enabled – shows the per-request and cumulative session cost derived from lua/flemma/models.lua. Token accounting persists for the lifetime of the Neovim instance; call require("flemma.state").reset_session() if you need to zero the counters without restarting. pricing.enabled = false suppresses the dollar amounts while keeping token totals for comparison.

Flemma keeps the most recent notification available via :Flemma notification:recall, which helps when you close the floating window before capturing the numbers. Logging lives in the same subsystem: toggle it with :Flemma logging:enable / :Flemma logging:disable and open the log file (~/.local/state/nvim/flemma.log or your stdpath("cache")) through :Flemma logging:open whenever you need the redacted curl command and streaming trace.

Configuration keys map to dedicated highlight groups:

Each value accepts a highlight name, a hex colour string, or a table of highlight attributes ({ fg = "#ffcc00", bold = true }).

Role markers inherit role_style (comma-separated GUI attributes) so marker styling tracks your message colours.

Set signs.enabled = true to place signs for each message line. Each role (system, user, assistant) can override the character and highlight. Signs default to using the message highlight colour.

While a request runs Flemma appends @Assistant: Thinking... with an animated braille spinner. The line is flagged as non-spellable so spell check integrations stay quiet. Once streaming starts, the spinner is removed and replaced with the streamed content.

Add the bundled component to show the active model (and reasoning effort when set):

require("lualine").setup({
  sections = {
    lualine_x = {
      { "flemma", icon = "🧠" },
      "encoding",
      "filetype",
    },
  },
})

The component only renders in chat buffers. Switching providers or toggling OpenAI reasoning effort causes Flemma to refresh lualine automatically.

Flemma works without arguments, but every option can be overridden:

require("flemma").setup({
  provider = "claude",
  model = nil, -- provider default
  parameters = {
    max_tokens = 4000,
    temperature = 0.7,
    timeout = 120,
    connect_timeout = 10,
    vertex = {
      project_id = nil,
      location = "global",
      thinking_budget = nil,
    },
    openai = {
      reasoning = nil, -- "low" | "medium" | "high"
    },
  },
  presets = {},
  highlights = {
    system = "Special",
    user = "Normal",
    assistant = "Comment",
    user_lua_expression = "PreProc",
    user_file_reference = "Include",
    thinking_tag = "Comment",
    thinking_block = "Comment",
  },
  role_style = "bold,underline",
  ruler = { char = "━", hl = "NonText" },
  signs = {
    enabled = false,
    char = "▌",
    system = { char = nil, hl = true },
    user = { char = "▏", hl = true },
    assistant = { char = nil, hl = true },
  },
  notify = require("flemma.notify").default_opts,
  pricing = { enabled = true },
  text_object = "m",
  editing = {
    disable_textwidth = true,
    auto_write = false,
  },
  logging = {
    enabled = false,
    path = vim.fn.stdpath("cache") .. "/flemma.log",
  },
  keymaps = {
    enabled = true,
    normal = {
      send = "<C-]>",
      cancel = "<C-c>",
      next_message = "]m",
      prev_message = "[m",
    },
    insert = {
      send = "<C-]>",
    },
  },
})

Additional notes:

• editing.auto_write = true writes the buffer after each successful request or cancellation.
• Set text_object = false to disable the message text object entirely.
• notify.default_opts exposes floating-window appearance (timeout, width, border, title).
• logging.enabled = true starts the session with logging already active.

The repository provides a Nix shell so everyone shares the same toolchain:

nix develop

Inside the shell you gain convenience wrappers:

• flemma-fmt – run nixfmt, stylua, and prettier across the repo.
• flemma-amp – open the Amp CLI, preconfigured for this project.
• flemma-codex – launch the OpenAI Codex helper.

Run the automated tests with:

make test

The suite boots headless Neovim via tests/minimal_init.lua and executes Plenary+Busted specs in tests/flemma/, printing detailed results for each spec so you can follow along.

To exercise the plugin without installing it globally:

nvim --cmd "set runtimepath+=`pwd`" \
  -c 'lua require("flemma").setup({})' \
  -c ':edit scratch.chat'

• Nothing happens when I send: confirm the buffer name ends with .chat and the first message starts with @You: or @System:.
• Frontmatter errors: notifications list the exact line and file. Fix the error and resend; Flemma will not contact the provider until the frontmatter parses cleanly.
• Attachments ignored: ensure the file exists relative to the .chat file and that the provider supports its MIME type. Use ;type= to override when necessary.
• Vertex refuses requests: double-check parameters.vertex.project_id and authentication. Run gcloud auth application-default print-access-token manually to ensure credentials are valid.
• Keymaps clash: disable built-in mappings via keymaps.enabled = false and register your own :Flemma commands.

Happy prompting!