Start · README.md

Overview

Leader is a Neovim config on top of NvChad v2.5, designed as a small framework: you clone it, run a script and get an editor ready to work, with what a developer uses every day and nothing more. Minimalism, fast productivity and performance: everything loads lazily, one file = one responsibility, and whatever you don't use is turned off with one line.

latest release · Neovim ≥ 0.11 · Linux, WSL, macOS and Windows · documentation · wallpapers

Installation

One command, everything done (Linux, WSL, macOS):

curl -fsSL https://raw.githubusercontent.com/sazardev/leader/master/install.sh | bash

Windows (PowerShell): irm https://raw.githubusercontent.com/sazardev/leader/master/install.ps1 | iex

It asks one thing: which languages to set up, as a checklist of packs (Go, Dart / Flutter, TypeScript / JavaScript, Web, Python, Rust, SQL, Swift, Java / Kotlin, Docker / Make / Prisma…) with the ones this machine already uses checked; Enter keeps them. Only the languages you keep download their LSPs, formatters and linters (the base, Lua, Markdown, JSON, YAML, TOML, is always on). Change them later in <Space>Sp → Languages. No clone needed: it fetches the repo into ~/.local/share/leader and does everything else (idempotent: run it again any time to bring it up to date):

1. installs whatever is missing from the system (git, curl, C compiler, ripgrep, node, cmake) and Neovim ≥ 0.11 if you don't have it (in ~/.local/opt, without sudo; with brew on macOS);
2. links nvim/ as your config (~/.config/nvim); an existing one is moved to nvim.bak-<date>, never deleted;
3. enables the git hooks (.githooks: cheatsheet always up to date and conventional commits);
4. writes your per-machine settings (nvim/lua/local.lua, git-ignored): the languages you chose and the options below;
5. installs the plugins at the versions pinned in nvim/lazy-lock.json (in parallel), the LSPs/formatters/linters (Mason) and builds the treesitter parsers (tree-sitter-cli comes from Mason), reporting the time each step took;
6. sets up the AI agent with the best backend it finds (Claude Code, OpenCode, Ollama…); --agent none skips it.

Options go after bash -s --, for example a Go laptop, fully configured:

curl -fsSL https://raw.githubusercontent.com/sazardev/leader/master/install.sh | bash -s -- --lang go,sql --theme gruvbox

Prefer to clone it yourself (to hack on it)? git clone https://github.com/sazardev/leader && cd leader && ./install.sh does exactly the same. Override the fetch with NVIM_CONFIG_DIR, NVIM_CONFIG_REPO and NVIM_CONFIG_BRANCH.

Then open nvim. Press <Space> and which-key shows you the menus.

There is also a landing page, docs/index.html (flat and square like the config, no build, self-hosted Geist in docs/fonts/, dark/light with t), and the documentation at docs/docs/index.html (generated from the Markdown by scripts/gen-docs.sh); serve docs/ with GitHub Pages (cd docs && python3 -m http.server).

./install.sh --lang go,sql --theme gruvbox --agent claude/haiku   # from a clone: a Go laptop, everything configured
./install.sh --dry-run --no-deps --lang rust                      # see what it would do

Single languages also work with --lang: lua go typescript html css tailwind json yaml toml markdown docker prisma astro dart rust python java kotlin sql swift make yarnspinner. If local.lua already exists it is left untouched: the installer tells you what to add (it is yours and may hold other settings).

Native Windows (PowerShell): ./install.ps1 [-Lang go,typescript] [-Theme x] [-Light|-NoLight] [-Agent auto] [-NoPlugins] creates the junction at %LOCALAPPDATA%\nvim and does the same steps (written but not tested on real Windows; on WSL use install.sh).

Uninstall: delete the ~/.config/nvim link (and, if you want, ~/.local/share/nvim, ~/.local/state/nvim, ~/.cache/nvim).

Desktop app (Linux, WSL)

The same editor in its own window: leader, a GPU front-end for Neovim written in Rust (app/). It runs your Neovim with this config, so everything above works the same, but it draws the screen itself instead of a terminal: one draw call per frame, nothing running between keystrokes, and the flat design's half cells and borders drawn as exact rectangles. Add --app to the installer (or run app/install.sh from a clone): it installs Rust with rustup if needed, builds leader and adds Leader to the application menu (~/.local/bin/leader, ~/.local/share/applications).

From a release, in one command (Linux x86_64, glibc 2.31+: Ubuntu 20.04, Debian 11, Fedora 32 and newer; WSL with WSLg): it downloads the package, checks it, installs the app and, when they are missing, Neovim and this config; the first launch shows the welcome screen.

curl -fsSL https://github.com/sazardev/leader/releases/latest/download/leader-installer.sh | bash

From a package: Debian, Ubuntu, Mint, Pop!_OS download leader-editor-amd64.deb from the latest release and sudo apt install ./leader-editor-amd64.deb; Arch, CachyOS, Manjaro use the PKGBUILDs in packaging/arch (leader-editor-bin prebuilt, leader-editor from source; makepkg -si). The packages add the menu entry, the icons, the manual (man leader) and leader-setup, which installs the config for your user (the first launch with no Neovim config runs it in the window). Every release is signed and checksummed: how to verify it in packaging/README.md.

From a clone:

./install.sh --app          # the config + the desktop app (built from source)
app/install.sh --uninstall  # remove the app (the config stays)

