overseer-nvim-mcp
An MCP server that lets an agent inspect and control overseer.nvim tasks inside Neovim.
List running and completed tasks, including status, exit code, command, cwd, timings, and whether the task came from the agent or user.
List available task templates discovered from npm, go-task, make, just, VS Code, etc., with filtering, descriptions, params, and running-task hints.
Tail a task’s live output, optionally waiting for a regex match, with cursor-based incremental reads and status/exit-code reporting.
Run long-running commands as overseer tasks using either a template with params or a raw argv command, with cwd, name, and startup settle time.
Restart, stop, or dispose tasks by numeric id or case-insensitive name substring.
Protect user-started running tasks by default: restart/stop/dispose refuse them unless
forceis passed.Expose resources for the task list and per-task output, plus prompts for directory-local task setup and diagnosing missing tasks.
Allows AI agents to manage and monitor overseer.nvim tasks in a Neovim instance, including listing, running, tailing, restarting, stopping, and disposing tasks.
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.
Related MCP server: @aetherall/mcp-nvim-tmux
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-mcpThe 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 mcp add overseer -- npx -y overseer-nvim-mcpcodex mcp add overseer -- npx -y overseer-nvim-mcpThen 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.
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 mcp add overseer npx -y overseer-nvim-mcpOr in settings.json:
{
"mcpServers": {
"overseer": {
"command": "npx",
"args": ["-y", "overseer-nvim-mcp"]
}
}
}In opencode.json:
{
"mcp": {
"overseer": {
"type": "local",
"command": ["npx", "-y", "overseer-nvim-mcp"]
}
}
}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
Tool | Purpose |
| Tasks with id, name, status, |
| Templates in a directory (npm, go-task, make, just, VS Code) with |
| A task's output, with status; can block until a pattern appears |
| Start a long-running command: a raw |
| Restart a task by id or name substring |
| Stop a running task |
| Stop and remove a task from the list |
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
$NVIMset, the server registers seven tools, each onenvim_exec_luaagainst overseer over msgpack-RPC.With
$NVIMunset, 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_tasksreportsoriginasagentoruser, andoverseer_stop,overseer_restartandoverseer_disposerefuse a running task you started yourself unlessforceis 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.
Finished agent tasks remove themselves from the list five minutes after they
complete. This is overseer's own on_complete_dispose with require_view
cleared. By default its timer starts only once the output buffer is shown in a
window, and the agent reads output over RPC without ever showing it.
dispose_timeout changes the delay. dispose_require_view restores the stock
behaviour for output the agent wants you to read yourself.
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
}descis an explicitnullwhen 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.
paramsare the arguments a template takes;requiredmarks the onesoverseer_runwill refuse the call without. Pass them asparams. A missing one is an error naming what it wanted rather than a prompt opened in your editor.running_task_idappears 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.filtermatches 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-instructionsin 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 devin 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, AGENTS.md, GEMINI.md, whatever yours reads).
Clients re-read project instructions constantly, so they outweigh anything the
server can send:
## Long-running commands
Start dev servers, file watchers and `--watch` test runs with `overseer_run`,
not the shell. They then appear in my task list, I can stop them myself, and
their process trees get torn down properly instead of being orphaned.
Short commands that exit on their own stay on the shell: their output is
in-band there, which is what you want.
Check `overseer_list_templates` first. If the repo declares one that matches, run
it by name rather than reconstructing the command.If that still isn't enough, a PreToolUse hook makes it deterministic. This one
blocks the shell for a few unambiguous cases and tells the agent what to do
instead. Start narrow and add patterns you actually hit, since a hook that fires
on the wrong thing is worse than none:
#!/usr/bin/env bash
# ~/.claude/hooks/prefer-overseer.sh: exit 2 blocks the call and shows stderr
# to the agent. Receives the tool call as JSON on stdin.
cmd=$(jq -r '.tool_input.command // ""')
case "$cmd" in
*"vitest run"*) ;; # one-shot, stays on the shell
*" --watch"*|*"vitest"*|*"npm run dev"*|*"pnpm dev"*|*"yarn dev"*)
echo "This looks long-running. Use overseer_run so it lands in the task list and can be stopped." >&2
exit 2
;;
esac
exit 0{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": "~/.claude/hooks/prefer-overseer.sh" }]
}
]
}
}Waiting, without spinning
An agent driving a task by hand ends up guessing: start it, tail, get nothing, tail again, get nothing. It has no way to sleep, so every guess is a round-trip you watch scroll past.
overseer_tail takes a wait_for regex instead. It returns the moment a
matching line appears, or when the task exits, or at timeout_ms, and says
which of the three happened, so a timeout can't be misread as success:
overseer_tail { task: 48, wait_for: "ready - listening" }
status=RUNNING total=5 from=1 waited=matched
compiling... 0
compiling... 1
compiling... 2
ready - listening on http://localhost:3000
GET /route-4 200total is a cursor. Pass it back as since and you get only what is new,
rather than re-reading the same screenful every poll:
overseer_tail { task: 48, since: 5 }
status=RUNNING total=9 from=6
GET /route-5 200
GET /route-6 200
GET /route-7 200
GET /route-8 200from is the index the block actually starts at. If it is greater than
since + 1, output scrolled past between calls and you are looking at a gap
rather than a continuation.
overseer_run waits briefly too, up to settle_ms (default 1500, 0 to
disable), returning as soon as the task produces output or exits. A command that
dies on startup reports its failure there instead of returning the same bare id
a healthy dev server would.
The waiting happens in Node. This server runs inside
your editor, and vim.wait does not process input, so a fifteen-second wait in
Lua would freeze your session for fifteen seconds. Polling over the local socket
keeps Neovim responsive, and you never see the round-trips.
Waits longer than a few seconds: wait
While the agent waits inside a tool call, the conversation is blocked. You can't ask it anything and it can't do anything else. That's fine for a dev server coming up, but not for a ten-minute test run. For those the package has a second entry point:
overseer-nvim-mcp wait <task> [--match <regex>] [--lines <n>] [--timeout <secs>]It connects to the same $NVIM, blocks until the task finishes, prints its
output and exits with the task's own exit code (124 on timeout, 125 if the
wait itself failed). <task> is an id or a name substring, the same selector
the tools take. --match returns on a matching output line instead, which is
how you wait for a dev server to come up.
The task itself is unchanged. overseer_run starts it in Neovim and it shows up
in your list as usual. The agent runs wait as a background shell command,
keeps working, and gets woken with the output when the task ends:
overseer_run { cmd: [...], name: "wait demo" } -> { id: 114, status: RUNNING }
bash overseer-nvim-mcp wait 114 (backgrounded)
status=SUCCESS exit_code=0 total=11 from=1 waited=exited
tick 1
...
all doneThe server instructions give the agent the full command, built from the
server's own argv[1], since under npx -y overseer-nvim-mcp the bin name
isn't on PATH.
Slash commands and attachable resources
Tools are what the agent calls. The server also publishes two things you drive.
Prompts appear as slash commands (/mcp__overseer__... in Claude Code). The
server generates them per invocation, so they inspect your live editor state
rather than reciting a generic answer:
directory_local_taskdefines a task for a project that has no npm script, Makefile or Taskfile, using overseer's ownregister_templatein a.nvim.lua. It checks whetherexrcis actually on and whether a.nvim.luaalready exists, and includes the two things that make a correct setup look broken: it will not appear until Neovim restarts, and Neovim will ask you to:trustthe file.diagnoseexplains why overseer is not showing the tasks you expect. Overseer records, per provider, why it contributed nothing, and that reason is otherwise invisible:- `npm`: 11/11 available - `make`: 0/0 available - No Makefile found - `mise`: 0/0 available - Command "mise" not foundWhich distinguishes "nothing to read here" from "that runner isn't installed", a distinction an empty list cannot make.
Resources are attachable rather than called:
overseer://tasks: the whole task list as JSONoverseer://task/{id}/output: one task's output, with a status line
The server enumerates the per-task URIs with live ids and supports completion, so a client can offer the tasks that exist instead of making you look one up.
Notes
Output from a task started over RPC lives in the strategy's pending buffer, not a terminal buffer, until you open the overseer panel.
overseer_tailreads both, strips ANSI colour codes and carriage returns, and trims the PTY's blank padding so you get clean log lines rather than the bottom of an empty grid.exit_codeis absent while a task is running and present once it exits, which is how an agent distinguishes a clean finish from a crash.
Contributing
See CONTRIBUTING.md. Releases are automated with release-please, so commits must follow Conventional Commits.
License
MIT © Miguel Angelo Sepulveda
Available Tools
7 toolsoverseer_disposeDispose an overseer taskADestructiveIdempotent
Stop (if running) and remove a task from the list by id or name substring. Disposing a finished task is unguarded; a running one the user started is refused unless force is set. A name matching more than one task is an error.
Inputs: task (required), force.
overseer_list_tasksList overseer tasksARead-only
List running and completed overseer.nvim tasks (id, name, status), newest first. origin is 'agent' for tasks this server started and 'user' for the ones they started themselves; only clean up your own.
Inputs: no named parameters.
overseer_list_templatesList runnable overseer templatesARead-only
List task templates overseer discovers in a directory (npm scripts, go-task, make, just, VS Code tasks, etc). An empty list is normal (many repos declare nothing runnable); use overseer_run with a raw cmd instead. Each entry has provider (which task runner it came from) and desc, which is null when that provider supplies no descriptions (npm and make never do, go-task and just usually do), so a null desc means there is nothing to read, not that something was withheld. Entries that have a description are listed first. params lists arguments a template takes, with required marking those that overseer_run will reject the call without. running_task_id is present when a task of that name is already running, which is your signal not to start a second one. Pass filter to match a substring against name and desc; worth doing in a large monorepo, where this can return well over eighty entries.
Inputs: cwd, filter.
overseer_restartRestart an overseer taskADestructive
Restart a task by id or name substring (stops it first if running). A name matching more than one task is an error listing the candidates; pass a numeric id instead. Running tasks the user started are refused unless force is set.
Inputs: task (required), force.
overseer_runRun a command as an overseer taskA
Start a long-running command as an overseer task, so it appears in the user's task list, can be stopped from it, and inherits proper process-group teardown. Use for commands that DO NOT exit on their own: dev servers, file watchers, --watch test runs, log tails. For short commands that terminate by themselves, use Bash instead: you need their output in-band, and round-tripping a fast build through start-then-poll is worse. Pass exactly one of template or cmd. Prefer template (a name from overseer_list_templates) when one matches what you want; it runs the repo's own definition under the name the user already sees in their task list. Most repos declare no templates, in which case pass cmd as an argv array, which works anywhere. Note a cmd is a one-off, though: gone when the session ends, and the user cannot run it again without you. If they want it to persist, it belongs in a directory-local template instead of being re-passed as cmd every time; the server instructions describe how. cmd does not go through a shell, so for pipes, globs, && or env prefixes pass an explicit wrapper: ["sh", "-c", "..."]. Returns once the task has produced output or exited, up to settle_ms (default 1500, 0 to return immediately), so a command that dies on startup reports its failure here rather than looking identical to a healthy one until some later tail. Templates that declare params need them supplied here; pass params as an object of name to value. A missing required param comes back as an error naming what it wanted rather than a prompt opening in the editor.
Inputs: cmd, cwd, name, params, +4 more.
overseer_stopStop an overseer taskADestructiveIdempotent
Stop a running task by id or name substring. Overseer stops the underlying nvim job, so the task's process tree is torn down rather than left orphaned. A name matching more than one task is an error listing the candidates. Running tasks the user started are refused unless force is set, since a substring like 'dev' can match theirs.
Inputs: task (required), force.
overseer_tailTail overseer task outputARead-only
Return a task's live output, preceded by a status line. task is a numeric id or a case-insensitive name substring; omit it for the most recent task. The status line reports status, exit_code once the task has exited, and total (lines available so far), so you never need a separate overseer_list_tasks to find out whether what you are tailing is still alive. Pass the previous total back as since to get only what is new instead of re-reading the same lines; from tells you where the returned block actually starts, and a from greater than since + 1 means output scrolled past between calls. Set wait_for to a regular expression to block until a matching line appears; use it instead of polling repeatedly. It returns as soon as it matches, or when the task exits, or at timeout_ms (default 15000, max 120000), and reports which of the three happened as waited, so a timeout is never mistaken for success. wait_for is for a wait of a few seconds. This call cannot be backgrounded, so a longer one holds up the conversation for the task's whole duration; wait for those with the wait subcommand in your shell instead, as the server instructions describe.
Inputs: task, lines, since, wait_for, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool maps to a distinct lifecycle action or listing operation, and the descriptions go out of their way to spell out the differences (dispose vs stop vs restart, with the force/ownership rules repeated). The only real overlap is the stop/dispose/restart trio, which an agent could still confuse at a glance, but the descriptions resolve it.
All tools share a consistent `overseer_` prefix with lowercase snake_case verbs, and the two listing tools follow a clean `list_<noun>` pattern. Single-object tools use bare verbs (run, stop, tail, dispose) rather than verb_noun, a minor deviation but still readable and predictable.
Seven tools is tightly scoped to the domain: start, observe, and control long-running tasks plus discover templates. Every tool earns its place with no redundant or throwaway entries.
The surface covers the full task lifecycle (run, list, tail, wait-for-output, restart, stop, dispose) plus template discovery, with tail's status line removing the need for a separate status tool. The notable gap is sending input to an interactive task's stdin, and there is no way to create or persist a template, though the latter is deliberately delegated to on-disk config.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI assistants to control running Neovim sessions via RPC socket, supporting command execution, state inspection, and LSP actions. Automatically discovers Neovim instances and supports multi-instance management on Linux and macOS.1823 PyPI68MIT
- AlicenseBqualityDmaintenanceAn MCP server that enables AI agents to control Neovim instances running in tmux sessions.12MIT
- AlicenseAqualityDmaintenanceMake Neovim feel like Cursor. This MCP server gives an agent full control over the Neovim session it is running inside, including buffers, windows, diagnostics, LSP language intelligence, and terminals.23MIT
- AlicenseAqualityFmaintenanceMCP server for running external coding agents as background tasks inside Claude Code. Supports multiple backends including Codex, Grok, GLM, DeepSeek, and more.7MIT