overseer-nvim-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| NVIM | Yes | The Neovim RPC socket path. This is typically set automatically when the MCP client runs inside a Neovim terminal buffer. Some clients require this to be explicitly passed in the env configuration. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Long-running commands belong in overseer, not the shell.
Start dev servers, file watchers and --watch test runs with overseer_run. They then appear in the user's own task list, the user can stop them from it, and their process trees are torn down properly rather than orphaned when the session ends. A command started in your shell tool has none of that, and the user cannot see it at all.
Short commands that exit on their own stay on the shell: their output is in-band there, which is what you want. Do not route a two-second build through start-then-poll.
Before starting anything, call overseer_list_templates. If the repo declares a task that matches, run it by name instead of reconstructing the command. If an entry already has running_task_id, the user has it running; tail that rather than starting a second one on top of it.
Do not poll in a loop. For a wait of a few seconds, use overseer_tail's wait_for. For anything longer, and for any task you expect to finish on its own (a build, a test run, a migration), do not wait inside a tool call at all: a tool call cannot be backgrounded, so the conversation stalls for as long as the task runs. Run this instead, as a BACKGROUND shell command if your shell tool has one:
/usr/bin/node /app/dist/overseer-nvim-mcp.mjs wait [--match ] [--lines ] [--timeout ]
It blocks outside the conversation, prints the task's last 20 output lines when it finishes (more with --lines), and exits with the task's own exit code (124 if it timed out). is an id or a name substring, the same selector the tools take. With --match it returns on a matching output line instead of on exit, which is how you wait for a dev server to come up without waiting for it to end.
A raw cmd is a one-off: it lasts for this session and the user cannot run it again without you. If the user wants a task that persists, and no runner entry suits, register it directory-locally instead: require("overseer"). register_template in a .nvim.lua at the project root, scoped with condition = { dir = vim.fn.getcwd() }. It needs vim.o.exrc = true, nvim will prompt them to :trust the file, and it will NOT appear until nvim restarts, because the provider list is memoized on runtimepath and a late register_template is silently ignored. Do not read that absence as a failed edit and do not retry it.
If overseer_list_templates comes back empty, or a task's output looks blank, the causes are enumerated in the diagnose prompt; tell the user to run it rather than guessing. Chief among them: the npm provider searches upward and prefers the nearest package.json that has a lockfile, so in a monorepo you can silently get the wrong package's scripts.
The task list is shared with the user. Tasks you started have origin "agent"; clean up only those.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
| completions | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| overseer_list_tasksA | List running and completed overseer.nvim tasks (id, name, status), newest first. |
| overseer_list_templatesA | 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 |
| overseer_tailA | Return a task's live output, preceded by a status line. |
| overseer_runA | 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 |
| overseer_restartA | 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 |
| overseer_stopA | 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 |
| overseer_disposeA | 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 |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| directory_local_task | Define a persistent task for this project without any task runner: no npm script, Makefile or Taskfile. Uses overseer's own register_template via a .nvim.lua that stays out of version control if you want it to. |
| diagnose | Work out why overseer is not showing the tasks you expect, or why a task's output looks empty. Reports what each provider actually tried and why it found nothing. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| tasks | Every overseer task with its status, exit code, command and origin. Attach it to give the conversation the current state of the task list without a tool call. |
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.