Run a command as an overseer task
overseer_runStart 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
| Name | Required | Description | Default |
|---|---|---|---|
| cmd | No | ||
| cwd | No | 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 | |
| name | No | Task-list name for a `cmd` task; defaults to the command. A `template` runs under its own name | |
| params | No | ||
| template | No | ||
| settle_ms | No | ||
| dispose_timeout | No | 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 | |
| dispose_require_view | No | 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 |