agent-fleet.nvim

Run a fleet of coding agents from Neovim — pi, Claude Code, or
any agent CLI — each in its own native terminal, listed and switchable from a
clean board.

Inspired by claude agents, but with one hard rule:

The agent runs as its real CLI, in a native nvim terminal. Nothing
reimplements the agent's UI.

So the whole conversation lives in a buffer you can scroll, search and yank with
your own keybindings.

Features

• Launch agents into a native terminal, with an optional initial prompt.
• Persist & resume — a roster on disk; reopen a past agent (focus it if
  live, else relaunch it via its CLI's resume flag in its original cwd).
• List & switch the agents of the current directory, live ones merged with
  on-disk sessions (pi and Claude) and deduped.
• Live board (:AgentsBoard) — a dedicated buffer grouping agents into
  running / idle / done / archived sections, with colored state and relative
  last-activity times, refreshing on a timer.
• Lifecycle — mark done, archive (soft, never deletes a session), rename,
  stop; bulk actions over a visual selection.
• Background auto-naming (opt-in) — name an agent from its launch prompt,
  optionally via a one-shot LLM namer.

See ROADMAP.md for what's shipped and what's planned. Today pi
and Claude Code are supported end-to-end; other CLIs launch but aren't yet
persisted/resumed.

Requirements

• Neovim 0.9+
• At least one agent CLI on your PATH (pi, claude, …)

Installation

With lazy.nvim:

{
  "MateoGreil/agent-fleet.nvim",
  keys = {
    { "<leader>aa", "<cmd>Agent<cr>", desc = "Agent Fleet: launch agent" },
    { "<leader>al", "<cmd>Agents<cr>", desc = "Agent Fleet: list & switch" },
    { "<leader>ab", "<cmd>AgentsBoard<cr>", desc = "Agent Fleet: board" },
    { "<leader>ad", "<cmd>AgentDone<cr>", desc = "Agent Fleet: done" },
    { "<leader>ax", "<cmd>AgentArchive<cr>", desc = "Agent Fleet: archive" },
    { "<leader>as", "<cmd>AgentSend<cr>", desc = "Agent Fleet: send selection to agent" },
    { "<leader>as", ":AgentSend<cr>", mode = "x", desc = "Agent Fleet: send selection to agent" },
  },
  config = function()
    require("agent-fleet").setup({
      agents = {
        pi = {},
        claude = {},
      },
      -- optional: background auto-naming via LLM
      auto_name = {
        enabled = true,
        model = "anthropic/claude-haiku-4-5",
      },
    })
  end,
}

With packer.nvim:

use({
  "MateoGreil/agent-fleet.nvim",
  config = function()
    require("agent-fleet").setup({
      agents = {
        pi = {},
        claude = {},
      },
      -- optional: background auto-naming via LLM
      auto_name = {
        enabled = true,
        model = "anthropic/claude-haiku-4-5",
      },
    })

    local map = vim.keymap.set
    map("n", "<leader>aa", "<cmd>Agent<cr>", { desc = "Agent Fleet: launch agent" })
    map("n", "<leader>al", "<cmd>Agents<cr>", { desc = "Agent Fleet: list & switch" })
    map("n", "<leader>ab", "<cmd>AgentsBoard<cr>", { desc = "Agent Fleet: board" })
    map("n", "<leader>ad", "<cmd>AgentDone<cr>", { desc = "Agent Fleet: done" })
    map("n", "<leader>ax", "<cmd>AgentArchive<cr>", { desc = "Agent Fleet: archive" })
    map("n", "<leader>as", "<cmd>AgentSend<cr>", { desc = "Agent Fleet: send selection to agent" })
    map("x", "<leader>as", ":AgentSend<cr>", { desc = "Agent Fleet: send selection to agent" })
  end,
})

setup() is required, and you must declare at least one agent — there are
no default agents. pi and claude are recognized keys that auto-fill their
command and session settings, so pi = {} / claude = {} is enough; pass extra
fields to override. See Configuration.

Usage

:Agent           " launch the default agent, prompting for an initial message (like the board's i)
:Agent fix auth  " launch the default agent with "fix auth" as the initial prompt
:AgentResume     " reopen a past agent of this directory (focus if live, else resume)
:Agents          " list & switch agents of this directory (focus if live, else resume)
:AgentsBoard     " open the live board buffer (sections, colors, per-row keymaps)
:AgentDone       " toggle an agent done / not done (✓)
:AgentArchive    " archive / unarchive an agent (hidden from :Agents by default)
:AgentRename foo " rename the current agent (or pick one) to "foo"
:AgentRename     " rename via a prompt (current agent, or pick one)
:AgentSend       " send the current line / visual selection to an agent as a file:line ref

:AgentSend doesn't send file content — it sends a path:line (or
path:line1-line2 in visual mode) reference into the current or
last-focused agent's terminal input, without moving focus or pressing Enter
for you. That means you can fire it from a few different spots to stack up
several references in the agent's input, then switch over yourself, add your
question, and press Enter.

