Skip to main content
Glama
overseer-nvim-mcp

overseer-nvim-mcp

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
NVIMYesThe 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

CapabilityDetails
tools
{
  "listChanged": true
}
prompts
{
  "listChanged": true
}
resources
{
  "listChanged": true
}
completions
{}

Tools

Functions exposed to the LLM to take actions

NameDescription
overseer_list_tasksA

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.

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 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.

overseer_tailA

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.

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 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.

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 force is set.

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 force is set, since a substring like 'dev' can match theirs.

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 force is set. A name matching more than one task is an error.

Prompts

Interactive templates invoked by user choice

NameDescription
directory_local_taskDefine 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.
diagnoseWork 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

NameDescription
tasksEvery 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

A4.5/5.0

Scored across 7 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessLimited data