Skip to main content
Glama
overseer-nvim-mcp

overseer-nvim-mcp

Run a command as an overseer task

overseer_run

Start long-running commands like dev servers or file watchers as manageable tasks in the user's Neovim task list, so they can be stopped, tailed, and cleaned up instead of lingering as orphaned processes.

Instructions

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.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "overseer_run"
  }
}

Input Schema

NameRequiredDescriptionDefault
cmdNo
cwdNoWorking directory for the task; for `template`, also the directory the template is resolved in. A relative path in `cmd[0]` (./script.sh) resolves against it. Defaults to nvim's cwd
nameNoTask-list name for a `cmd` task; defaults to the command. A `template` runs under its own name
paramsNo
templateNo
settle_msNo
dispose_timeoutNoSeconds a finished task stays in the task list before overseer removes it; default 300. Keep it above ~30: a removed task can no longer be tailed or restarted
dispose_require_viewNoKeep the finished task until the user opens its output in nvim, and only then start counting `dispose_timeout`. Use it for output they should read themselves; your own tail does not count as opening it

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.3.0
    • changedInput schema / properties / cwd / description
      Previous value: -"Working directory for the task; for `template`, also the directory the template is resolved in. Defaults to nvim's cwd"New value: +"Working directory for the task; for `template`, also the directory the template is resolved in. A relative path in `cmd[0]` (./script.sh) resolves against it. Defaults to nvim's cwd"
    • addedInput schema / properties / dispose_require_view
      Added value: +{
      +  "description": "Keep the finished task until the user opens its output in nvim, and only then start counting `dispose_timeout`. Use it for output they should read themselves; your own tail does not count as opening it",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / dispose_timeout
      Added value: +{
      +  "description": "Seconds a finished task stays in the task list before overseer removes it; default 300. Keep it above ~30: a removed task can no longer be tailed or restarted",
      +  "exclusiveMinimum": 0,
      +  "maximum": 86400,
      +  "type": "integer"
      +}
  2. Changed2 schema fields changedv0.2.1
    • addedInput schema / properties / cwd / description
      Added value: +"Working directory for the task; for `template`, also the directory the template is resolved in. Defaults to nvim's cwd"
    • addedInput schema / properties / name / description
      Added value: +"Task-list name for a `cmd` task; defaults to the command. A `template` runs under its own name"
  3. First observedv0.2.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare destructiveHint=false, so the description carries most of the burden and does so well: it discloses process-group teardown, stoppability from the task list, the ephemerality of `cmd` ('gone when the session ends, and the user cannot run it again'), and that `cmd` bypasses the shell so pipes/globs/&& require ['sh','-c','...']. It also explains the return timing semantics and that a startup crash surfaces in the result rather than looking healthy until a later tail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is long but front-loaded: the core purpose and the Bash exclusion come first, then parameter selection, then return semantics. Every sentence carries operational content, though a couple of clauses (e.g. the aside about templates persisting for the user) could be tightened without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter tool with no output schema, the description covers what an agent needs to call it correctly: mode selection, argument format, shell wrapping, params supply, failure surfacing, and return timing. Nothing material is left for the agent to infer before the first call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 50% schema coverage across 8 params, the description compensates for the undocumented ones: it states the mutual exclusivity constraint ('Pass exactly one of `template` or `cmd`'), that `cmd` is an argv array with no shell, that `params` is an object of name to value required by templates that declare params, and that `settle_ms` defaults to 1500 with 0 meaning return immediately. It does not restate the cwd or dispose_* semantics, which the schema already documents, so the remaining gap is small.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Start a long-running command as an overseer task') and immediately states the observable effect: it appears in the user's task list, can be stopped from there, and gets process-group teardown. It is clearly distinguished from sibling alternatives by naming Bash for the short-command case and overseer_list_templates for the template lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use criteria are given with concrete examples ('dev servers, file watchers, --watch test runs, log tails') and the when-not-to-use case is spelled out with the reason ('you need their output in-band, and round-tripping a fast build through start-then-poll is worse'). It also states the decision rule between the two modes: prefer `template` when one matches, otherwise pass `cmd` as an argv array.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.