Overseer Nvim MCP

overseer-nvim-mcp

An MCP server that gives a coding agent the same control over overseer.nvim tasks that you have: list, tail, run, restart, stop, and dispose.

Why

Your agent's shell tool and your overseer task list are separate execution worlds. A dev server the agent starts in its own shell is invisible in the task list, can't be stopped from it, and orphans its process tree when the session ends. Tasks *you* start get proper teardown. This closes that gap: the agent's long-running commands become real overseer tasks.

Requirements

• Neovim with overseer.nvim (tested against v2.1.0)
• Node >= 22
• An MCP client running inside a Neovim terminal buffer

Install

The server speaks stdio and is started by your MCP client. The command is always the same:

npx -y overseer-nvim-mcp

The client must run inside a Neovim terminal buffer; that is where the $NVIM socket it inherits comes from. Tools appear at the next session start, since MCP servers connect at startup. If the tools never appear, the usual cause is that $NVIM did not reach the server's environment: the server registers nothing without it, and some clients strip the environment they pass to servers.

Claude Code

claude mcp add overseer -- npx -y overseer-nvim-mcp

Codex CLI

codex mcp add overseer -- npx -y overseer-nvim-mcp

Then add one line to the generated block in ~/.codex/config.toml:

[mcp_servers.overseer]

command = "npx" args = ["-y", "overseer-nvim-mcp"] env_vars = ["NVIM"]

The env_vars line is required. Codex passes stdio servers a fixed whitelist of variables (HOME, PATH, TERM and the like), $NVIM is not on it, and without it the server registers no tools.

Codex also won't reach for the server on its own; see Getting your agent to actually use it.

Antigravity CLI

In ~/.gemini/config/mcp_config.json:

{

"mcpServers": { "overseer": { "command": "npx", "args": ["-y", "overseer-nvim-mcp"] } } }

That user-global file is the one to use: the CLI's non-interactive print mode (agy -p) loads MCP servers from it and from nowhere else; a workspace-level .agents/mcp_config.json is silently ignored there.

Antigravity also won't reach for the server on its own; see Getting your agent to actually use it.

Gemini CLI

gemini mcp add overseer npx -y overseer-nvim-mcp

Or in settings.json:

{

"mcpServers": { "overseer": { "command": "npx", "args": ["-y", "overseer-nvim-mcp"] } } }

opencode

In opencode.json:

{

"mcp": { "overseer": { "type": "local", "command": ["npx", "-y", "overseer-nvim-mcp"] } } }

mcphub.nvim (codecompanion.nvim, avante.nvim)

In mcphub's servers config:

{

"mcpServers": { "overseer": { "command": "npx", "args": ["-y", "overseer-nvim-mcp"], "env": { "NVIM": "${NVIM}" } } } }

The env block is required: mcp-hub does not pass its own environment to the servers it spawns, so without it the server sees no $NVIM and registers no tools. The server operates on the Neovim instance that started the hub. A hub started outside Neovim has no $NVIM to forward, and mcp-hub reports this server as disconnected with Variable 'NVIM' not found.

Using with LazyVim

LazyVim ships an overseer.nvim extra. Enable it with :LazyExtras (select editor.overseer), restart Neovim, then add the server to your MCP client as above. Nothing else is needed; the server talks to whatever overseer configuration you already have.

Tools

The last three take force, and refuse a running task you started without it.

Tasks are addressed by numeric id or a case-insensitive name substring, so an agent can say "dev" instead of tracking ids.

How it works

The transport is $NVIM, the RPC socket Neovim exports to every process it spawns in a terminal buffer. Your MCP client inherits it, and this server, as a child of that client, inherits it in turn.

Everything else follows from that:

• With `$NVIM` set, the server registers seven tools, each one nvim_exec_lua against overseer over msgpack-RPC.
• With `$NVIM` unset, it registers nothing and gets out of the way. Running outside Neovim is a no-op rather than an error.

There is no socket discovery: no cwd hashing, no lsof, no pgrep. Those approaches are structurally broken (a cwd-hash scheme cannot tell a crashed instance's stale socket from a live one and will unlink working sockets; pgrep on macOS excludes the caller's own ancestors, which is exactly the Neovim instance that matters). $NVIM sidesteps both by construction.