• Open it with leader [files…] (any nvim argument works) or from the menu; files dropped on the window open in it.
• The system clipboard works on its own ("+y, "+p, Ctrl+Shift+V), no wl-copy/xclip/OSC 52 needed.
• Its own title bar, painted with the editor's background so it is part of it (it steps back while a modal such as Telescope is open), in a smaller type than the code, laid out like Zed's. Leader's dotted N (it ripples on hover; also F10) opens the app menu: File, Edit, Selection, View, Go, Run, Git (inside a repo), Agent, Window and Help, each a submenu whose items do exactly what Leader's own keys do and show them, plus the command palette (Ctrl+Shift+P: every menu item and every key of the config in one search). The project's name opens the projects menu (every folder you worked in, newest first; switching saves the session and restores the other project's, unsaved files are never dropped) and Open Project… (Ctrl+Shift+O) a full-screen picker: your recent projects and every git project under your home, with the one under the cursor described on the right (branch and changes, last commit, when you opened it, whether a session brings your windows back, its stack, its README); ⏎ opens it, o in a new window, d forgets it, plus a folder by path, a new project or a clone. ⌂ goes to the start screen, ↺ opens your recent files. Center: the current file's path, every part clickable. Right, live: what is running (LSP indexing with its progress, installs, a save: a dot spinner and a thin progress line), what is left to install, a macro being recorded, the file's git changes, unusual encodings or line endings; then minimize · maximize · close as three small flat squares. Configure it in gui.appbar: controls, buttons = { mark, project, home, history }, activity, show, enabled = false for the system's title bar.
• Full mouse: everything you can choose follows the pointer and answers a click. Menus light up the item under the pointer and open submenus as you pass over them; the project picker (and every full-screen list of the config) selects the row under the pointer with its details beside it, opens it on a click, and its key chips are buttons; modals light up their buttons; Telescope (the palette and every picker) selects on hover and opens on a click; the file tree opens a file or a folder with one click; the start screen's buttons follow the pointer. Over menus and pickers the pointer is an arrow, over text an I-beam.
• A guided setup opens on the first launch, full screen, in seven steps (each one says what it still needs and Next waits for it; keyboard or mouse): what this machine is (distro, package manager, GPU), a theme (previewed live as you move over it), your languages (the ones this machine uses already checked), a few features, an AI agent (the ones found here with their models, or one to install), what to install (missing system packages with the exact command for pacman, apt, dnf, zypper or apk, Leader's plugins, language tools and parsers, and the agent you asked for: nothing runs until you press Install, sudo asks in a terminal, each item shows its status) and a review with the install checks. It comes back with Ctrl+Shift+W, Help › Welcome or the bar's "to finish" chip. Full-screen lists such as Open a project mark the chosen row with a bar and move with the arrows or hjkl.
• Updates, connected: Leader looks for a newer version now and then (one tiny request, never more than every 12 hours, off with update.enabled) and shows a ↑ 1.9.0 badge in the bar and a line at the top of the logo's menu. Click it for what changed, version by version, and update on request: the config is pulled with git (never merged or discarded), the plugins restored to the lockfile, the desktop app updated through its installer, and Leader offers to restart. Skip hides a version until a newer one; Help › Check for Updates looks right now.
• Projects first, like an IDE: started from the menu, Leader asks which project to open (or reopens the last one, or shows the start screen: your choice); leader ~/code/app opens that folder as the project. Pin the ones you use (p in the picker) to keep them at the top, or walk your folders Yazi-style (b in the picker: h up, l in, ⏎ open). Recent files (Space f o, the start screen) are the ones of the project you are in, not everything you ever opened; Ctrl+A there widens it to every project. The window comes back with its size, place and maximized state, and its frame is yours to pick (Leader's square bar or the system's).
• A toolbar you decide: a right click on the bar (or View › Customize Toolbar) turns each tool and chip on or off: project, home, recent files, command palette, file tree, terminal, problems, agent (pick the agent and model right there), theme (light/dark, the terminal's theme, a dark and a light list previewed as you hover, the whole catalog), settings, setup. Every tool shows a tooltip with its key.
• Window keys: F10 app menu, Ctrl+Shift+P command palette, Ctrl+Shift+O open a project, F11 fullscreen, Ctrl+Shift+Enter maximize, Ctrl+Shift+M minimize, Ctrl+Shift+N new window, Ctrl+Shift+H home, Ctrl+Shift+R recent files, Ctrl+Shift+W welcome and checks.
• Font: gui.font in core/settings.lua (guifont syntax, "Family:h12"); Ctrl+= / Ctrl+- / Ctrl+0 resize it.
• WSL: it opens through WSLg on the Windows GPU (Mesa's d3d12 driver), with no setup.
• LEADER_TIMING=1 leader prints where the startup time goes (~170 ms to the first frame on WSLg, GPU start included).

Philosophy

• Fast: ~20 ms startup (measured headless, with --startuptime); defaults.lazy = true, plugins loaded by event/filetype/command/key, bytecode cache (vim.loader) and unneeded built-in plugins disabled.
• Minimal: 54 entries in lazy-lock.json, counting dependencies and NvChad's own. No heavy session manager, no tab bar, no embedded AI chat, no LSP dependency tree for things you don't use.
• Modular: the config is declared, not wired. Adding a language, a plugin, an agent action or a Go helper means creating one file; nothing else is touched.
• Spend the minimum: whatever can be decided without a model is decided beforehand (gates, local analysis, treesitter completion); when one has to be called, only what is needed is sent and the cost is shown.
• Light where it matters: with ≤ 2 GB of RAM the resident processes (LSP, golangci-lint) are turned off automatically; force it with NVIM_LIGHT=1|0.
• Everything by keyboard, with keys documented and generated from the real code.

What's included

Commits (<leader>G)

A single panel for committing: what goes in (staged vs not staged, with +/− per file), the message with live Conventional Commits validation (✔ feat(scope) · 38/72), assisted type and scope, and a line saying what the agent will do before spending anything. Gc opens the panel, Gm opens it with the AI draft, GM commits on its own, in the background (stages what is modified except sensitive files, the AI writes ONE message in English, it is validated and committed; if anything fails, it undoes what it staged) and Ga rewrites the last one. The AI message is always in English, on one line, in ~2 s with a light model.

AI agent (<leader>a)

It is not a plugin: it is Lua code in this config, with no dependencies, and it does nothing until you invoke it. Claude Code, OpenCode, Ollama (CPU/CUDA), LM Studio/llama.cpp/vLLM and other CLIs; it detects and configures its backends on its own (<leader>am → Setup, or ./scripts/agent-setup.sh). A short generic menu and one menu per level, each with its own folder and actions:

Around the proposals: Tab refines one instead of starting over, accepted code is verified for free (the LSP's new errors are compared with the old ones and it offers one more attempt with them), and a spend guard checks every request against your own history (it asks above a size, blocks at the caps you set). Also: clear findings one at a time, per file or all of them (<leader>ac, aC, :AgentClear), history in markdown with the code sent, filters and back navigation (<leader>ah), models per tier (cheap where it is enough). Details in docs/cheatsheets/agent.md.

Herdr (<leader>W)

Herdr is the terminal workspace that runs the coding agents. Leader reads it through its CLI: <leader>Wa opens the breakdown of the workspace — one row per agent (its state, its kind, where it is), the transcript of the one under the cursor and why Herdr thinks it is in that state, refreshed on its own. f brings the agent's pane to the front, s sends it a prompt. <leader>Ws is the setup: it detects the binary, the server and the agents' integrations, and installs what is missing (nothing without pressing the button).

It also goes the other way: with the registration on, this nvim appears in Herdr's Agents panel saying what it is doing (working while the agent runs, blocked while a proposal waits for you), and Herdr 0.10+ brings the pane back with your session after a server restart. Details in docs/cheatsheets/herdr.md.

Go without an LLM (smart completion, 0 tokens)

On top of a shared index (utils/goindex.lua: treesitter + go.mod, cached by date):

• missing methods to satisfy an interface, with the exact signature and bodies that call your dependency (return s.repo.FindByID(ctx, id));
• if err != nil with the zero values of the function's returns and a message taken from what is called (the menu opens by itself after x, err := …);
• mappers between layers (NoteResponse ↔ Note), constructor wiring (NewNoteService(noteRepo) with the arguments resolved), enum helpers (IsValid, Parse, UnmarshalText…), interface from a struct and var _ I = (*T)(nil), HTTP handlers from a service (net/http, chi, gin, echo);
• getters of the private fields (slices and maps as copies), Reconstitute (the persistence constructor), the domain's repository port and package ranked by the folder (main only where it makes sense);
• struct tags, constructors, filled literals, sentinel errors, statement snippets. Details in docs/cheatsheets/go.md.

Dart / Flutter (<leader>d)

• run and debug through nvim-dap, with a picker of entry points (lib/main*.dart, the last one first) and the device in the statusline; hot reload on save, the app's log in a split that keeps your focus;
• tests inside the editor: the test under the cursor, the file or everything, a mark per test line, failures as diagnostics on the expect that failed, quickfix; <leader>dT jumps between a file and its test;
• code generation: build_runner watch in the background with its state in the statusline and its errors on their line; saving an .arb runs gen-l10n;
• completion for your stack, read from pubspec.yaml: Riverpod providers, freezed classes, Consumer widgets, named after the file and with their part lines; pub outdated written next to each dependency, pub add. Details in docs/cheatsheets/dart-flutter.md.

Customizing

Everything configurable is in nvim/lua/core/settings.lua with its default value and a comment. Your changes go in nvim/lua/local.lua (git-ignored, merged on top; the installer can generate it with --lang, --theme, --light):

-- nvim/lua/local.lua
return {
  theme = { name = "catppuccin" },
  languages = { disabled = { "astro", "dart", "java", "kotlin" } },
  agent = { backend = "ollama", tiers = { lens_security = "light" } },
  git = { commit = { subject_max = 60 } },
}

You do not have to edit a file for the everyday ones: <leader>Sp opens the settings panel (theme, motion, cursor, format on save, diagnostics layout, answer language, light mode, plugins, tools, update…). Enter flips a value and applies it at once when it can (the few that need a restart say so); your choices are kept apart (stdpath("state")/prefs.json), win over local.lua, and "Reset my choices" forgets them. Keys of their own: St theme, Sf format on save, Sl plugins, SM tools, Si info, Su update the config.

Files have the same treatment: <leader>F (and a / r / d inside the tree) creates, renames, moves, duplicates and deletes in flat modals that show where the file will land. Several files at once (a.go; b/c.go; d/), a name with / moves it, the move is a folder picker, and delete goes to a trash (<leader>Fu brings the last one back). Open buffers, language servers and the tree follow a rename; your unsaved changes survive it.

To add (each one is a single file and, at most, a name in its NAMES list):

• a language: nvim/lua/languages/<name>.lua (contract at the top of languages/init.lua);
• a plugin: a file in nvim/lua/plugins/<group>/;
• a dashboard art: nvim/lua/ui/arts/<name>.lua (braille only);
• an AI backend: an entry in agent.custom (no code) or nvim/lua/agent/backends/<name>.lua;
• an agent action, lens or test: agent/actions/, agent/lenses/actions/ or agent/tests/actions/;
• a per-language test convention: agent/tests/convention.lua;
• a Go completion helper: a utils/go<name>.lua module on top of goindex and its call in gosmart.

How it is organized

The principles (the same across the whole repo) and where they show:

• One responsibility per module: the pure parts (commit/conventional.lua, utils/goindex.lua, agent/protocol.lua) kept apart from what touches git, the LSP or the UI (commit/git.lua, commit/panel.lua); one presenter per output kind (agent/output/).
• Open for extension, closed for modification: discovered registries (languages/, agent/actions/, agent/backends/, agent/lenses/); adding one doesn't force editing the others. The agent pipeline is extended with action hooks (retarget, merge, reveal, prepare), with guards (agent/guards/) and with events (agent/events.lua: verification, batches and the proposal queue subscribe; the presenter that accepts a proposal knows none of them).
• Dependencies point to abstractions: each piece talks to a small contract (a backend's build/parser, a context provider's collect(target, done), a Go helper's declaration_items(range, frag)), not to its neighbor's implementation.
• Configurable things in a single place: core/settings.lua; the scripts (install.sh, install.ps1) share the same settings logic (scripts/install-local.lua) instead of duplicating it.

Keys and documentation

• The documentation site: everything below in one searchable page (/ to search). It is generated from these Markdown files (scripts/gen-docs.sh; the pre-commit hook regenerates it).
• CHEATSHEET.md: all the keys. It is generated from the real keymaps (scripts/gen-cheatsheet.sh; the pre-commit hook regenerates it). Inside nvim, the dashboard's Mappings button shows the same.
• docs/cheatsheets/: what the code doesn't say (workflows, tools, pitfalls), one page per language and the agent's.
• AGENTS.md / CLAUDE.md: architecture and pitfalls for whoever touches the config (people or agents).

Structure

install.sh · install.ps1      installation (Linux/WSL/macOS · Windows)
VERSION                       config version
nvim/                         the config (what gets linked)
  init.lua                    bootstrap only
  lua/core/                   settings, options, keymaps and startup autocmds
  lua/languages/              one file per language (declared; not wired)
  lua/plugins/<group>/        one lazy spec per plugin
  lua/menus/                  contextual leader menus
  lua/agent/                  AI agent: backends, actions, context, output, tests, lenses, ddd, setup
  lua/commit/                 commits: validation (pure), git, AI draft, panel
  lua/utils/                  utilities; go*.lua = Go completion helpers on top of goindex
  lua/ui/ appearance/ themes/ dashboard, theme, colors
  lua/prefs/                  settings panel (<leader>S): one file per group of toggles in items/
  lua/files/                  file operations (<leader>F): paths, file system, buffers, modals
  snippets/ ftdetect/ syntax/ custom snippets and filetypes
scripts/                      installation (install-*.lua), cheatsheet, agent setup and tests
docs/cheatsheets/             per-language and agent documentation
.githooks/                    up-to-date cheatsheet + Conventional Commits

Maintenance

• Update: re-run the install command (or git pull && ./install.sh): it brings the plugins to the versions pinned in lazy-lock.json; the config reloads itself when nvim opens.
• Check: scripts/test.sh runs everything (agent and commits, Go helpers, installer and up-to-date cheatsheet; no network or tokens); each suite can also be run on its own: scripts/test-agent.sh, scripts/test-go.sh, scripts/test-install.sh, scripts/gen-cheatsheet.sh --check.
• Commits: Conventional Commits format (feat(scope): subject); the commit-msg hook validates it and <leader>Gc / Gm / GM assist with it.

Start · docs/cheatsheets/README.md

Workflows

Keys: CHEATSHEET.md (repo root) — the only source. It is generated by reading the real keymaps (scripts/gen-cheatsheet.sh) and regenerated on every commit; it is not edited by hand and its tables are not duplicated here. Inside nvim, the dashboard's Mappings button (NvCheatsheet) shows the same thing live. These pages hold what the code doesn't say: what each thing does, workflows, tools, pitfalls. <leader> = Space.

How the leader works

Each language has its own letter under <leader> (g Go, d Dart, t TypeScript, p Python, r Rust, Q SQL, i Swift…) and only exists in buffers of that filetype; <leader>G (Git) only inside a repo, and <leader>a (agent), <leader>R (Makefile tasks), <leader>P (sessions), <leader>u (undo and yank history), <leader>S (settings), <leader>F (files), <leader>C (comments) and <leader>W (Herdr) are global. Press <leader> and which-key shows only what applies to the current file (no delay).

The language menus open an integrated terminal (toggleterm) and run the commands at the project root (they detect go.mod, package.json, Cargo.toml, pubspec.yaml, pom.xml/build.gradle...).

Workflows worth knowing

The exact keys are in CHEATSHEET.md; here, how they combine.

• Jump and come back: after gd / grr / Ctrl+click, Esc returns to where you were (if you didn't edit there); it also closes popups and clears the highlight. Ctrl+o / Ctrl+i walk the jump history.
• Line diagnostic (<leader>xd): opens a popup; press it again to enter it and copy the text.
• Diagnostic blocks (utils/diagblocks.lua): <leader>xa draws all of them under their line (a bar in the severity color, source/code and a 2/5 counter); <leader>xc toggles between all expanded and one by one (each one a single line, only the one on the cursor line opens); <leader>xn/xp jump to the next/previous and turn the view on in one-by-one mode. They show up on their own in every buffer with diagnostics (the text on the right, virtual_text, is off) and <leader>xa turns them off in that buffer; then only the tinted line number remains. In insert mode the blocks are hidden (nothing appears or pushes the code while you type) and come back when you leave with Esc; diagnostics.update_in_insert = true keeps them live. Matched colors (ui/diagcolors.lua): the E2/W1 label in the status bar, the line number and each block's label are the SAME pill (background = the theme's DiagnosticError/Warn/Info/Hint, text = the theme background, bold), and the block's side bar uses that same accent; this way they change together with the theme (also with the theme inherited from the terminal and when Alacritty changes live: diagcolors.sync() detects the change on every status bar refresh and recomputes number and blocks, because base46 loads its cache without notifying through an event). Gutter: no icons either on the left or next to the code. The line number is drawn with the pill of the highest severity on the line (red error, yellow warning, blue info, cyan hint); the pill fits the digits, with a space on each side, so the number ends up centered (it is drawn by 'statuscolumn', defined in settings.options, and lines split by wrap only leave the gap) and git is a thin ┃ bar attached to the number (signcolumn=no: the statuscolumn draws the sign in ONE cell; with signcolumn=yes each sign takes two and an extra gap is left) (green added, blue changed, red deleted), so they are not confused. Your choice (<leader>xa on/off, <leader>xc expanded/collapsed) is global and saved in stdpath("state")/diagblocks.json, so it comes back the same when you reopen nvim; settings.diagnostic_blocks (auto, mode, number) only gives the initial value. <leader>xn/xp with the view off turn it on only in that buffer and don't touch what is saved. It updates on its own when diagnostics or the cursor change. The bottom panel (<leader>xx, Trouble) opens with focus: Enter jumps to the diagnostic and opens its popup, like <leader>xd.
• Delete without clobbering the clipboard: <leader>d + motion (<leader>dd line, <leader>dw word) or in visual mode.
• Multicursor (multicursor.nvim, real cursors like VS Code/Helix; loaded on the first key): add cursors by line (Ctrl+↑/↓), by match of the word or selection (Alt+n/Alt+p, Alt+Shift+n/p skips one) or all at once (Alt+a); Alt+click adds or removes one with the mouse. With several cursors everything (motions, operators, insert, undo) is repeated on each one; Esc clears them, Ctrl+q turns the main cursor off/on, ←/→ switch cursor and Alt+x deletes the current one. In insert mode, the secondary cursors replicate what was typed ON LEAVING insert; if the completion menu is open, Esc/jk close it first and you have to press them again. Ideas: Alt+a on a word to rename it in the file; Ctrl+↓ several times + I/A to edit columns. The native visual block (Ctrl+v + I/A/c) is still there for simple columns. Don't use Ctrl+n (it is nvim-tree).
• Textobjects (treesitter): combine them with operators — daf deletes the function, dif the body, cif changes it, yaf copies it, vaf selects it; dac deletes the class. For braces of any block: di{ (inside), da{ (with braces), % jumps to the pair. PageDown/PageUp jump block by block (function, method, class, struct/interface in Go); they don't stop at closures inside a function, accept a count (3<PageDown>) and, with no blocks or no parser, do the normal scroll. Home/End go to the start/end of the current block; pressing them again goes up to the enclosing block (method → class → file). For start/end of line use ^/$ (or 0), and in insert they remain native.
• Alt+hjkl move a line or block (mini.move); in Normal mode Alt+h is NvChad's horizontal terminal instead (the visual block still moves left).
• Format: <leader>fm formats (conform); it also formats on save.
• Telescope: the preview is always visible. flex layout: on the right in windows ≥ 110 columns, at the bottom in narrow ones (lua/plugins/navigation/telescope.lua).
• nvim-tree: opening a file closes the tree; I shows/hides what git ignores. Deleting a folder warns how many files it contains.
• Terminal: Alt+i (float), Alt+v (vertical) and Alt+h (horizontal) open NvChad's terminals, <leader>g… the toggleterm one. Esc (Terminal or its Normal mode) closes the window and the shell keeps running; Shift+Esc only hands the focus back to the previous window and leaves the terminal open. Shift+Esc needs a terminal that tells it apart from Esc; if yours doesn't, it behaves like Esc.
• Completion (blink.cmp): the documentation appears instantly on selection and, for snippets, shows what will be inserted. Nothing comes preselected, except inside a Go struct tag (there Enter accepts the first suggestion). Sources: LSP, path, snippets, buffer; in Go gotags and gosmart are added; in Lua, lazydev.
  • With the menu open, Tab / Shift+Tab pick a suggestion (and Enter inserts it). Without a menu, inside a snippet (e.g. gorm.Open(dialector, opts)), they jump to the next / previous placeholder.
  • Keep what you typed and move on: Esc (closes the menu without leaving the snippet) and then Tab.
  • Esc (or jk) with the menu open only closes it and undoes the suggestion that was inserted (back to what you typed); you stay in insert mode and in your snippet. Without a menu, they leave insert as usual.
• Sessions: one per folder (and per git branch; main/master use the base). They are not restored automatically: Restore Session button (rs) on the dashboard or its menu key. Opening a single file (nvim x) and quitting overwrites that folder's session; there is a key to not save on exit.
• Git: git-blame is off by default (no cost); it is toggled from the Git menu.
• Conventional commits (<leader>G, a single panel): Gc opens the panel, Gm opens it and immediately asks the AI for the draft, GM commits on its own, without a panel (see below), Ga rewrites the last commit (warns if it is already on the remote). At the top you see what gets committed: what is staged (●, with +/− per file) and, separately, what does not go in (○, modified or new); Space stages/unstages the file (or the whole group if you are on its header), a stages everything, u unstages everything, p or Enter show its diff. Below you write the message and the title is validated live (✔ feat(scope) · 38/72, or why it fails); Ctrl+t picks the type (suggested from the files) and Ctrl+o the scope (from the paths and the history). Underneath, a line says what the agent will do before spending anything (✦ AI claude/haiku · ⌃g to draft · reads 2 files, 3.1k chars: light model, only reads what is staged: its compact diff without lockfiles capped at git.commit.diff_max_chars, the branch and the list of types) and, when done, what it did (drafted by … · 2.5s · 1.2k→39 tok · $0.0001); Ctrl+g asks for the draft (never on its own, except with Gm), replaces the message and is undone with u, and repeating it gives another one. The message is always in English and on a single line (Conventional header; ~2 s with haiku). GM automatic commit: no panel and in the background; if you already staged files it commits only those, otherwise it stages everything modified except sensitive files (git.commit.sensitive: .env, keys…), the AI writes the message, it is validated and committed, and a one-line notice gives hash, message, files, +/−, time and cost. If something fails (no backend, AI, invalid header, a hook) it undoes what it staged and leaves nothing half done (Gm to do it by hand). Ctrl+s (or Enter in normal mode) commits; with nothing staged or with an invalid message it warns and does nothing; if a hook rejects the commit the panel stays open so you can fix it. Tab toggles files ↔ message, q/Esc cancel (and stop the agent). The .githooks/commit-msg hook requires the same format on any git commit (types and length in git.commit; if you change the list of types, change it in the hook too).
• Comments (<leader>C): Cd inserts the idiomatic documentation template for the function/type under the cursor (godoc, LuaCATS, JSDoc, docstring, rustdoc) with name, parameters and return already filled in; Cm lists in quickfix the public items that have no doc comment (for other languages use the agent: <leader>ad). Snippets in any language, with the language's own comment style: todo, fixme, note, hack, warn, perf, deprecated (and with o at the end, e.g. todoo, TODO(name):); they live in nvim/snippets/all.json.
• Theme: gruvbox ↔ gruvbox_light, or inherit the terminal's (Alacritty), which is followed live.
• Other: :TSContext toggle pins the function/class context at the top; za/zc/zo fold (treesitter folds with nvim-ufo, everything open on start) and <leader>z folds by what the code is: <leader>zf the function you are in, zt the type, zo the object/table literal, zb the block (again = the one around it), zm the methods of the current type, zF/zT/zO every function/type/object in the file, za outline only, ze expand all, zs focus here (all closed except this), z1-z3 fold everything deeper than that level (all after <leader>); <leader>C folds long comments (blocks or consecutive // lines of comments.min_lines or more, 4 by default): Cc folds them all and remembers the preference (files you open afterwards, and future sessions, open with them already folded; it is saved in stdpath("state")/comments.json), Ce unfolds them and stops folding them automatically, Ct toggles only the one under the cursor without touching the preference; comments.auto_collapse only gives the initial value; :Lazy sync installs/updates plugins (the config auto-reload does not).

Light mode

On machines with ≤ 2 GB of RAM, LSP, go.nvim and golangci-lint are turned off (go vet remains). Treesitter, conform and nvim-lint keep running. Force it with NVIM_LIGHT=1|0. Per-machine settings in lua/local.lua (ignored by git).

Adding things

• Language: lua/languages/<name>.lua + add it to NAMES in languages/init.lua + its page here.
• Plugin: one file in lua/plugins/<group>/.
• New keymap: give it a desc of 2+ words starting with its section ("Harpoon add file"); the generator and NvCheatsheet group by the first word and drop single-word ones.
• Go snippet: nvim/snippets/go.json (VSCode format).
• After changing keys or menus: nothing to edit by hand; scripts/gen-cheatsheet.sh regenerates CHEATSHEET.md (the pre-commit hook does it on its own).

Start · CHEATSHEET.md

Every key

Generated from the config's real keymaps (nvim_get_keymap, menus/, servers/on_attach.lua). Regenerated automatically on every commit (.githooks/pre-commit). <leader> = Space. This is the ONLY source of keys. What can't be derived from code (what each thing does, workflows, tools): docs/cheatsheets/.

Leader menus

Each menu has its own letter under <leader> and only exists where it applies: when pressing <leader> which-key only shows what belongs to the current buffer.

Agent — <leader>a

_Where: global_

Agent Advanced — <leader>aA

_Where: global_

Agent DDD — <leader>aD

_Where: global_

Agent Doctor — <leader>aX

_Where: global_

Agent Lenses — <leader>aL

_Where: global_

Agent Repository — <leader>aP

_Where: global_

Agent Service — <leader>aU

_Where: global_

Agent Setup — <leader>aS

_Where: global_

Agent Tests — <leader>aT

_Where: global_

CSS — <leader>s

_Where: css, scss, less_

Comments — <leader>C

_Where: global_

Dart / Flutter — <leader>d

_Where: dart_

File — <leader>F

_Where: global_

Fold — <leader>z

_Where: global_

Git — <leader>G

_Where: files inside a git repo_

Go — <leader>g

_Where: go, gomod, gowork_

Herdr — <leader>W

_Where: global_

History — <leader>u

_Where: global_

Java — <leader>j

_Where: java_

Kotlin — <leader>k

_Where: kotlin_

LSP — <leader>L

_Where: global_

Markdown — <leader>m

_Where: markdown_

Python — <leader>p

_Where: python_

Run — <leader>R

_Where: global_

Rust — <leader>r

_Where: rust_

SQL — <leader>Q

_Where: sql_

Session — <leader>P

_Where: global_

Settings — <leader>S

_Where: global_

Swift — <leader>i

_Where: swift_

TypeScript / JavaScript — <leader>t

_Where: typescript, typescriptreact, javascript, javascriptreact_

LSP (when a server attaches)

Buffer-local keymaps from servers/on_attach.lua.

Autocompletion (blink.cmp, insert mode)

Preset enter plus the overrides from plugins/editing/blink.lua. → = tried in order until one applies.

nvim-tree (inside the tree)

Ctrl+n opens/closes it and <leader>e focuses it (see Global shortcuts). g? inside the tree lists these same keys.

Global shortcuts

Sections = first word of the desc (same as the dashboard's Mappings button).

Agent

Clipboard

Comment

Comments

Diagnostics

File

Find

Flash

Fold

General

Harpoon

Herdr

History

LSP

Move

Multicursor

Nvim-tree

Run

Session

Settings

Surround

Telescope

Terminal

Textobject

Window

Native Neovim 0.11 (not from this config)

Start · CHANGELOG.md

Changelog

All notable changes, newest first. Generated from the Conventional Commits since each tag (<leader>GRc).

[1.14.2] - 2026-10-21

Highlights

• An empty file can be a right answer: a build used to report a failure for every file the model left empty, including the ones that are correct that way (a Python __init__.py, a .gitkeep, py.typed, the requirements file of a project with no dependencies). It now does for those what it should: nothing.

Fixes

• build: an empty __init__.py is not a failed answer (5ecfbb0)

[1.14.1] - 2026-10-21

Highlights

• Checked against a real build: a build of a small project with Claude Haiku (13 files, $0.03, under 3 minutes) did what the 1.14.0 notes promise: it named its riskiest requirement, deferred the one SPEC.md left open and said why, ended ⚠ built · 3/4 requirements have a test instead of ✓, and left a .leader/ folder with nothing of the project in it. Two details came out of it and are fixed here: the plan review no longer calls a test that uses a fake or a temporary directory a "stand-in", and the builder's own wiring check is recorded under its name.

Fixes

• build: tests are not stand-ins, name the wiring check (1ff9203)

[1.14.0] - 2026-10-21

Highlights

• A build no longer calls itself done when it only compiles: the closing line now says what is proven, e.g. ◐ built · 23 files · checks pass · 5/17 requirements have a test · core without one: FR-16 · 2 placeholders, and it is ✓ only when every requirement has a test and nothing is open. PROGRESS.md carries the same proof and what is open. A layer build (foundation, design, domain) reports the numbers but keeps ✓; kit.build.strict makes an unproven build a failure.
• A repair cannot delete your code quietly: before a replan trashes files, the review lists what goes (lines, public types, tests, who still uses them) and asks, and the closing line counts the public declarations a build removed or the tests it made unproven.
• Layers build on the code that is there: a whole-project build used to plan from the documents and the ADRs' text only, so it wrote the code earlier builds had left a second time under other names (two ports, two controllers, hundreds of analyzer errors). It now sees the project's files and their API. A free check fails when a public type is declared in two files, Flutter projects run flutter test and Rust ones cargo test, and plans name their risks and what they defer, with a warning for stand-ins of core requirements.
• .leader/ in every project the builder touches: how Leader worked there (how builds end, which checks fail, what a model costs, whether you accept a proposal) as counts, sizes, durations, costs and outcomes, for measuring and improving Leader from real use. Offline: nothing is ever sent. It is never your work: a schema is the only gate, so unknown fields are dropped, file names are salted hashes, and there is no code, prompt, answer, name or text. The folder documents itself, ignores itself in git, <leader>aSl shows the report, LEADER_NO_DATA=1 turns it off, and deleting it clears everything.

Features

• build: honest builds and a local .leader folder (1cb1c6e)

Fixes

• build: skip examples in the duplicate check, hide custom models (bebfb1d)

Documentation

• build: proof, loss gate, duplicates and the .leader folder (94a536e)

Chores

• deps: update the plugin lockfile (3ab99c6)

[1.13.0] - 2026-10-21

Highlights

• The agent is measured now, and a modest model gets help: make eval runs 31 cases (Python, Go, JavaScript, Lua; fix, docs, refactor, review) through the real pipeline against any model, judged by code (does it parse, does a script that imports it still pass, did anything outside the target move, did it find the planted bug), never by another model. On the committed baselines Claude Haiku passes 100% of the single tries on the cases it was tuned on at roughly a tenth of Sonnet's cost per usable answer. Every model gets a capability profile (small, medium, strong): a smaller target limit, a second try with the reason when an answer does not parse, server-shaped output for Ollama and OpenAI, a chain of single steps for an instruction that is several things, and an optional cascade to the main model.
• You are told what is going to happen, and can take it back: the spinner carries the estimate, every proposal says whether anything checks it (checked on accept (LSP) or unverified), the statusline shows what the session has spent, <leader>au takes a whole run back across files (never what you edited since) and <leader>aSbu takes the last build back.
• Less on the menu: DDD, the repository/service/lens menus, the doctor, building a whole project and multi-file plans are experimental and stay hidden until agent.experimental (Settings → Agent) is on. Nothing was removed.
• Review stops crying wolf: it no longer reports a finding that says nothing is wrong, nor hypothetical misuse; on the eval, Haiku went from 82% to 100% on review without losing the real findings.

Features

• agent: evals, capability profiles, trust layer, experimental flag (3777b62)

Documentation

• agent: evals, profiles, trust layer and stability (4cef712)

[1.12.2] - 2026-10-21

Highlights

• Your nvim now speaks Herdr: Herdr is the terminal workspace that runs the coding agents, and Leader talks to its CLI. <leader>Wa opens the breakdown of the workspace: one row per agent grouped by workspace (its state, the agent and where it is), the transcript of the one under the cursor and why Herdr thinks it is in that state (the rule that matched). It refreshes on its own, so what is on screen is the state now. <leader>Ws is the setup: it detects the binary, the version, the server and the agents' integrations, and installs what is missing (nothing without the button) — the installer does the same, and the start screen gets an Agents button when Herdr is there.
• And Herdr sees what your nvim is doing: nvim registers itself as an agent of the workspace and says what it is doing (working while the inline agent runs, blocked while a proposal waits for you, idle otherwise), so the Agents panel of Herdr shows it. It never takes the pane from a real agent that already owns it, and a headless nvim (a script, a test) does not register at all.

Features

• herdr: the workspace of agents under <leader>W (135c337)

[1.12.1] - 2026-10-21

Highlights

• The code search index builds ~3x sooner and no longer freezes the editor: on a 4000-file TypeScript monorepo the first <leader>fs took 19-35 s with 12-22 s of blocked UI (stalls up to 1 s); it now takes 6-10 s with the UI blocked ~0.2 s. The files are read by up to 4 headless Neovims in parallel (settings.search.workers); the result is identical to reading them in the editor, which is still what happens for a few changed files or if a worker fails.
• Typing is smoother: nvim-highlight-colors repainted the window on every key while the completion menu was open; it now waits 60 ms. In a TSX file the per-key cost went from p95 8.8-9.8 ms to 6.1-7.5 ms (the frame budget is 16.6 ms).
• Less memory in big projects: Tailwind's server only starts where the project uses Tailwind (~210 MB less in the API of a monorepo), TypeScript is linted by the eslint server alone (eslint_d stays for light mode), and a server that outgrows settings.lsp.memory_limit_mb (vtsls: 2200 MB; it reached 2.9 GB in a long session) is restarted when you are idle. scripts/bench-project.lua measures all of this on any project.

Performance

• lsp: fewer resident servers, and tsserver cannot grow forever (44a781a)
• ui: highlight-colors repaints behind a 60 ms debounce (d1d39ba)
• search: the code index is built by parallel workers (08ddc7e)

Other changes

• chore(bench): a probe for a real project (5aa2719)
• chore(packaging): point the PKGBUILDs at v1.12.0 (3995f15)

[1.12.0] - 2026-10-20

Highlights

• Lua answers across files ~2.5x sooner: Lua now uses emmylua_ls (a Rust server) when it is installed, and lua_ls otherwise. On this repo's 670 files cross-file go-to-definition worked at ~0.7 s against ~3.8 s on the bare workspace, and ~2.5x sooner with the full config, with the same hover, completion and diagnostics. lua_ls keeps nothing between sessions and its maxPreload has no effect, so the way to speed it up was a faster server. Mason installs it with the rest; settings.lsp.lua_server forces either one.
• <leader>dr runs and stops a Flutter app: pressed again while the app runs, it quits it and closes the debugger and every panel that opened, instead of only saying it is already running.
• Your sessions are safe from tests: Neovim saves a session on every exit, and a headless test that opened temp files in a repo replaced that folder's real session with files that no longer existed, so restoring the project opened an empty buffer. Persistence now stays off without a UI, every test script runs against a throwaway state directory, and the whole suite leaves sessions, recent files, agent history and logs byte-identical.

Features

• dart: leader dr toggles run/stop (fffd15c)

Fixes

• sessions: tests and headless runs never write your state (db55542)

Performance

• lsp: Lua gets emmylua_ls when it is installed (~2.5x faster) (ccc1a54)

[1.11.0] - 2026-10-20

Highlights

• Big files stay fast: past 1.5 MB (or a minified bundle) a file opens as plain text, with no treesitter, LSP, folds, lint or formatter. A 4 MB Lua file opens in ~135 ms instead of ~1.9 s, and its first frame in the window matches a one-line file's.
• Saving never freezes: a buffer over 3000 lines is written at once and formatted in the background. A 15k-line save goes from ~1.2 s to ~20 ms. Linting is debounced, so a burst of Esc and saves lints once.
• Stop a language server that takes too long: <leader>L stops the servers of a buffer (also in the middle of "Loading workspace", in ~13 ms), stops all of them, restarts them, pauses everything, or says what is loading. A server that has not answered yet is found too. The editor cannot cache a server's workspace load, so this is the way out.
• Code search remembers: the index is kept on disk, so only the very first search parses every file (~5 s here); every later session loads it in ~120 ms. The first <leader>ff of a session is ~2x faster too.
• A cleaner, faster start: the window opens on the themed editor, never on a black frame, and the real editor reaches the screen ~45 ms sooner (graphics driver and Neovim start in parallel with the window, the first frame is warmed).
• leader --reuse file opens files in the window that is already running in ~6 ms, without a new window or Neovim. Opt-in; a plain leader is unchanged.
• Measure it yourself: make bench (startup, first frame, big files, picker, search index) and make bench-edit (big paste, undo, save, diagnostics, typing latency), with the findings and limits in AGENTS.md.

Features

• lsp: stop, restart and pause language servers (<leader>L) (ecaf792)
• gui: a full-screen theme picker (0770236)

Performance

• app: a faster, cleaner start and a window you can reuse (21d5427)
• editor: big files, saves, lint, search index, picker preload (c185df4)

Other changes

• chore(bench): make bench and make bench-edit, and what they found (859c6b9)
• chore(dev): a Makefile and a real-time loop for the app (09ebf01)
• chore(packaging): point the PKGBUILDs at v1.10.0 (5b5cf42)

[1.10.0] - 2026-10-20

Highlights

• Install it the way your system expects: a .deb for Debian, Ubuntu, Mint and Pop!_OS, PKGBUILDs for Arch and CachyOS (prebuilt and from source), the one-command installer for any Linux and WSL, and ./install.sh --app from a clone. They add the menu entry, the icons, the manual (man leader) and leader-setup, and uninstalling removes exactly what was installed.
• Signed releases: every file has a SHA-256 and a detached signature by the Leader Releases key (fingerprint in packaging/README.md). The installer requires a signature made by exactly that key when gpg is installed, and refuses a forged or missing one.
• The logo, clear: the N is the window icon, the menu icon at every size (a solid N when small, the dotted one when large) and the art of the About dialog. The app id is io.github.sazardev.Leader, so launchers pair the window with its icon and menu entry.
• First launch that explains itself: no Neovim says so in a notification; no Neovim config runs leader-setup in the window's own terminal. AppStream metadata, a New Window action, a license (MIT) and a site with Open Graph cards, structured data, a sitemap and real screenshots.

Features

• site: SEO, screenshots, install options for every system (eab5dbc)
• packaging: signed releases, a .deb and Arch PKGBUILDs (3ebec37)
• app: the logo everywhere, an app id, first-launch setup (035cbea)

[1.9.0] - 2026-10-20

Highlights

• Projects first, like an IDE: Leader asks which project to open when it starts (or reopens the last one, or shows the start screen: your choice), leader <folder> opens that folder, and starting inside a repo opens that repo. The picker keeps its facts and the list it found on disk, reads git in the background one folder at a time, pins projects (p), and a Yazi-like browser (b: h up, l in, Enter opens) walks your folders.
• Updates, connected: a ↑ 1.9.0 badge in the bar and a line at the top of the logo's menu when a newer version exists; a page shows what changed version by version and updates on request (the config with git pull --ff-only, the app through its installer). One tiny request, never more often than every 12 hours, never updates by itself.
• Recent files that belong to the project you are in, not everything you ever opened (Ctrl+A widens it).
• Esc closes whatever is extra: help, quickfix, panels, floats, pickers (from insert too), lone tabs; never the last window. The hidden cursor has one owner list now, so it can no longer stay invisible after pages overlap.
• Install progress in numbers: every language tool with its state, time, bytes and speed, a bar, and a warning when data stops arriving. The window remembers its size, place and maximized state; the frame is yours to pick.
• Speed: hovering never scrolls a list, hovers are coalesced, Telescope no longer leaks a buffer per open, streaming answers redraw at most every 40 ms, and a list that fails to open leaves nothing behind.

Features

• gui: projects first, a folder browser, install progress, Esc (e9ccc65)
• app: keep the window's size, place and maximized state (fd876ef)
• ui: one owner list for the hidden cursor, Esc closes extra windows (0157e10)
• update: detect new versions, show the changelog, update on request (3eac257)
• recent: recent files that belong to the project you are in (9ac6d49)

[1.8.0] - 2026-10-20

Highlights

• Guided setup in the desktop app: seven steps on one screen on the first launch (and with Ctrl+Shift+W). It shows what this machine is, lets you pick a theme previewed live, your languages (the ones you already use checked), a few features and an AI agent with its model, then lists what is missing with the exact command for your Linux family (pacman, apt, dnf, zypper, apk). Nothing runs until you press Install; sudo asks in a terminal and each item shows its status. A review with the install checks closes it.
• A toolbar you decide: a right click on the bar turns each tool and chip on or off (project, home, recent files, palette, file tree, terminal, problems, agent, theme, settings, setup). The theme and the agent are right there: a theme menu previewed as you hover, and every installed agent with its models. Every tool shows a tooltip with its key.

Features

• gui: guided setup and a toolbar you decide (aef5599)
• app: a customizable toolbar with tooltips (a5b7db1)

Other changes

• docs(gui): document the guided setup and the toolbar (48502be)

[1.7.0] - 2026-10-19

Highlights

• Leader for the desktop (Linux and WSL): leader, a GPU window for the editor written in Rust. The same config, drawn in one GPU draw call per frame, nothing running between keystrokes, ~170 ms to the first frame. Its own bar in the theme's colors: Zed-like menus (File, Edit, Selection, View, Go, Run, Git, Agent, Window, Help), a command palette (Ctrl+Shift+P), the projects you work in (switched with their sessions) and a full-screen project picker (Ctrl+Shift+O), the current file as a clickable path, live activity (LSP indexing, installs, saves). Full mouse: menus, pickers, modals, Telescope, the tree and the start screen follow the pointer and answer a click. A welcome screen checks the install and fixes what is missing. Install it in one command (curl -fsSL https://github.com/sazardev/leader/releases/latest/download/leader-installer.sh | bash: the app, plus Neovim and the config when they are missing; Linux x86_64 with glibc 2.31+, WSL with WSLg) or from a clone with ./install.sh --app.
• Doctor (<leader>aX): a troubleshooting agent for builds that fail, apps that will not start or crash. Free checks first (dependencies, lockfile, .env, toolchain versions, a merge in progress), then one confirmed request.
• Merge conflicts (<leader>Gx): trivial ones resolved for free, the rest one proposal per conflict.
• Language packs: Python, TypeScript, Rust, SQL, Swift, JVM and more as packs, with tests in the editor, project setup presets, debugging and a SQL runner. The installer asks once which packs you want.
• A full-screen marketplace for SPEC.md modules and STACK.md / DESIGN.md add-ons, and a bigger library of each.
• Leader is the new name (repo sazardev/leader), with a brand kit, wallpapers and a scripted product video.

Features

• app: release package with a guided installer (9cb78d4)
• gui: the config side of the desktop app (8c320ce)
• app: Leader desktop app, a GPU front-end for Neovim (f0ee3b0)
• site: wallpapers page, fed by a release of the brand assets (196b936)
• brand: logo, image catalog and wallpaper collection (602c5a7)
• video: scripted product video with keys, effects and score (9ec8b75)
• agent: doctor, a troubleshooting agent (4b23e52)
• git: merge conflict assistant (818657c)
• kit: full-screen marketplace and a bigger library (af08bb9)
• agent: statusline badge for one-shot requests (a2b18f9)
• languages: packs, tests in the editor, setup and SQL runner (4c6f2a1)
• agent: SPEC.md modules for what every app repeats (50e3da4)

Fixes

• kit: drop a stray local path from the design presets (9ced0ca)

Other changes

• docs(app): install and document the desktop app (fb4775e)
• chore(rename): rename my-nvim-setup to Leader (0a5425c)
• docs(agent): document the doctor, conflicts and marketplace (3a3e74a)
• docs(docs): list Go and Dart / Flutter under Languages (4270f1f)

[1.6.0] - 2026-10-19

Highlights

• Build by layer (<leader>aSb then t, s or d): the foundation from STACK.md, the domain from SPEC.md or the screens from DESIGN.md, each built on top of the files the project already has. bb still builds everything at once.
• Build one feature (<leader>aSbf): pick a requirement of SPEC.md, or describe a new one in your words; it is added to SPEC.md as the next FR-n (after a confirmation) and built end to end, following the patterns the code already uses.
• Recipes (<leader>aSr): twelve prefab tasks for your stack (a Flutter screen with its state, a data feature or a form; a Go endpoint, entity with its repository, CLI command or Bubble Tea screen; web components and pages; TypeScript, Python and Rust endpoints). Each is a plain Markdown file you can copy and adapt.
• Coverage (<leader>aSv, 0 tokens): which requirements have a test, what STACK.md names that the manifest lacks, DESIGN.md tokens no code uses, folders no document mentions.
• Decisions and progress (0 tokens): every accepted plan records its new decisions as ADRs in docs/adr/, which later builds follow (reversing one is explicit: Supersedes ADR NNNN); PROGRESS.md says what was done, what is open and what is next. <leader>aSP lists them.
• Release kit (<leader>GR): this changelog and the next version from the Conventional Commits (c), a pull request description (p, one light request, copied to the clipboard) and a release checklist from STACK.md (l). It never tags, pushes or posts.
• Flutter: run on a chosen device, profile mode, quieter runs. opencode 2.x CLI supported.

Features

• agent: layer and feature builds, recipes, ADRs, release kit (b2644fd)
• agent: support the opencode 2.x CLI (790cf02)
• dart: run on a chosen device, profile mode, quiet runs (b109513)

Fixes

• release: write other changes as the commit is written (8e93451)
• commit: force a/ b/ prefixes in the staged diff (e67396c)

Other changes

• chore(deps): update neoconf.nvim and nvim-treesitter (5abb9eb)
• test(agent): keep the backend detection test hermetic (573dec0)

[1.5.0] - 2026-10-18

Features

• agent: build look step, design screens and toolkits, live plan (cb319cc)
• agent: project kit (<leader>aS) and build with agent (43fe81a)

[1.4.0] - 2026-10-15

Features

• history: undo word by word, redo keys, clipboard and yank list (8b7c617)
• go: getters, Reconstitute, repository port and package ranking (8df42c8)
• dart: tests in the editor, entry points, pub and translations (3b93295)
• dart: debugging, build_runner watch and stack completion (1e51b98)
• agent: convert selection, smaller context, Dart support (1c441fc)
• setup: .gitignore from the project and Go config presets (eb0b24a)

Fixes

• docs: polish the docs site on phones and desktop (49838b4)
• theme: follow the terminal theme faithfully and live in every nvim (6b26a31)

Performance

• theme: terminal theme starts as fast as the default one (7a060db)

Other changes

• chore(deps): update schemastore.nvim (43b5e4d)
• docs: web documentation at /docs, generated from the Markdown (362660e)

[1.3.0] - 2026-10-15

Features

• tasks: run the targets of the project's Makefile from <leader>R (19d630d)
• agent: answer cache, next edit, diff-only docs and code search (47d3945)
• diagnostics: copy the line, the file or the project as text (2b6d1fd)
• files: create, rename, move, duplicate and delete from <leader>F (f6f0ecb)
• settings: a settings panel on <leader>S (217be6a)
• folds: fold code by what it is from the <leader>z menu (18863ae)
• terminal: Esc and Shift+Esc in NvChad terminals (7df03f4)

Fixes

• ui: modal buttons, filled rows and floats without a dark hole (77549d5)

Other changes

• chore(deps): update neoconf.nvim and schemastore.nvim (e131374)
• docs: settings panel, file operations, copy diagnostics and the tree (533f1df)

[1.2.0] - 2026-10-14

Features

• agent: agentic layer on top of the inline pipeline (68b0012)

Performance

• agent: warm opencode server, no MCP or thinking, cheap model list (42e435e)

Other changes

• docs(site): demo scenarios for the agentic layer (a841bfa)

[1.1.0] - 2026-10-14

Features

• agent: history in markdown with filters and back navigation (7391daf)
• ui: every view drawn like the landing page's demo (ee4615c)
• ui: which-key labels without the section the menu already says (377cd38)
• ui: commit panel bars, key hints as words, which-key grid (8dc4010)
• ui: start screen identical to the landing page's, compact popups (420d023)
• ui: optional key display like the demo's keycaps (:FlatKeys) (8b89b30)
• ui: flat design for the whole editor, same as the demo (1e4a33b)
• install: one-command install with bootstrap, no prompts (93b8bc4)
• install: ajustes por máquina y agente de IA desde el instalador (c3ca0f4)
• comments: plegado de comentarios con preferencia que se recuerda (3306c7a)
• diagnostics: colores unificados y número de línea con píldora (5c23cab)
• go: if err, mapeadores, cableado, enums, port y HTTP sin LLM (6a1eff6)
• go: completar los métodos que faltan para cumplir una interfaz (e5fe0d0)
• agent: pruebas (aT) y lentes (aL) con gasto mínimo de tokens (10dbc7d)
• commit: borrador de IA rápido y en inglés, y commit automático GM (ce388d1)
• agent: fix en dos niveles, en línea (af) y de bloque (aF) (e572dce)
• agent: limpiar hallazgos de uno en uno, por archivo o todos (f29532c)
• commit: panel único para commitear con validación e IA clara (e849ae6)

Fixes

• lsp: servers never attach to diffview:// and other virtual buffers (5fd444f)
• ui: telescope preview hit line and text chips without patches (f92969b)
• ui: files opened from the start screen lost their line numbers (0c6b3d2)
• install: run the agent setup without loading the user config (26676ba)

Other changes

• chore(plugins): update nvim-treesitter and schemastore (31da4dc)
• docs(site): agent scenarios drawn as Neovim draws them (204b017)
• docs(site): terminal-derived theme picker, menus from real keymaps (eaf2c98)
• docs(site): 41 demo scenarios in tabs: search, tree, replace, git, more (90d8974)
• docs(site): flat inspect floats, no border and no divider (b44dba3)
• docs(site): hover, signature help, diagnostics popup and completion docs (7147a7c)
• docs(site): faithful editor demo with multicursor, DDD and commit panel (9b8e9da)
• docs(site): scripted real-looking editor for the Go and agent demos (c1dd9db)
• docs(site): redesign the landing page flat, square and minimal (9a6e050)
• docs(site): single-file landing page in the config's own design (f56c5ea)
• chore: translate scripts, installers, hooks and tests to English (6aea6b9)
• refactor: translate code comments and UI text to English (1776927)
• docs: translate README, AGENTS, CLAUDE and cheatsheets to English (db1990f)
• docs(readme): README con todo lo nuevo y los principios de diseño (bb3faee)
• test(agent): más margen para gopls en frío en test-fix (ca8392d)
• refactor(go): gohttp separa lo de cada router y quita código muerto (e98ff23)

[1.0.0] - 2026-10-13

Features

• install: instalador de un paso para Linux, WSL, macOS y Windows (7d47d1f)
• agent: agente inline con DDD, niveles y modelos locales (9fa27fd)
• editing: commits convencionales, bloques de diagnóstico (3159950)
• session: autoguardado periódico y reapertura del pane en Herdr (7adaa22)
• dependencies: new (8a8ef31)
• ui: diagnósticos de la barra como etiquetas E/W de color y sin LSP (e74c296)
• go: atajos de archivos de modelo (functable, funcdomain, functodomain, funcfromdomain) (b969d7f)
• go: tags gorm con variantes por campo/tipo y TableName en *_model.go (d2aaefc)
• docs: cheatsheet único generado desde los keymaps reales (a5ea1a6)
• docs: new marketing slogan (4380500)
• docs: new marketing slogan (cb73724)
• dashboard: 66 arts braille nuevos (mascotas, anime, retro, comida) (3198ee1)
• docs: new marketing slogan (88e6e19)
• native search/autoread options, lazydev and git-conflict (7f14f7b)
• git: diffview (<leader>Gd/Gf/Gr/Gq) and treesitter-context (0ef25e4)
• session: persistence.nvim with dashboard Restore Session button and <leader>P menu (b16163d)
• options: jumpoptions=view, diagnostics severity_sort, restore last cursor position (63f7d5c)
• markdown: toggle diagnostics, reading mode, spell, word count, checkbox (d2665a9)
• docs: new marketing slogan (adf7b62)
• design: new ascii art for neovim! (1d899be)
• dashboard: add herdr braille art (da3d974)
• dashboard: braille art catalog discovered from lua/ui/arts, picker with "Change Art" (8b4657a)
• keymaps: native multicursor with Ctrl+Down/Up (visual block) (c854a30)
• nav: <Esc> goes back after gd/grr, <leader>H file history; fix <leader>q (8334e31)
• lsp: clear definition/references navigation (gd, grr, Ctrl+click) (413d00a)
• terminal: responsive integrated terminal panel for language menu actions (8efa087)
• theme: inherit the terminal (Alacritty) theme with live follow and <leader>S settings (c3e6412)
• keymaps: <leader>q closes buffer or quits nvim (a9d3dd1)
• funcs: new funcs (f063361)
• light mode, blink.cmp tab-complete, color previews; drop rest.nvim/lazygit (3e3622c)
• blink.cmp, harpoon, mini.move, drop sessions (98d62f5)

Fixes

• plugins: go.nvim y flutter-tools respetan languages.disabled (30c4a40)
• session: registro de nvim como agente de Herdr apagado por defecto (e9d8327)
• completion: Tab vuelve a elegir sugerencia con el menú abierto; Esc + Tab para saltar (a983fb5)
• completion: Tab salta de hueco en snippets y Esc/jk solo cierran el menú (beb23dd)
• dashboard: usa layout horizontal en el picker de arte (7e16d09)
• dashboard: re-lock nvdash buffer after resize (NvChad leaves it modifiable) (b10b2cc)
• telescope: defer require until display closure (1d1b556)

Other changes

• docs(readme): README nuevo con instalación, filosofía y estructura (c36b153)
• refactor(i18n): pasa a inglés los textos de UI (keymaps, menús, notificaciones) (8136b19)
• chore(lock): add persistence, diffview, treesitter-context and refresh plugin versions (fb79e18)
• docs: document sessions, diffview and treesitter-context in AGENTS.md (b49eae4)
• new art! (607c7ba)
• refactor: modular architecture, contextual leader menus, and config cleanup (f3f2dd1)
• refactor: trim unused plugins and keymaps, add global replace (73fb3d6)
• unify visual: single borders, zero icons, fix diagnostics (f1ebbad)
• docs for go! (e3719b4)
• Remove Copilot plugin and dependencies (5ceb0fa)
• Add Go tooling keymaps, fix treesitter highlighting, brighten gruvbox syntax colors (a8e5bb2)
• update config (c4f50b2)
• update config (81c1348)
• update config (2e53d5b)
• update config (b454716)
• update config (d9a5192)
• update config (1bd0135)
• update config (0227935)
• update config (dc6de83)
• update (33b096d)
• update chadrc (61586bd)
• update (53069e6)
• add AGENTS.md (f9a64be)
• update config files and README (7c45f1e)
• update config files (b4dba20)
• Initial commit (68e950e)

Features · docs/cheatsheets/agent.md

AI agent

One-shot actions on what you are looking at: a function, a class or a selection. No chat, no sidebar, no conversation. Every action has a closed prompt, a bounded context and an output with a fixed format, so it is predictable and cheap. Keys: CHEATSHEET.md (Agent menu).

Flow

1. Put the cursor inside a function (or select lines in visual mode) and press <leader>a + the action.
2. The code being sent is highlighted and a spinner turns on the right: ⠋ implement · claude/haiku · 1.2s. Requests with no code to paint (the project documents of <leader>aS, including the screens of <leader>aSw, the commit draft, the staged review, plans) show a badge in the statusline from any buffer: ⠹ drawing screens, then ✓ drawing screens (or a red ✗) for a few seconds after it ends. <leader>ax cancels them too.
3. The result shows up in the code, depending on the action:

The instruction field is inline (like the inline chat in Zed or VS Code): it opens right ABOVE the target code and pushes the code down instead of covering it, with an accent bar, a header (✦ implement · claude/sonnet) and a placeholder. It grows as you type (up to 6 rows), ⏎ sends, ⎋ cancels (also if you switch windows), ⌃J / Alt+Enter insert a line break and ↑/↓ (or ⌃P/⌃N) walk through the previous instructions of that action, which are remembered across sessions. In narrow windows the key hint shortens itself. There is no autocompletion or auto-closing of quotes inside.

Instruction: i, d, t and f open the field and Enter with an empty field runs without an instruction; if you type something, it is appended to the prompt and takes precedence over the default behaviour. Useful for an empty func main() {} ("read a CSV and sum column 3"), for an unclear function ("this validates orders before charging; the coupon case is missing") or to steer a fix. a ask and R refactor require the text; r review and e explain run instantly.

Short menu: i implement, d docs, t convert, n next edit, r review, e explain, a ask, f fix inline, F fix block, R refactor, g hand off (only inside Herdr), h history, m model (main, light and effort in a single selector), c clear (discards the finding on the line, or those in the selection in visual mode), C clear file (those in this file), x stop (cancels what is running and discards the pending proposals; it does not touch findings) and l last answer (reopens the last answer or rejected proposal). Everything that works on many pieces at once lives in its own Advanced menu, <leader>aA, so the everyday one stays short: a fix all, o / O fix from output / from a command, p plan across files, and for the proposals they leave waiting ] / [ next / previous, y accept all, l list. Accepting and rejecting a proposal have no menu entry: they are ⏎ and ⎋ on the proposal (and Tab refines it).

Accepting is a single change: u undoes it entirely. If you edit the code while the agent is working, the proposal is discarded instead of overwriting your change. Several actions can run at once (not on the same block).

Which target it takes

Priority: visual selection (always whole lines) > function under the cursor (with the contiguous comments above it, which are the spec) > class > paragraph of lines around the cursor (useful for a half-written signature: type func ParseConfig(path string) (*Config, error) and press <leader>ai). "Function/class" is the definition of af/ac (treesitter textobjects), for any language with a parser. More than context.max_target_lines (400) is rejected: trimming it would break the replacement.

Context (and why it is cheap)

Each action asks for providers; together they are capped at context.max_chars (8000 characters), the target is counted separately:

types is language-independent (it uses the same treesitter queries as af/ac): Go (struct, interface, alias), TypeScript (interface, class, type, enum), Python, Rust (a method of impl Note brings struct Note, not the impl), Java... A type in the same file is read instantly; one in another file or package is located with the LSP (textDocument/definition) and extracted from the destination file (project only, not dependencies). Field types are followed one level (Tags []Tag), and if the target is a class method, the class is included without the method itself. Cap: context.types (4) definitions of context.type_lines (30) lines. Each definition is compacted first (compact in providers/types.lua): full-line comments and blank lines go (context.type_comments = true keeps comments), and runs of bare enum values are joined, at most 24 shown and the rest counted (… (188 more)). Measured on a Flutter widget whose build uses two enums with a doc comment per value: the <types> section went from 3,243 to 871 characters. Definitions are never taken from generated files (x.freezed.dart repeats the class ~5x longer; utils/generated.lua).

Each action asks for what it needs, in priority order (if the budget gets tight, the last ones are trimmed):

Transparency (note:): after the code block the model may add note: ... (max. ~15 words) when it assumed or added something that was not in the context, and needs-import: .... Both show up in the proposal hint (note: Note has no Done field; assumed one) and are kept in the history. Measured in a test with SetDone without types: it guessed Done and Updated and said so; with types: the same code, with no warning, -70 % output tokens and -25 % cost.

Measured with Claude: a normal claude -p call drags ~46 000 input tokens (your plugins, skills, hooks and memory). With --setting-sources "", --tools "" and its own --system-prompt it drops to ~600 tokens (+ the context), about 2 s and fractions of a cent per action (haiku). The CLIs run in a neutral directory (stdpath("cache")/agent), so they do not load the AGENTS.md/CLAUDE.md of your repo either. That is why --bare is not used: it would break subscription login.

Cost audit (measured): every claude -p call was billed as a 1-hour cache write (up to 2× the input price) and never hit the cache, because the message changes on every call. With DISABLE_PROMPT_CACHING=1 (setting agent.claude.prompt_cache = false, the default) a Sonnet action went from $0.0065 to $0.0037 and a Haiku one from $0.0005 to $0.0003, with no change in latency. The system prompts were also shortened ~35 % (implement 1462 → 943 characters) and now state what is true (types, callees, diagnostics) and that whatever was assumed must be flagged with note:. In total, the same action costs ~50 % less than before the audit. About ~560 fixed input tokens from the CLI itself remain, which no safe flag trims (CLAUDE_CODE_SIMPLE and --bare break subscription login). agent.claude.max_cost_usd (0.25) cuts off a runaway call.

Order of the prompt (stable first, volatile last)

The sections reach the prompt arranged by each provider's stability: 1 the same on every call of the project (rules, testing), 2 changes only when the code does (types, outline, contracts, schema, ports, ddd, testfile, callees), 3 changes with the cursor or the editor (diagnostics, findings, around, callers, gitlog, changes, subject). The declared order still decides what survives when the budget is tight; only what is SENT is rearranged. What this buys depends on the backend:

• Ollama / llama.cpp / vLLM keep the KV cache of the last prompt and reuse what is identical from the start: a second action on the same code re-reads only the tail. For that, Ollama's num_ctx is now sticky per model (a small action after a big one keeps the big window, otherwise Ollama reloads the model and drops that cache).
• claude -p gets almost nothing from it: the CLI sends the whole message as ONE block and the fixed part is under the cache's minimum size. That is why prompt_cache stays off (measured: -40% per call); if you turn it on, <leader>ah shows cache_read/cache_write per run so you can check it pays. The answer cache is what makes repeated questions free there.
• A new provider declares stability = 1|2|3 next to its cap (default 2).

Models per tier (cheap where it is enough)

Each action runs on the main model or the light one. docs, explain and convert are light (Claude: haiku); the rest use the main one (sonnet by default). Measured with Claude, a single-function action: ~$0.005 on sonnet vs ~$0.0003 on haiku, about 17 times less, and the spinner shows the model that is running. Light actions do not inherit the effort either: they are the cheap ones and must not become expensive because of a setting meant for others.

• <leader>am opens a selector with the main model (and the backend), the light model and the effort, with their current value. Everything is remembered.
• Change which actions are light: agent = { tiers = { review = "light", docs = "main" } } in local.lua.
• agent.claude.light_model / agent.opencode.light_model set the default light model. In OpenCode both default to opencode-go/deepseek-v4.1-flash (ids depend on your provider: pick another in <leader>am).

Backend and model

<leader>am → Main model opens ONE fuzzy list with the models of all installed backends (Claude: haiku/sonnet/opus; OpenCode: the cheap, fast shortlist in agent.opencode.models, or whatever opencode models returns if that is nil). Choosing one also switches the backend and is remembered across sessions (stdpath("state")/agent.json). Effort (Claude only; --effort) is in the same selector. With backend = "auto" the first available one in agent.order is used.

• Claude Code (claude -p): no tools, no session on disk, text streaming.
• OpenCode (opencode run): each action travels as an ephemeral agent with no tools (OPENCODE_CONFIG_CONTENT). Your global MCP servers are turned off for these runs (agent.opencode.mcp = true keeps them): their tool schemas were ~20k input tokens and ~2 s per action. With agent.opencode.serve (default) a private opencode serve (free loopback port, random password, no MCP, stopped on exit, off in light mode) boots in the background and actions talk to its HTTP API with curl on a session created ahead: ~2 s per action instead of ~8 s. The first action (while it boots) is cold. The CLI line is detected (opencode --version): 2.x changes the inline schema (agents/system/permissions), takes the variant in -m provider/model#level, needs run --standalone (without it the background service, which never sees OPENCODE_CONFIG_CONTENT, answers and the requested agent is "not found") and has no --pure equivalent. Its warm path is off until opencode serve's v2 HTTP API is driven, so every action pays the private-server boot (~3 s measured on 2.0.31) and the run's JSON stream carries no usage events in our tests (the report shows tokens as —). In 1.x, models matching agent.opencode.no_thinking (default deepseek, haiku, minimax-m3) run with thinking off: deepseek-v4.1-flash spent 300-1400 reasoning tokens (4-15 s) on small functions; it costs some quality, {} turns it back on. It is per model because glm/cat-jam reject the parameter. (2.x has no such option: reasoning is chosen with the model's variants, effort in <leader>am.) The shortlist (deepseek-v4.1-flash, minimax-m3, claude-haiku-5-5, glm-5.3-flash, gpt-6-luna) was picked by benchmarking all opencode-go models on four graded tasks (two implement checked with go test, a review with a seeded bug, a review of clean code that must answer OK): 4/4, 1.4-3 s warm, ~$0.0002 per action. Haiku keeps requests 30 days; Gemini and Muse Spark train on prompts (left out). DeepSeek costs double at Peak (01-04 and 06-10 UTC, Mon-Fri). Only one run per task, so differences under ~0.5 s are noise. agent.opencode.attach points at a server of your own instead (--server on 2.x), but opencode run --attach printed no text in v1.19. agent.opencode.agent uses an agent of your own. If opencode does not find the requested agent it warns and falls back to the default one, which DOES have tools: here that is treated as an error.
• Each opencode session stays in its list: titled nvim <action> in the cold path, nvim agent on the private server.

Local backends and models (automatic setup)

Besides Claude Code and OpenCode, the agent talks to local models (Ollama on CPU or CUDA, LM Studio, llama.cpp, vLLM...) and to any other agent CLI (Hermes Agent, Gemini CLI, Codex, Aider). A setup detects and connects them.

Quick start

1. <leader>am → Setup (or scripts/agent-setup.sh from the terminal). It detects in parallel, without touching anything: the installed CLIs, Ollama and OpenAI-compatible servers (also the Windows one if you are on WSL: it tries 127.0.0.1, the nameserver and the gateway), their models, whether what is loaded runs on GPU or CPU, the VRAM/RAM, and it remembers the server it found.
2. Use detected models applies the recommendation with what you already have. If there are no models, it offers to Download a couple according to your memory (VRAM, or half the RAM without a GPU): qwen2.5-coder 32b/14b/7b/3b/1.5b. They are suggestions, you decide.
3. If Ollama is installed but stopped: Start Ollama server (ollama serve in the background). Starting and downloading are always requested explicitly: nothing is installed or downloaded by itself.

Terminal (scripts/agent-setup.sh; with no flags it only reports and exits with 0 if a backend is ready):

Example: scripts/agent-setup.sh --start --pull qwen2.5-coder:3b --auto.

The best of each tier: the main one stays on Claude and local models cover the light tier (docs, explain): light_backend (in <leader>am → Light model, or agent.light_backend) keeps those actions on a free local model without moving implement/fix/review. With no cloud CLI at all, the local one becomes the main one too.

Backends (all use curl, no dependencies):

• ollama: agent.ollama = { host, model, light_model, models, num_ctx, max_ctx, keep_alive, temperature, think }. The host comes from host > OLLAMA_HOST > what the setup detected > 127.0.0.1:11434. num_ctx is automatic (power of two depending on the prompt, capped by max_ctx): Ollama SILENTLY truncates whatever does not fit in its window and would lose precisely the rules at the beginning. keep_alive leaves the model loaded (the first action is slow, the following ones are not); temperature is low (0.1) because the required format is respected better. Cost is always 0. The <think>…</think> blocks of qwen3/deepseek-r1 are discarded.
• openai: agent.openai = { base_url, api_key_env, model, light_model, models, temperature } (LM Studio :1234, llama.cpp :8080, vLLM :8000, LiteLLM, OpenRouter...). The key is read from the api_key_env variable and travels through the process environment, not in the arguments (it does not show up in ps).
• custom (Hermes Agent, Gemini CLI...): a declarative entry in agent.custom, without writing code:

-- local.lua
return { agent = { custom = {
  hermes = {
    label = "Hermes Agent",
    cmd = { "hermes", "chat", "-q", "{prompt}" },   -- {prompt} {system} {model}
    system_in_prompt = true,
    model_flag = { "-m", "{model}" },
    models = { "hermes3" },
  },
} } }

The flags in the Hermes Agent example are not verified (the CLI was not installed when this was written): check them with hermes --help. Hermes models do work today through Ollama (ollama pull hermes3).

Pitfalls

• A small local model fails more often with the structured format (code block, L<n>|sev|msg): use it for docs/explain and, if you want more, move up to a 14b+ code model. Esc rejects malformed output as usual.
• Without a GPU the model runs on CPU: fine for the light tier; the report says whether what is loaded is on GPU, GPU+CPU or CPU.
• WSL2: to reach the Windows Ollama, set OLLAMA_HOST=0.0.0.0 there. In Docker with NVIDIA: docker run -d --gpus all -p 11434:11434 -v ollama:/root/.ollama ollama/ollama.
• The setup (and the terminal report) stores the servers it finds in agent.json (endpoints).

Handoff to Herdr

<leader>ag (only inside Herdr): you type the instruction, pick an agent from herdr agent list (those in this folder first) and file:range + diagnostics are sent with herdr agent prompt. With unsaved changes it attaches the current code. Use it when the task no longer fits in a single shot.

What the other agents of the workspace are doing is in the Herdr panel (<leader>Wa), and this nvim can say what it is doing to Herdr (see herdr.md).

Hexagonal architecture levels (one menu per level)

<leader>a keeps the generic ones (implement, review, explain, ask, fix inline, fix block, docs, convert, refactor, hand off, model, history, clear, stop, last). Each architecture level has its own folder (lua/agent/<level>/), its own action registry and its own menu, with its context and, in each one, a local 0-token analysis. The actions of each level run through the same pipeline (inline diff, findings, history and cost), and in the history they appear under their own name (repo_port, service_review, ddd_fix...).

The providers of each level (contracts, schema, ports, ddd) are silent if the code does not belong to that level, so implement/review/fix of the generic menu also receive them when applicable, at no cost when not. The shared code (searching with ripgrep, reading a type definition) lives in agent/discovery.lua, so levels do not depend on each other.

Repository (<leader>aP): persistence adapters

Implementing a repository (SQL, Postgres, MySQL, in-memory...) is long but mechanical, and the model needs what is not in the file you are looking at. The agent finds it by itself, without you mentioning files, and each piece arrives with its path:

• Port: the interface it must satisfy. It is deduced from the name (PostgresOrderRepository, pgOrderRepository, OrderRepositoryImpl, CachedOrderRepository → OrderRepository) and from what is declared explicitly (implements X, class T(X), impl X for T, var _ X = (*T)(nil)); it is located with ripgrep in any folder structure and read with treesitter.
• What is missing: it compares the port's methods with those the type already has (in Go, the functions with that receiver in the package) and also warns about the constructor. Only the missing ones are requested.
• Entity and types the port names (Order, with its fields and constants) even if the empty struct does not mention them: without this the model invents the fields.
• Sibling example: another implementation in the project (the one in the same folder is preferred) with the constructor and the equivalent method: this way it copies your structure, your error handling (fmt.Errorf("…: %w"), errors.Is(err, sql.ErrNoRows)) and your mapping.
• Schema: the entity's real table with its later changes and the dialect (from the schema syntax and from go.mod/package.json/pyproject/Cargo.toml/pom.xml), the access library and the parameter style. It is agnostic: with the same prompt, a Postgres migration produces $1 and ON CONFLICT, and a MySQL one, ? and ON DUPLICATE KEY UPDATE.

<leader>aPp (repo port) uses the type under the cursor (or that of its receiver, if you are inside one of its methods) and writes the type, the constructor and ALL the missing methods, in the port's order. <leader>aPi (repo implement) writes a single method with that context; implement (i/aDi) receives it too if the code is an adapter, and <leader>aPr (repo review) reviews what is specific to persistence (columns that do not match, dialect parameters, concatenated SQL, unclosed rows, unwrapped errors, N+1) and <leader>aPc (repo check, 0 tokens) compares the port's methods with those of the type and the entity's fields with the columns of its table. Silent if it does not apply: a service, a handler or any other function does not pay even for the search (measured: 0 characters of extra context).

Tested with Claude on an empty PostgresOrderRepository with a 4-method port: it returned the constructor and the 4 methods with the real columns from the migration, $1…, the error style of the sibling implementation and no invented fields (what it assumed, such as order.ErrNotFound, it states in note:), for ~$0.0013 with Haiku. Limits: the port is found by name or explicit declaration (not by type inference); the sibling example is the first reasonable one it finds; the schema is only read from *.sql and *.prisma (not from ORM models or the live database).

Service (<leader>aU): application services / use cases

A service can only call the methods that its ports declare. The ports provider finds the interfaces the service receives (fields, constructor parameters, method parameters, in any language) and reads them with their real signatures, each with its path and the instruction to call only those methods; with examples it adds another service of the project as a style example.

• <leader>aUi service implement: orchestrates the domain and calls ONLY the ports in <ports> with their exact names and signatures; business rules are called on the entity (not reimplemented); it propagates the context and translates the ports' errors.
• <leader>aUr service review: calls to port methods that do not exist or with wrong arguments, business rules in the service, leaking infrastructure details, swallowed or untranslated errors, non-atomic steps or steps ordered in a risky way (effects before saving), N+1.
• <leader>aUd service deps (0 tokens): for each port, which methods it declares, which ones this file calls and which ones the port does NOT declare (it would not compile), which implementations it has and whether any is wired (used outside its file); it lists what needs attention.

Tested with Claude: on a service that called orders.FindByID (the port declares ByID), deps detected it without an LLM and service review flagged it against the real port; service implement used only ByID, Save and Mailer.Send and called the entity's o.Confirm() instead of repeating the rule (what it assumed, such as a method the entity does not have, it stated in note:).

Findings that stay (and how to fix them)

The findings of review and ddd review, and the violations of ddd diagnose, are diagnostics pending attention: they are saved (stdpath("state")/agent-findings.json) and come back when you open the file in another session, even if you do not deal with them today.

• Each one is saved with the text of the flagged line. If the code has moved since then (you edited above, another branch...), it is relocated by that text (up to ±40 lines); if the line no longer exists, it is dropped with a warning (Agent: 1 saved finding no longer matches the code and was dropped). Saving the file updates the positions.
• Only the agent's are saved: LSP ones are not touched. If there is no findings file, opening a file costs nothing.
• Clearing them (from memory and from disk; review and ddd alike): <leader>ac clear discards the one on the cursor line (in visual mode, those in the selection) → one at a time; <leader>aC clear file, all those in this file; :AgentClear [file|all] (with a range: :'<,'>AgentClear), all = all files. <leader>aDc ddd clear, the DDD diagnostic of the whole project. <leader>ax stop does not delete them: it only cancels what is running and discards pending proposals.
• Fixing them: <leader>af (fix inline, the one on the line), <leader>aF (fix block, the whole function) and <leader>aDf (ddd fix) read the findings that fall in the function or selection, together with the LSP diagnostics, and propose the minimal change (in ddd fix, respecting the layers in <ddd>; if the fix needs a port, type or file that does not exist, it says so in note: and does not invent its content). When you accept the proposal, the findings in that range are considered resolved and also disappear from what is saved. review and ddd review do not read earlier findings: a new review must not start from what the previous one said.
• Flow: <leader>aDr (review) → tomorrow, another session: the diagnostics are still there → <leader>aDf on the function → ⏎.

DDD (<leader>aD)

A feature separate from the normal agent, with its menu, its action registry (lua/agent/ddd/) and its context. Same pipeline and same experience (inline diff, findings as diagnostics, window, history and cost, where they are distinguished as ddd_implement, ddd_review...), but the actions follow the layers and naming of YOUR project.

What the local analysis does (free, no LLM): it walks the project once (asynchronously, in batches; it only reads files inside layer directories and that are not tests; cached by mtime) and deduces:

• Layers by directory name (domain, application, infrastructure, interface and synonyms: usecases, adapters, persistence, api, handlers...; adjustable in settings.agent.ddd.layers). The dependency rule points inwards: domain ← application ← infrastructure / interface. Composition roots (main, cmd/, container, di...) may wire everything.
• Violations (◈ diagnostics in the code + quickfix list + panel): outward dependencies (with the exact import), frameworks in domain/application (database/sql, net/http, gorm, @nestjs, sqlalchemy, org.springframework... per language: Go, TS/JS, Python, Java/Kotlin/Scala, Rust, C#, PHP, Dart) and badly named files (PaymentService in pricing.go). Only the project's own imports are assigned to layers (go.mod module, relative ones in TS/Python, crate:: in Rust): database/sql is a framework, not "the database layer".
• Naming: file style (snake_case, kebab-case, order.entity.ts, PascalCase) and most used roles (repository, service, handler...), deduced from what already exists; suggestions for missing files respect it.
• Aggregates, gaps and connections: for each domain entity (a type with an ID field) it looks for its repository port, its implementation, whether it is wired (its name is used in some other file, via rg) and its use cases; it lists what is missing.

What the model receives (<ddd> section, max. 1800 characters, only what is relevant to that target): its layer and what it may depend on, project layers, naming convention with examples, neighbouring files, the pieces surrounding the entities it touches (Order: port OrderRepository (...) · impl PostgresOrderRepository (...) wired ✓ · use cases PlaceOrder), the violations in that file and a line with the idiom of the current language (constructors, errors, injection). Plus the DDD rules (~600 characters).

Measured on a Go project with one complete entity (port + implementation + use case) and another without a port: implement of Order.Confirm() used Pending/Confirmed (the constants of the Status type travel with it) and respected the layer; review found the *sql.DB and the concrete repository stuffed into the entity, plus primitives without invariant; missing listed the vertical slice of Customer with paths in the project's style. Each action, under $0.001 with Haiku. On a repo with 7500 code files, the first analysis takes ~0.9 s (252 layer files) and the next one 35 ms.

Limits: layers are recognised by directory name (if yours are named differently, adjust layers); "entity" is a domain type with an ID field; "wired" means "its name appears in another file", not a dependency-graph analysis; imports are read with regex and types with treesitter, so it is not a compiler. Languages without a treesitter parser only contribute imports.

History and spending (<leader>ah)

Every action is stored in stdpath("state")/agent-history.jsonl (append-only): when, action, model, target, your instruction, the system prompt, the exact message sent, the response, tokens (with cache read/write), cost, time and what you did with the result (accepted, rejected, discarded, N findings...). This way you can see transparently what was asked and what was paid.

• <leader>ah opens a selector with one row per run (date, outcome, action, model, cost, target); the title adds up the total spent. The preview shows the full detail rendered as markdown, including the code sent (the target and the code around it, highlighted in its language); ⏎ opens it large and ⌫ (BS) comes back to the list with the same filters, search text and run selected.
• ⌃F filters the history by agent (claude, opencode, ollama…), provider (who serves the model: anthropic, openai, local…), model, action, outcome or project: pick the dimension, then the value (each with its runs and cost). Filters stack and show in the title with the runs and spend that match; ⌃X clears them.
• ⌃S opens the spending report (⌫ comes back to the list): by period (today, 7 days, total), by action, by model, by day, cost per applied change, what was spent on proposals you did not apply, errors, cache hits, where the prompt goes (system, context per provider, target) and the 5 most expensive runs. It is the basis for deciding what to cut.
• ⌃Y copies EVERYTHING about the run as markdown (the same text you see in the detail): outcome and event line (accepted at 09:38:27...), target, time, tokens, cost, your instruction, the response, the system prompt and the exact message sent. ⌃P copies only the prompt (system + message) to reproduce or tweak it. In the detail panel and in the report panel, Y copies the whole panel. Everything goes to the clipboard (+) and the unnamed register.
• Privacy: the history includes your code (it goes inside the prompt). agent.history.store_text = false stores only metrics; enabled = false turns it off. It compacts itself to the max_entries (1000) most recent.

Refine: change a proposal without starting over

A proposal is on screen and almost right? Tab (settings.agent.keys.refine) opens the instruction field again ("how should it change?") and replaces the proposal with a new one that starts from the previous code: the model sees the original target, the proposal and only what you ask to change. The old proposal never touched your buffer; the history links the new run to it. Cost: about one ordinary run per round (your instruction is ~30 tokens, the previous proposal 100-300), instead of rejecting and describing everything again.

The same key on an answer (explain / ask window) asks the next question about the same code with the earlier questions and answers as the conversation (the oldest turns are dropped past ~4k characters). The answer window never takes focus, so while it is on screen the key is also bound on the code buffer you are in (it goes away with the window; a proposal waiting in that buffer gets the key back). Pressing it needs no <leader>al first.

After accepting: verification

Accepting a proposal is no longer the end. agent/verify listens to the replace presenter's events and, for free:

1. remembers the buffer's LSP and linter diagnostics before the code is written (the agent's own findings do not count: accepting resolves those);
2. waits until the language server settles (verify.settle_ms, never more than verify.max_wait_ms) and compares: a diagnostic is identified by what it says (source, code, message), not by its line, so the same old warning one line lower is not new;
3. nothing new → one quiet line ✓ verified · no new problems; something new → a question fix regression 1/2: it names the problems, the attempt, the model and the estimate. Yes launches a fix regression proposal over the function that holds them (same experience as any proposal, and verified again if you accept it); verify.max_retries (2) bounds the chain, verify.auto_retry = true skips the question (still bounded and still behind the spend guard);
4. a build check (verify.command = "auto": go build ./..., cargo check, py_compile, dart analyze of the saved file in machine format (only its errors count, never warnings); or your own per language) runs when you save the accepted code, because a compiler reads the disk. Only the errors on or next to that code are blamed on it; the rest of the project's errors are counted, not guessed at.

Tokens: 0 unless you answer yes; then about 1.8 runs per attempt (the original prompt plus the errors). docs is excluded (verify = false: only comments change).

Several proposals at once

fix all, fix from output and multi-file plans share one engine (agent/batch):

• One confirmation with the total (3 proposals · claude/sonnet · ~2.3k tokens · ~$0.0012, the files and how many problems each holds). The budget guard is not asked again per piece, but a hard cap still stops the rest.
• The pieces run one by one; the statusline says ⠋ agent fix all 2/3. If you cancel (<leader>ax) or the budget blocks one, the rest does not go on.
• Each piece is anchored (an extmark), so accepting something above it while it runs does not misplace it.
• The proposals wait in a queue: <leader>aA] / <leader>aA[ jump between them across files, <leader>aAl lists them in the quickfix, <leader>aAy accepts them all after one question (each is its own u). Each proposal's hint ends with 2/4 · <leader>aA] next.

Fix all (<leader>aAa) groups the file's diagnostics by the function (else the type) that contains them: three findings in one function are one request. Sources and severity: settings.agent.fixall (agent findings, DDD violations, LSP/linters; warn and up by default). Tokens: about one fix block run per affected function (5 findings in 3 functions ≈ 3 runs).

Fix from output (<leader>aAo): the errors come from the last terminal buffer, else the quickfix list; <leader>aAO asks for a command (the project's build by default), runs it and uses what it prints. They are parsed by Neovim's own errorformat (go, tsc, cargo, python, javac, flutter analyze, dart analyze (human and --format=machine) and the generic file:line:col: message), 0 tokens; each piece sends only the errors of its function (<build_errors>), not the whole output. At most settings.agent.errors.max_errors (20) errors are read.

Multi-file plans

<leader>aAp on a type or function, then what should change ("add a Done flag to notes, through every layer"):

1. Free: where it reaches. Language-server references (completed with git grep when the server never leaves the starting file), collapsed to the declarations that hold the symbol (function or type, with its first line as the signature), capped by settings.agent.plan (max_files, max_sites).
2. One request: the instruction and only those signatures (never bodies; ~40 tokens per site) go to the model, which answers ordered steps n|path|symbol|what. Steps that name a file or symbol that is not in the list are dropped (the model inventing them).
3. You: the plan panel (☑ 1. path · Symbol — what). Space unchecks a step, a all/none, Enter runs the checked ones, q cancels. Its first line keeps the estimate up to date as you toggle.
4. One request per step, in order: each is a proposal for its declaration, with the overall plan (this step marked) and what the steps before it proposed as context, so step 3 uses the field that step 1 adds. They land in the queue above and are verified as you accept.

A snapshot (git stash create, nothing in your work tree changes) is taken first: git diff <ref> shows everything the plan changed and git checkout <ref> -- <file> restores a file. Renames are better done with LSP rename (deterministic, 0 tokens); the plan is for semantic changes. Tokens: plan ≈ 1-2.5k in, 300 out; each step ≈ 1 run; a 5-step plan is about 6 runs in total.

Spend guard

Before every request (actions, batches, the staged review, plans) the budget guard (agent/guards/budget.lua, pure core in agent/budget.lua) checks the size of what is about to be sent (characters ÷ 3.5 ≈ tokens) against settings.agent.budget and what the history says you already spent. The price of a token is learned from your own history with that model (no price table). Above confirm_tokens / confirm_usd, or near a cap, it asks (modal with the reasons); a used-up day_usd / session_usd blocks. Every one-shot call (commit draft, staged review, plan) is recorded in the history too, so the spend is complete. The usage report (<leader>ah → ⌃S) gains a Budget line and Suggestions: actions you accept rarely (and what they cost), the share of the spend that went to proposals nobody applied, and how often the verifier had to retry.

Review before committing

<leader>Gv (or ⌃R in the commit panel) reviews what is staged:

1. Free checks on the added lines: secrets (AWS/GitHub/Slack/OpenAI-style keys, private keys, password = "…" literals), merge-conflict markers, debugger/print leftovers per language (not in tests) and sensitive files (settings.git.commit.sensitive).
2. If there is real code to read (not only lockfiles, generated files, deletions or binaries) one request goes out with the staged diff numbered by its lines in the new file (+L13 added, L12 context), within git.commit.review_max_chars. A finding must point at one of those lines or it is dropped as invented.
3. Findings land as diagnostics on their lines (open files at once; the others when you open them: they persist like any finding) with source staged review, and as a quickfix list. The panel's agent line says review: 2 findings (quickfix).

Tokens: a typical commit (40-200 changed lines) is ~1.5-6k in and 100-600 out; a docs-only or lockfile-only commit costs nothing.

Context for refactors and explanations

Two providers that are opt-in per action (they cost tokens): callers (refactor, the api lens): who calls the target, from the LSP references, one short line each (path:line code), at most context.callers (6) and two per file, so a refactor sees how the function is really used before it changes a signature (~60 tokens each). gitlog (explain, review, refactor): the last context.gitlog (3) commits that touched those lines (git log -L), one line each (~40 tokens): the "why is it like this" and "this was fixed before".

Project conventions: .agent.md

An .agent.md at the root (or further up) is added to ALL prompts: style, preferred libraries, what to avoid. Max. 1500 useful characters. Example: Idiomatic Go; errors with %w; no logs in pure functions; tests with testify.

Next edit (on demand)

Not autocomplete and not ghost text: one key press (<leader>an) asks the light model (a small local one through light_backend is enough) for the edit you are about to make. What it sees: the lines around the cursor (settings.agent.next_edit.window, 30 each side) and <edits>, your latest changes in this file as -/+ hunks, oldest first.

• The changes are tracked by agent/edits.lua: a baseline snapshot per file buffer, compared with the buffer when an insert ends or a normal-mode change settles (one vim.diff; no model, no LSP, files over next_edit.max_lines are not followed). It keeps the last keep hunks and sends at most max_chars of them (the newest win).
• With nothing changed in the file it asks nothing (0 tokens, and says why). If nothing in the window clearly follows from your changes the model returns the window unchanged and you get "no changes".
• It is a normal replace proposal: inline diff, ⏎/⎋, verification after accepting, history. Not cached (a proposal on live code).
• Why on demand: a streaming ghost-text subscription spends tokens on every pause; this spends them only when you ask.

Answer cache (repeated questions are free)

A request is identified by everything the model would receive: system prompt, file, context sections, target, task, your instruction, plus backend, model and effort (agent/cache/, pure logic in cache/core.lua). If the same request was answered before, the stored answer comes back with 0 tokens, before the budget guard (nothing to ask about), and goes through the same presenter (the status line says cached · 0 tok · saved $…). A hit is not a run: it never appears in the history (<leader>ah) or the spend report, since no model was called. Any change to the function, to a type or diagnostic it reads, or to your instruction changes the hash, so a stale answer cannot come back.

• Kept by default: text and findings outputs (explain, ask, review, lenses). A replace proposal is never cached: asking again on live code should give a fresh one. An action can opt in or out with cache = true|false.
• Stored in stdpath("state")/agent-cache.json; the least recently used go past max_entries, and answers expire after ttl_days.
• <leader>aAk shows what the cache holds and has saved you (answers kept, times it answered, tokens and money saved: counters the cache keeps itself) and has a Clear button. settings.agent.cache.enabled = false turns it off.
• Tests must never share the real cache (a hit hides the call they count): K.fake() points it at a temp file.

Project documents (<leader>aS): AGENTS.md, STACK.md, DESIGN.md, SPEC.md

The documents every coding agent (Claude Code, Codex, Cursor, opencode, this one) reads before it changes code, written at the repository's root in the same sections in every project, so an agent always knows where to look. Lowercase keys use presets or the project's own facts; uppercase ones take what you describe in your words and the model writes the document.

Customize is one list in groups, merged into STACK.md without a model (rows replace the row with the same first word, rules and commands are added once, so applying twice changes nothing). It opens with the best picks for that stack already checked (an add-on's <!-- default: … -->: in a one-of group the most specific match wins, the stack itself over its language over its category), so Enter alone gives a complete setup; change or uncheck what you want. Round marks (●/○) are one-of groups, squares (■/□) take any number. Only the add-ons that fit the stack are listed (its main language is read from the Stack table, so a Go API is never offered TypeScript tools).

The customize step is a full-screen marketplace too (the same keys): the choices by group on the left (●/○ one-of groups, ■/□ any number), the add-on under the cursor on the right (what it is and what it writes: its Stack rows, conventions, commands, rules), and under both what the choice sets (sets the rows Database, Auth…). p shows exactly the text the document would gain, Space picks (in a one-of group the others go off), ⏎ goes on, Esc goes back, / filters, Tab folds a group, ? lists the keys. <leader>aSk opens it on an existing STACK.md and <leader>aSK on an existing DESIGN.md.

Esc goes back one step (Principles → Customize → stack → kind of project; in T, Customize → the page with what you wrote), keeping what you chose; Enter moves on. Only the first step's Esc closes.

DESIGN.md customize works the same way (best picks checked, Esc back), with its own groups:

A terminal design is a real DESIGN.md for a TUI: colors as ANSI 16 / 256 / truecolor roles with fallbacks, typography as monospace cells and glyph sets, spacing in cells, borders as box drawing, motion as frames.

The build (b…) is an orchestrator you can watch, steer, leave and come back to. It builds the whole project (bb) or one layer from the document that describes it, with the same letter that document has in this menu:

A layer is built on top of what the project already has: the plan request gets the existing files as <project> (their paths, the manifests whole, the API the code declares), every file request sees that API and the existing files it uses, and an existing file the plan has to change (the domain adds a dependency to go.mod, the design makes main.go open the screens) is sent as it is and comes back whole. The review shows those as replaced. Usual order: bt → bs → bd, each reviewed before anything is written; any of them alone works too (a domain on an empty folder plans its own manifest). Each layer keeps its own saved run and its own list of the files it created: a replan of the domain only drops the domain's old files, X sends only the files that layer created to the trash (the ones it only changed stay), and the foundation's run is never touched by the domain's. The tab's top line and the statusline name the layer (domain · from SPEC.md, ⠹ build domain 3/9).

One feature at a time (bf): after the first build, most work is a new feature. The picker lists the requirements of SPEC.md with whether a test proves them yet (the preview opens SPEC.md at that requirement), and ＋ new first:

• An existing one opens the feature build with that requirement's text: its line to the next requirement, plus every other line of SPEC.md that names it (its edge cases, its open questions).
• A new one: you describe it on the draft page in your words; one request (main tier, SPEC.md as context) turns it into a requirement (title, "The system must…", 2-6 Given/When/Then criteria, edge cases, the questions only you can answer). A confirmation shows it; Add and build writes it into SPEC.md in the document's own style (heading ### FR-n: or bullet - **FR-n**, the next free id), its edge cases under ## Edge cases and its questions under ## Open questions (numbered on from the last Qn); the old SPEC.md goes to the trash.

The feature build plans the smallest set of files that makes the requirement work for the user: the domain it needs, the interface that reaches it (when there is one), the tests of its acceptance criteria, following the patterns the code already uses (same folders, naming, state management, error handling), on top of the project as it is (<project>, like the layers). Existing files it changes come back whole and keep what the rest uses. The wiring check and the use phase run, with scenarios from that requirement alone. Features are additive: one feature's replan or clean never touches another's files. One feature run is kept at a time; picking another requirement starts afresh.

SPEC.md modules (m, 0 tokens): your SPEC.md stays yours (you write the core of your business); the modules add the well-known parts you would otherwise forget. It opens as a small marketplace on the whole screen: the modules by group on the left (□ not picked, ■ picked, + comes with what you picked, ✓ already in SPEC.md), the one under the cursor on the right (what it is, its requirements with their criteria, edge cases, and the questions that are yours), and under both what SPEC.md would get from your choice (the modules, the FR range, the counts, what came in because another needs it). Nothing is written until you add, and the confirmation sums it up first (the old SPEC.md goes to the trash; cancelling it brings you back to the marketplace as you left it).

• List: j/k move, Space picks, ⏎ reads and customizes, p shows what SPEC.md gets, / filters by name, description, key or requirement title, {/} jump between groups, Tab folds a group (on a folded title it unfolds it), h hides what SPEC.md already has, t / d open the STACK.md add-ons / DESIGN.md patterns it goes with (below), A adds, ? lists every key, q closes. ★ marks a module your SPEC.md already talks about without having it (a word of its name or one of its requirement titles appears in the text: 0 tokens), and its pane says which word.
• Read and customize (⏎): j/k scroll, Space keeps or leaves out the requirement under the cursor (its edge cases and questions go with it; leaving every one out drops the module), Esc/h back to the list.
• What SPEC.md gets (p): exactly the text that would be added, as it would read, with what you left out missing; Esc goes back.

How a module goes in:

• Each requirement gets the next FR-n in SPEC.md's own style (heading or bullet) with its Given/When/Then criteria; its edge cases go under ## Edge cases and its questions under ## Open questions (numbered on from your last Qn), tagged with its id.
• Questions, not invented rules: lockout limits, roles, taxes, grace periods… come as questions; the build's plan decides them explicitly until you answer.
• A requirement you already wrote (same title, any case or punctuation) is kept as you wrote it, and the module's edge cases and questions for it are tagged with your id.
• needs: pulls what a module builds on (subscriptions → payments → accounts, needs first) and the confirmation says so.
• <!-- module: accounts --> marks where a module went in: applying it again adds nothing. Nothing is ever removed.
• Then each new requirement is a ○ in bf (build it) and in the coverage (v).

Modules are plain files in agent/kit/presets/spec/<group>/ (## Requirements with ### Title, "The system must…" and criteria; - [Title] … edge cases and questions; <!-- needs: … -->). They are also in the library (/), where the search looks at their requirement titles too (refund finds payments).

Starter kits open the list of the marketplace: a product type as a set of modules (SaaS for teams, marketplace, online store, internal tool, blog, booking, community, support desk, API product, consumer mobile app, project tool, forms and surveys). Space on a kit picks all its modules (◧ = some picked), ⏎ goes to the first one, and its pane says who it is for, what it adds and the decisions to take first. They are files too: agent/kit/presets/spec-kits/<id>.md with <!-- modules: key key … -->.

Narrow terminals (under 100 columns): the list and the pane take turns on the whole screen: ⏎/l opens the pane, Esc/h gives the list back.

What a module goes with: every module (and kit) names the STACK.md add-on axes and the DESIGN.md screen patterns it pairs with (<!-- tech: auth email -->, <!-- design: forms auth-screens -->), shown in the pane under "Goes with": accounts → Auth, Database, Email · Forms, Auth screens. The names are the library's own (<leader>aSt / <leader>aSd customize steps), and a test checks every name exists. In the marketplace t opens the STACK.md add-ons over it (the groups that go with what you picked marked ★, the cursor on the first; with nothing picked it uses the module or kit under the cursor) and d the DESIGN.md add-ons with those screen patterns already checked; closing them puts you back in the marketplace with your picks. They need a STACK.md / DESIGN.md in the project. DESIGN.md has a new group, Screen patterns (forms, data tables, empty states, onboarding, settings, navigation shell, toasts, dialogs, command palette, search and filters, dashboards, auth screens, pricing and checkout, comments, file upload, notification center).

Recipes (r): prefab tasks, plain Markdown files in agent/kit/presets/recipes/<group>/ (add your own: the header of the presets plus one <!-- input: key | question --> line per value, and a body with ## Make, ## Rules, ## Tests using {{key}}, {{key_snake}}, {{key_camel}}, {{key_pascal}}, {{key_kebab}}). Only the recipes whose for: fits STACK.md are listed (go+server = both, go+!server = a Go project that is not a server). Picking one asks its values, fills it and opens the recipe build: the recipe says what to make, STACK.md and the existing code say where and how (its paths are only a hint when the project already does it differently). Recipes skip the wiring check and the use phase. They are also in the library (/).

Coverage (v, 0 tokens): a report in a split, read from the documents and the code:

⏎ opens the place a line is about, r reads again, q closes. Ask tests to name the requirement they prove (// FR-3: …): the builds' tests do.

Records (0 tokens, settings.agent.kit.build.adr / .progress):

• Decisions (docs/adr/NNNN-title.md): when a review is accepted, the plan's decisions that no earlier ADR records are written as one ADR (Status, Context, Decision, Consequences: the files created and changed) and indexed in docs/adr/README.md. A build that decides nothing new writes nothing. Every later plan follows them: the decisions still in force go to the plan request as <decisions> (oldest first; the newest kept past ~4000 characters), and the plan lists only new choices. When a build truly must reverse one, the plan says so as a decision of its own (Supersedes ADR 0002: Bloc for state because …): its ADR's Status says supersedes ADR 0002, the index marks 0002 superseded by 0005, and 0002 is no longer sent to plans. An ADR is never edited. The feed's plan line says how many it followed (follows 3 ADRs).
• PROGRESS.md at the root, rewritten whenever a run settles: Now (the last build, how it ended, how to resume it), Done (a log, one line per finished build, kept across rewrites), Open (files not written, failing checks, issues the use phase found, SPEC.md's open questions), Next (the requirements no test proves yet). Any agent reads it to go on where the last one stopped.

Both are linked from AGENTS.md's "Read first" the first time, and neither is ever read as code by a layer build.

What a build may claim, and what it may throw away (agent/kit/build/proof.lua, loss.lua, kit/decls.lua; all free, no model). Checks are compilers and unit tests: they say the files agree, not that SPEC.md is delivered. So the closing line says what is proven. A build of the whole project, a feature or a recipe ends ✓ built only when every requirement has a test that names it and nothing is open; otherwise ◐ built · 23 files · checks pass · 5/17 requirements have a test · core without one: FR-16 · 2 placeholders. A requirement is core when SPEC.md's Goals cite it (FR-1 to FR-15 ranges included) or its line says (core). A placeholder is code that says it is not real yet (TODO, UnimplementedError, todo!(), "placeholder", "coming soon"; an input's own placeholder= attribute, tests and generated files are not). A layer build (foundation, design, domain) reports the same numbers but keeps ✓, because one layer cannot meet most requirements. Also in the line: a requirement that had a test before the build and has none now, and the public declarations of the files the build rewrote or deleted that are gone. PROGRESS.md gets a Proof line under Now and every item under Open. settings.agent.kit.build.strict = true makes such a build end ✗ incomplete instead.

• Deleting code asks. The files a replan drops are inventoried before anything goes to the trash (lines, public types, tests and which requirements they name, who still uses them). The review screen says so (⚠ deletes 2,591 lines and 9 public types), and when what goes holds a real declaration or 60+ lines, ⏎ opens a confirmation with the list first. <leader>Fu still brings them back.
• A whole-project build sees the code that is there. <leader>aSbb over a project that earlier builds left code in used to plan from the documents and the ADRs' text only, and wrote the code a second time under other names (two ProjectRepository ports, two timeline_view.dart: 364 analyzer issues). Now the plan request carries the project's files and the API they declare, and is told to use exactly those names and to merge duplicates instead of adding a third.
• A type is declared once. Every project gets a free check, no type is declared twice: a public type (class, interface, struct, trait, enum) in two source files of the same language fails it and goes to a diagnosis (Go: per package; tests, generated code and tool scaffolds do not count). Flutter/Dart projects also run flutter test (a project with a test/ folder), and Rust projects with tests/ run cargo test: "it analyzes" was all that was checked.
• Plans name the risk and defer honestly. The plan lists risks (the hardest requirements, riskiest first; the real path through the first is built right after the manifest, before the layers that only present or store) and deferred (what this build cannot deliver, and exactly what is missing). The review shows ⚠ for a requirement the plan neither builds, wires nor defers, for a file that stands in for a core requirement, and for a plan that names no risk. These are warnings for you to read, not a reason to ask for a second plan. (Building the risky path first as a verified skeleton before the rest is not enforced: it is a rule in the plan prompt that the warnings check.)

• The tab: on the left the phases as chips (done ones green, the current one with a spinner, the next ones faint), the progress bar, then the files (the one being written on a full-width band, like the agent's inline target) and the checks; models and documents only before it writes. The code (c shows/hides it) and the feed (f) on the right; with both hidden only the list advancing is left (settings.agent.kit.build.view sets which panes it opens with). The statusline of the tab is its own (a lualine extension): the phase as the mode chip in the color of how it stands (red failed, yellow stopped, green done), the keys of the moment (as many as fit, most useful first), then progress · money (and cache · time when the screen is wide).
• Reading and moving: z puts the code pane alone on the screen with the cursor in it (the plan, a file, a request) and z again brings the panes back; l hides or shows the files, c the code, f the feed; Tab / Shift-Tab move the cursor between the panes; P shows the plan (plan.md, rendered) at any moment.
• Start over: n plans again right away (the files of the old plan stay; the new review says which it replaces and which leftovers go to the trash). X cleans the build after a confirmation that lists them: every file it wrote goes to the trash (<leader>Fu brings them back), empty folders it made are removed, the saved run is forgotten; the four documents are never touched.
• Nothing is lost: the run is saved after every step. Closing Neovim with a plan in review and running <leader>aSbb (or the layer's key) again brings the review back with the plan on screen; a run stopped mid-write continues from the first file not written.
• Leave it running: q closes the tab, the build goes on; the statusline shows ⠹ build 7/25 · $0.031 from any buffer, a notice says how it ended, its key (<leader>aSbb, or the layer's) brings the view back exactly where it is.
• Resilient: the run is saved after every step (state dir, per project). Closing Neovim mid-build and opening it again offers to continue from the first file not written; the spend so far is kept.
• Transparent: money, tokens in/out, the share read from the cache and the time, live; per file its lines and cost; p shows the exact request (system prompt and message) a file was written from; every request is also in <leader>ah.
• Clean answers: a model that wraps the file (a fence with a sentence around it, the prompt's<file>tags echoed, tool-call markup leaking from the CLI, "I'll make the file…" before the code) is cleaned before anything is written; when it is still not a file (Go withoutpackage`, JSON that does not parse, markup left) the request is asked again once with the reason. A broken fix never replaces a file that was a file. Each of these used to cost a full fix round.
• Cheap: every file and fix request shares ONE system prompt (all four documents + the plan), so the backend caches it once and every later request reads it at a tenth of the price (measured with claude/haiku: ~20k of ~25k tokens per request from the cache); the message carries only the file's focus, the API of what exists and the files it uses.

Checks (never commands written by the model): Go go mod tidy · gofmt (fixes itself) · build · vet · test; Node/Bun package.json has STACK.md's tools (Vite, Vitest, TypeScript, Biome… named in the Stack table) · install (the package manager STACK.md names when there is no lockfile yet) · every id the code looks up exists (HTML vs getElementById, querySelector('#…'), *_ID constants) · every control the page declares is handled (a data-action/data-key/data-op name such as equals that no script handles: the button does nothing while every unit test passes) · every stylesheet and module is used · tsc --noEmit · the lint (Biome/Prettier fix format themselves), build and test scripts; Python uv sync · compileall · ruff · pytest when declared; Rust, Dart and Flutter their build/analyze. A Go module version the model invented (invalid version: unknown revision) is dropped with go mod edit -droprequire and go mod tidy writes the real one (0 tokens; go.mod is asked without a require block, and the plan never lists files tools generate: goldens, lockfiles, build output). Formatters (gofmt, Biome, Prettier) run again after every fix round. Missing golden files (snapshot tests run for the first time) are created by running those packages' tests with -update (no tokens; review testdata/*.golden), then the checks run again. A build is done only when every check passes; otherwise it ends failed with the fix rounds it tried.

Measured fix (claude/haiku): ascii-calc's keypad opened on "7" so Enter typed a 7 and three UI tests failed; the diagnosis named keypad.go (not in the errors), one fix there, tests untouched, every check green: 2 requests, $0.008.

Measured on two projects (claude/haiku): a 25-file Go TUI and a 23-file Vite + TS 7 + Bun web app each cost about $0.08–0.10 in total, documents, plan, files, checks and fix rounds included, in 7–8 minutes. Known limits: the use phase reads screens as text (terminal cells, the accessibility tree and measured layout, the Android hierarchy): colors and pixel-level looks still need your eye (the screenshots are kept for that); native desktop toolkits (GTK, Qt, Flutter desktop) and iOS have no driver; library APIs the model knows badly can be invented (a fix round usually repairs them).

Principles are presets too, appended to STACK.md as ## Engineering principles (one ### each): SOLID, Clean Code, one file one responsibility, hexagonal, testing, error handling and security are checked by default; Clean Architecture, DDD, Twelve-Factor, observability, API design, performance, functional core, accessibility, git workflow and documentation are one Space away. The model writing a STACK.md only gets their names (to keep the layout consistent); their text is the preset's.

• Never in silence: a document that is there is replaced only after a yes, and the old one goes to the trash (<leader>Fu brings it back). A file with unsaved changes in a buffer is never written under.
• The page (s, D, T) is a Markdown float: :w or Ctrl-s sends it, q closes it; what you wrote is kept for the session, so closing it or a failed request loses nothing.
• Linked: creating STACK.md, DESIGN.md or SPEC.md adds its line to AGENTS.md's "Read first".
• Language: the documents are written in settings.agent.kit.language (English by default) whatever language you write the description in: the model translates it and keeps names and domain terms. Measured with Haiku: Spanish drafts came back fully in English (they came back mixed before the rule was moved to the end of the request).
• Facts vs choices: AGENTS.md and SPEC.md never invent (a gap is a TODO: or an open question); STACK.md and DESIGN.md are choices, so the model makes them, marked (proposed) with the reason, and keeps TODO: for what only you know.
• Commands come from what the project declares: the Makefile's targets first, then the lockfile's manager (npm/pnpm/yarn/bun, uv/poetry/pdm/pip, Go, Flutter/Dart, Cargo, Maven/Gradle wrappers, Swift, Deno, Composer, Bundler) and only the tools a manifest names (no pytest or ruff guessed).
• Cost: the model ones run once on the main tier (kit_agents, kit_stack, kit_design, kit_spec, reassignable in settings.agent.tiers), through the spend guard and into the history (<leader>ah); presets and A/c/p cost 0 tokens.
• Your own presets: drop a Markdown file in lua/agent/kit/presets/design/, stack/<category>/ (a new folder is a new category), addons/<group>/ (<!-- for: ts web --> says which stacks it fits: tags from the stack's words, presets.tags) or principles/, starting with <!-- name: … --> and <!-- desc: … --> (<!-- core: true --> checks a principle by default). scripts/test-kit.sh checks every preset has its document's sections.