The visual-mode mapping must be :AgentSend<cr> (not <cmd>AgentSend<cr>): a
<Cmd> mapping does not pass the visual selection's line range to the command,
so it would only send the cursor line. The leading : lets Neovim insert the
'<,'> range for the selection.

Inside an agent terminal: <C-\><C-n> to enter Normal mode, then move / scroll /
yank with your usual nvim keys. i / a to type to the agent again.

The board (:AgentsBoard)

A dedicated, non-terminal buffer that opens in the current window and lists
this directory's agents in lifecycle sections — running, idle, done,
and (when toggled) archived — each row showing a live/dead marker, the
derived state, the name, and a relative last-activity time. It re-renders on a
timer while visible and reacts to agents exiting. Move with your normal nvim
keys (j/k///gg); the per-row actions are:

Switching, a and i hand the board's window to the agent (the board buffer
is wiped; reopen with :AgentsBoard). Action keys are no-ops on section
headers. d, x and s also work over a visual line selection (V): select a
span of rows and the action applies to every agent in it at once. There is
intentionally no q binding — leave the board with your usual buffer navigation.

The board renders a muted key legend at the bottom, so these shortcuts stay discoverable without leaving the buffer.

Configuration

require("agent-fleet").setup({
  default_agent = "pi", -- which agent `:Agent` launches with no argument
  agents = {            -- registry of agents: key -> { cmd = "<command>" }
    pi = {},
    claude = {},
  },
  window = "enew",      -- where the agent terminal opens (see below)
  start_insert = true,  -- drop straight into terminal insert mode
  follow_output = true, -- keep unfocused agent terminals scrolled to the bottom
  board = {             -- the :AgentsBoard buffer
    refresh_ms = 2000,  -- how often the open board re-renders
  },
  auto_name = {         -- background auto-naming (off by default; see below)
    enabled = false,
    model = nil,        -- e.g. "openai/gpt-4o-mini"; required to do anything
  },
})

Registering agents

The agents registry maps a key to a command. pi and Claude Code are
fully supported end-to-end (persist, resume, board listing with live state).
Other CLIs will launch in a terminal but not appear on the board or be
resumable unless they provide a session backend.

agents = {
  pi = { cmd = "pi" },
  claude = { cmd = "claude" },
}

default_agent chooses which of these :Agent launches; the agent type is not
a command argument (all of :Agent's arguments become the new agent's name).

cmd is split on spaces into an argv list and executed directly without a
shell, so each token becomes a separate argument — no quoting, pipes, or
VAR=val env prefixes. If you need shell features, point cmd at a wrapper
script.

Declaring pi = {} or claude = {} pulls in that agent's built-in preset
(command, session flags, and on-disk session location); any field you set
overrides the preset. A key with no matching preset (e.g. aider = { cmd = "aider" }) launches and is tracked while live, but is only persisted/resumed if
you also give it a session = { id_flag, name_flag, resume_flag } block.

window — where the agent opens

window is run as a plain Ex command right before the buffer becomes a
terminal, so any window-opening command works. Common choices:

Power users can pass any Ex command, e.g. window = "botright 80vnew" for a
fixed-width split.

auto_name — background auto-naming

When an agent (pi or Claude) is launched with an initial prompt but without
a name (board i, or :Agent <prompt>), the plugin can rename it from that
prompt: it runs a lightweight one-shot namer for that agent's backend (pi with
tools/session/extensions off, or claude -p with --tools "") on the prompt
text, sanitizes the reply to a short name, and applies it. There is no
polling — the prompt we launched with is used directly. The agent stays
machine-named, so a manual :AgentRename always takes precedence and is never
overwritten.

Independently of this LLM namer, an agent launched with a prompt but no name
already gets a sensible default: the first line of the prompt (char-aware
truncated to 40 chars), instead of the numbered <kind>-<n> name. An agent
launched without a prompt still falls back to <kind>-<n>.

The LLM namer is OFF by default and does nothing unless you both set
auto_name.enabled = true and provide a model.

auto_name = {
  enabled = false,        -- master switch
  model = nil,            -- model the namer runs with (required, e.g. "openai/gpt-4o-mini")
  thinking = "off",       -- pi --thinking value for the namer
  namer_timeout_ms = 30000,  -- kill the namer subprocess after this long
  max_chars = 2000,          -- cap the prompt text sent to the namer
}

The namer is the only subprocess agent-fleet spawns itself; it runs via
jobstart with an argv list (no shell), and it never passes --name or touches
the session file.

Board highlight groups

The board defines these highlight groups, each linked to a standard group by
default so it follows your colourscheme; override any with
vim.api.nvim_set_hl(0, "<group>", { … }):