Rove

<!-- rove-skill-version: 56 — bump in lockstep with ROVE_SKILL_VERSION (src/lib/skill-install.ts). -->

Rove shell control

Use rove api to manage local coding tasks. Managed Tasks created by API automation own a git Worktree and branch plus Hosted PTY engine tabs; project main and directory Tasks reuse existing directories. API automation works without an open TUI; prompted send and add ensure a target engine tab.

Inside a Rove session, Rove verbs come first

Check where you are before choosing how to delegate or parallelize:

test -n "${ROVE_TASK_ID:-}"

When that passes, you are an engine session Rove manages — $ROVE_TASK_ID is your task, $ROVE_TAB_ID your tab. Coordination should then go through Rove, not around it, because work routed through rove api gets what ad-hoc subprocesses never do: its own Worktree and branch (no file collisions with you), a sidebar row with live state the user can watch, lifecycle tracking, and an explicit outcome contract.

• Parallel attempts of one prompt → add --count N, not N hand-rolled subagents.
• Delegating a scoped piece of work → add --prompt, not a raw claude -p child the user cannot see or manage.
• Following up on a task you started → send; comparing → collect; finished your own task and were spawned by another → a bare send (no --task-id) replies to the DISPATCHER — the exact task + tab that created you, recorded at creation (.task.dispatcher on get-task). If that tab died it falls back to the dispatcher task's live canonical engine tab; nothing alive fails loud (DISPATCHER_UNREACHABLE) — it never spawns a new engine, so a failed reply is visible, not fake-ok.
• Messaging another agent session on this machine → send, and ONLY send — never relay through the user, a side file, or a generic peer channel (an MCP server offering to message "other instances" is exactly that channel: it reaches a process, not a task, so nothing it delivers is attributable, watchable, or replyable). Sent from inside a Rove task, the prompt arrives prefixed [ROVE PEER] from "<title>" (task <id> — Rove agent skill /rove, read it once per session …), so the receiver knows who is talking, that this skill is required reading, and how to answer — the baked-in reply command is tab-precise (--task-id <sender> --tab <sender's tab>), so peer conversations need no coordinator and no human relay. That prefix is the contract: do not strip it with --plain for coordination messages (--plain is only for a verbatim paste the receiver should treat as content, not conversation). Received a [ROVE PEER] message yourself? Read this skill once per session. The baked-in command identifies where a necessary reply goes; it is not an instruction to acknowledge every message. Act on FYIs without replying.
• send carries text, but that text can carry FILES: peers share a filesystem, so put the absolute path of a screenshot, log, diff, or any artifact in the prompt and the receiver opens it with its own Read tool — images included. An annotated screenshot beats a paragraph describing one; prefer "see /path/to/shot.png — the arrow marks the broken card" over re-narrating pixels. Paths under the sender's Worktree work too (worktrees are world-readable locally); just never expect the receiver to WRITE there.
• dispatch stays the dispatcher's verb (deliver-only into an already-hosted session; never impersonate the user in someone else's terminal).

Your own engine's in-context subagents remain fine for read-only research/exploration inside your task — the boundary is WORK: anything that edits files, runs long, or the user should be able to see and steer belongs in a Rove task. Do not recursively fan out from a spawned task.

When the check fails, none of this applies — use rove api only if the user asks for Rove by name.

Vocabulary — what the user's words map to

Two of those colloquialisms are traps, so read them as INTENT, not as product terms: in Rove's own vocabulary Workspace is the center Terminal Tab region of the UI (CONTEXT.md), not a checkout, and ChatTab is retired vocabulary for Terminal Tab. A user saying "in this workspace" means the worktree they are looking at — answer the intent, keep writing the real term.

They nest — Task ⊃ Terminal Tab ⊃ Split — and isolation drops at every level down:

