Run a command as an overseer task
overseer_runStart long-running commands (dev servers, file watchers, watch tests) as overseer tasks, so they appear in your task list and can be stopped when needed.
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.
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. 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 |