All user input (task names, commands, working directories) is passed as msgpack arguments and arrives in Lua as .... Nothing is ever interpolated into Lua source, so a task name cannot become code execution.

It shares your task list, so it stays out of your tasks

The task list has two writers now, and only one of them can see it. Two things keep that from biting:

• A substring matching more than one task is an error that lists the candidates and asks for a numeric id. "dev" matches a dozen names in a monorepo, and silently taking the first is how the wrong thing gets stopped.
• Tasks are tagged with who started them. overseer_list_tasks reports origin as agent or user, and overseer_stop, overseer_restart and overseer_dispose refuse a running task you started yourself unless force is passed. Finished tasks are unguarded, since removing a dead row costs nothing.

The asymmetry is on purpose. A wrong refusal costs one extra call. A wrong stop kills your dev server, loses whatever state it held, and you would have no reason to connect it to the agent.

overseer_run is for commands that do not exit on their own: dev servers, file watchers, --watch test runs. Short commands that terminate by themselves should stay on the agent's normal shell tool, where output is available in-band. Round-tripping a two-second build through start-then-poll is worse.

An empty template list is normal

overseer_list_templates returns whatever overseer's providers discover, verbatim. Most repos declare nothing runnable and return an empty list. That is a legitimate answer, not an error. This is why overseer_run takes a raw cmd as its primary path: a template-only design would be unusable in the common case.

No provider-specific knowledge lives in this server. It does not filter or rewrite results, including help-only entries some task runners expose, because doing so would mean encoding one provider's conventions into a server that must behave identically in a repo that has never heard of it.

What each entry carries:

{

"name": "just fixture-just-generate", "provider": "just", "desc": "Generate output for a language", "params": [{ "name": "lang", "type": "string", "required": true }], "running_task_id": 128 }

• `desc` is an explicit `null` when a provider supplies no descriptions. npm and make never do; go-task and just usually do. An explicit null says there is nothing to read, rather than leaving you guessing whether a field got dropped somewhere.
• Entries with a description sort first. That encodes nothing about any provider, only about information content. A repo with a Taskfile *and* a package.json would otherwise bury its documented half beneath dozens of bare npm script names.
• `params` are the arguments a template takes; required marks the ones overseer_run will refuse the call without. Pass them as params. A missing one is an error naming what it wanted rather than a prompt opened in your editor.
• `running_task_id` appears when a task of that name is already running. It is a name match, so it can miss (a template invoked with params produces a task named after the resolved command), but when it is there, it is the signal not to start a second dev server on top of yours.
• `filter` matches a substring against name and desc. Worth using: a three-runner monorepo can return well over eighty entries.

Getting your agent to actually use it

On some clients this is automatic. The server returns MCP instructions in its initialize result, and clients that surface those put them in the agent's system prompt, where it is actually looking rather than buried among fifty tool descriptions. It states the lifetime boundary (long-running here, short commands on the shell) and tells the agent to check templates before reconstructing a command, use wait_for instead of polling, and clean up only its own tasks.

The server withholds those instructions when $NVIM is unset, for the same reason it registers no tools: a session that gets none should not be told how to use them.

Whether the instructions reach the model is the whole game, and clients differ:

• Claude Code injects them. Copilot CLI injects them for servers whose instructions you allow (--allow-all-mcp-server-instructions in scripted runs).
• Codex CLI shows the model the tool definitions but not the instructions, and leaving servers untouched until prompted is a known open issue. Asked to "start the dev server", it runs npm run dev in its own shell with the server connected and working.
• Antigravity CLI injects nothing at all: it writes the instructions and every tool schema to files under ~/.gemini/antigravity-cli/mcp/overseer/ that the model only reads once something points it there. Same prompt, same result: its own shell.

On those two, either name overseer in the prompt ("start the dev server in overseer" works on both) or say it once in the place the client actually reads: its context file. One line in AGENTS.md (Codex) or GEMINI.md (Antigravity) flips the same prompt to full overseer routing: templates checked first, task run by name, output tailed after.

The markdown below is that one-time instruction, and it belongs in your project context file on every client (CLAUDE.md, `AGENT