new Task   → own worktree + own branch     (parallel work can't collide)
new Tab    → own engine session, SAME files (a helper in the same checkout)
new Split  → same session's screen, one tab divided (a monitor beside the work)

The distinction that decides every routing call: a new tab shares the worktree and branch; only a new task gets its own. Two tabs in one task edit the same files, so they can collide — that is a feature when the user wants a helper in the same checkout, and a bug when they wanted parallel attempts. A split isolates nothing at all: it is a layout, for watching something (logs, btop, a test loop) next to the work — never the answer to "do this work".

One boundary the isolation model does NOT cover: never git stash in a managed worktree. The stash stack lives in the repo's common dir (.git/refs/stash) and is shared by every linked worktree — two tasks that stash in parallel can pop or drop each other's work. Commit instead; a commit is per-branch and isolates exactly the way the model promises.

Where does this work land?

Inside a Rove session ($ROVE_TASK_ID non-empty — check first: it is what makes the tab/split rows addressable at all), match top to bottom and take the first row that fits:

Order is the tiebreak: a count ("3 ways in this workspace") beats a location word, and delegation language loses to "you do it" — the user asking YOU is not asking for a fleet. Two more rules the table can't show:

• No location word at all ⇒ new task. It is the only routing whose isolation cannot corrupt work-in-progress, so it is the safe default.
• "this repo" / "this project" are NOT location words — they name the repo, not the checkout. Only worktree-scoped words route to a tab.

Outside a Rove session none of this applies: there is no "this task" to add a tab to, so add (single or --count) is the only routing available.

Know where you are before you route

echo "$ROVE_TASK_ID / $ROVE_TAB_ID"          # who you are (empty = not a Rove session)
rove api get-task --task-id "$ROVE_TASK_ID"  # .task.title, .task.branch, .task.id, .running, .tabs[]
                                             # .task.worktreePath too — only if you are about to read/write its files

get-task is the per-task read that answers "what is my worktree, my branch, and which sibling tabs exist" — .tabs[] carries each tab's id, kind, vendor, liveVendor, lastTitle and alive, which is exactly the target list for send --tab. A tab flagged unregistered: true is a live session the tab snapshot lost; it is addressable like any other.

Coordinating others? Start every turn with context

If you spawned tasks, begin each turn with one read instead of your memory — between two of your turns a worker can finish, crash, stall on a permission prompt or get its PR approved, and you witnessed none of it:

rove api context --repo "$PWD" --text

One line per task, sorted so the first line is what needs a person next. The group on each row is DERIVED from that task's report, PR observation, engine activity and tab liveness — it is NOT the status field, which a crashed worker leaves reading in_progress forever:

Never read unknown as idle, and never act on a group as if it were a verification: ready-for-review means a worker CLAIMED something, so collect and the actual diff still decide whether it lands. Drop --text for structured rows (group, rank, checkState, report) when you are going to branch on the fields rather than read them.

context also carries the unhandled attention inbox and the repo's newest field notes — the same notes a fresh session here is handed, so brief your workers from those and don't re-derive what is already written down.

Refer to a task the way the user sees it

The sidebar row is the task's title; the line under it is its branch. Nothing in Rove's UI ever renders worktreePath, so the directory name in it (~/.rove/worktrees/<repo>/marlin) is a filesystem address the daemon picked from an animal pool — the user has never read that word and cannot find it on screen. Never name a task by its directory to a user or in a report.

Use the title when a human reads it, the task id (or its last six characters) when you need it to be unique, and both when you need both:

• ❌ marlin opened a PR · landed in zorilla · see mammoth's branch
• ✅ "Skill version guard…" (task …CWWA) opened PR #972
• ✅ succeeded: guard now fails the build (branch fix/skill-version-bump)

worktreePath earns a mention only when the sentence is about files on disk — cd, a path in a command, a file you edited.

Found a defect in ANOTHER project? File a request, don't work around

The repos on this machine are deliberately interdependent — one project using (and stumbling over) another is the normal case, not the edge case. Each saved project can keep a main task: a long-lived resident agent on that repo's own checkout. It is more than "task kind = existing directory" — it is that project's standing inbox, addressable from any other repo's session, and it dispatches what it receives.

So when work in repo A surfaces a defect in product B, the default is to file a request with B's main task — not to quietly patch around it in A. The test: would this bite someone else? A local workaround fixes only you; a fix in B fixes everyone. Work around locally to unblock yourself if you must, but file the report either way.

rove api list                                   # find B's main task id
rove api get-task --task-id <their-main>        # .tabs[] → the engine tab's id
rove api send --task-id <their-main> --tab tab-N --prompt "<report>"

Address the engine tab explicitly (--tab tab-N from get-task's .tabs[], kind == "engine"): a long-lived main task's engine tab is often not tab-1, and an un-addressed send may refuse with NO_ENGINE_TAB rather than guess.

A report worth sending carries: symptoms (what happened, concretely, how many times), root cause if you found it, why it is worth fixing (who else it bites), and suggestions without prescribing the implementation — the receiving project decides how to fix its own product.

Send the report — never add a task into someone else's repo. You hold the problem-side context (symptoms, root cause, impact); only that project's main agent holds the solution-side context (code structure, existing issues, what's mid-flight, where this slots in the schedule). A task you compose would bake YOUR guess at the fix into the brief, and that guess is usually wrong — one field report here looked like "add a line to the docs" and actually split into a docs fix plus a runtime-detection issue anchored in files the reporter didn't know existed. You raise the problem; their main agent decomposes it into tasks. That translation is the main task's whole job, and it is why every project should keep one.

Fresh worktrees start empty — install before you judge

A managed task's worktree is a brand-new checkout: no node_modules, no build artifacts, nothing a lockfile promises. Two consequences:

• A test failure in a fresh worktree may be fake. Missing dependencies masquerade as product bugs ("Could not resolve: react-dom/client" reads like a regression, not a missing install). Before reporting any failure as real, confirm the repo's install step ran — and when a failure looks unrelated to your change, compare against the same command on the base branch before believing it.
• Repos with an install step should ship .rove/init.sh — it runs once per worktree, before the engine, in the worktree (per-user override: rove repo set --init-script; inspect with rove repo show, which lists .rove/init.sh: absent when unset). Working in a repo that lacks one and you just paid the install tax? Suggest adding it.

Discover before calling

Do not guess flags — but do not pay a round-trip for the ones you use every turn either. These five carry almost all traffic:

add      --repo(REQ) --prompt --title --command --count --agents --activate
send     --prompt|--prompt-file(REQ) --task-id --tab --command --plain
get-task --task-id(REQ)          list  (no flags)
collect  --group <groupId> | --task-ids <csv> | --repo

Names that have actually been guessed wrong here: add --vendor is --command; read-output --task is --task-id; per-field verbs (set-<field>, rename, pin) are all update --<field>; dispatch --text is --prompt (--text belongs to note); issue-list has no --state at all — filter its JSON yourself.

references/api-flags.md is every verb and flag. Find your section by what you were ASKED, not by Rove's noun for it:

Reach for schema when the binary and that file disagree.

rove api schema --verb add    # or --group create, --all
rove api <verb> --help
rove api engine-list          # what you can launch, and with what command

Commands emit one JSON object; errors use {"error":{"message","code",...}} on stderr. Common rejections also carry hint (what to do) and nextCommandArgs (argv for the same Rove executable — run rove <args...> verbatim to recover, e.g. ["api","list"] after TASK_NOT_FOUND). Add --pretty for readable output.

Common operations

# Create one task and start its first engine turn.
rove api add --repo "$PWD" --title "focused title" --command claude \
  --prompt "<complete scoped instruction>"

# Parallel attempts of the same prompt (hard cap 10; prefer 3-4).
rove api add --repo "$PWD" --count 3 --prompt "<prompt>"
rove api add --repo "$PWD" --agents claude:2,codex:1 --prompt "<prompt>"

# Follow up. Use an explicit id for unattended work; the active task can drift.
# From inside a Rove task this auto-prefixes [ROVE PEER] provenance
# (sender + reply command) — `add --prompt` wears it too, so a dispatched
# task's opening brief carries its reply address; --plain sends verbatim.
#
# A prompt with backticks, $vars, or quotes goes through --prompt-file, NEVER
# a double-quoted --prompt: in double quotes `rove api send …` is command
# substitution — the shell RUNS it and ships its output, and the words vanish.
# Single quotes block $ROVE_TASK_ID too, so there is no quoting that fits both.
rove api send --task-id <id> --prompt "<complete next turn>"      # plain text only
rove api send --task-id <id> --prompt-file - <<'EOF'              # anything else
<turn — backticks, $vars, quotes, multi-line, all verbatim>
EOF

# Reply home: no --task-id inside a dispatched task = the dispatcher's tab.
rove api send --prompt "succeeded: <one line> (branch <final branch>)"

# A task can hold several Terminal Tabs. `get-task` lists ONE task's tabs (the
# usual read before addressing one); `inspect` is the wider diagnostic — every
# task's snapshot plus daemon activity and live pty sessions.
rove api inspect --task-id <id>
rove api send --task-id <id> --tab tab-3 --prompt "<turn>"  # exact alive tab
rove api send --task-id <id> --tab new --prompt "<turn>"    # fresh engine tab
# Same worktree, DIFFERENT agent — the API twin of the TUI's ctrl+e pick. The
# engine is pinned to that tab (survives restarts, unaffected by a later
# update --command) and the task's own engine is left alone. --tab new only.
rove api send --task-id <id> --tab new --command codex --prompt "<turn>"

rove api get-task --task-id <id>
# One read for the whole round — the groupId `add --count` returned. Never
# hand-copy N task ids across turns: collect by group. Lost the groupId? Any
# sibling task's `.groupId` in `list` output recovers it.
rove api collect --group <groupId> --pretty
rove api list --pretty

.running is true / false / null. It means an ENGINE PROCESS is alive in one of the task's engine tabs — a live shell, command, or content tab alone does not count, and neither does an engine tab whose engine exited (the PTY survives it as a login shell; each tab reports that as engineAlive). null means the pty host could not be asked: "couldn't look", NOT "nothing is running". Never act on null as if it were false — deleting a task on it destroys a worktree that may hold live work. It is process truth, not progress: a task whose work is merged and whose worker has signed off still reads true until somebody deletes it (see "A task is finished when it is GONE"). Omitting BOTH --task-id and --tab inside a task that has a dispatcher targets that dispatcher's tab (see the reply rule above); otherwise the target is the active task. Omitting only --tab targets a live engine tab (tab-1 first, then any surviving engine tab). Trap: omitting only --task-id while giving --tab tab-N inside a dispatched task delivers to tab-N of the DISPATCHER's task — the dispatcher's id fills in for --task-id, but an explicit --tab is kept, so your send --tab tab-3 lands in the middle of another session's tab-3, not yours. Target your own task's tab with --task-id "$ROVE_TASK_ID" --tab tab-N. Only when the task has NO live session at all does send auto-start the canonical engine in the task's worktree (started: true in the result marks that fresh session). If live tabs exist but none resolves as an engine, it refuses with NO_ENGINE_TAB — address one with --tab tab-N or spawn one with --tab new; it never silently spawns a duplicate engine. Its hint names pty-list — the live-PTY read (key, alive, pid, command); use it when .tabs[] and reality disagree.