# Concepts Six nouns explain Rove: **Task**, **Worktree**, **Terminal Tab**, **Engine**, **Daemon**, and **PTY host**. Learn those and the rest reads itself. ## Task A Task is one workspace record you're tracking. Rove has two Task kinds: | Kind | Directory | Git isolation | |---|---|---| | Managed task | A Rove-created worktree | Own branch and worktree | | Directory task | An existing directory opened with `rove .`, or a saved project's own checkout | Uses the directory as-is; it need not be a git repository | For a managed task, the product unit is: ```text Managed task = git worktree + branch + terminal tabs ``` A Task is a **workspace, not a conversation**. Its Terminal Tabs all run in the same directory. Only managed tasks get Rove-created branch/worktree isolation; directory tasks (a session in a project's own checkout included) deliberately reuse directories you already own. A **New shell** from a Task row is not a Scratch shell: it is a child Task sharing the row's directory, listed under it, whose `tab-1` is the login shell. When that shell exits the row stays, empty, and is never deleted for it. **Scratch shells** are directory Tasks with an unsettled home: press `tab` in the `ctrl+e` new-conversation dialog until the destination reads "new scratch task", pick an engine (or `shell` for a bare shell), and `enter` opens one in `$HOME` with that engine already running. It lives in the sidebar's **Ungrouped** group above every project, and follows a zero-ceremony lifecycle: its last tab exiting removes the row (no archive, no confirm; nothing on disk is touched). Routines created with **Ungrouped** run in their own directory under `.rove/routines/` and their sessions open from the Routines page, not the sidebar; they are not scratch shells and are never auto-removed. A scratch row earns a permanent place two ways: rename it (naming is the keep gesture), or start a coding harness inside a git repository. Rove detects the live harness plus the shell's settled directory and quietly migrates the row into that repository's project group. If the settled directory already belongs to a Task (a directory Task's directory, or inside a managed Task's worktree), the shell folds into that Task as a new terminal tab, running session and all, instead of becoming a duplicate row. Each Task has a `status` you set yourself (`backlog`, `in_progress`, `in_review`, `done`, `canceled`, `error`) — from the sidebar row's right-click menu (**Set status**) or with `rove api update --status`. It is a label and nothing more: `canceled` does not stop a session or remove a worktree, and `done` does not close anything. Rove moves a Task from `backlog` to `in_progress` by itself when its engine starts a turn, and the system prompt asks the agent to set `in_review` when it finishes, unless another Rove session handed it the work (then its `report` or outcome message is the signal); everything past that is yours. The sidebar row does not draw it: the one mark in that cell is the PR's, and the status is something you already know because you set it (see [TUI](./TUI.md#status-glyphs-in-the-sidebar)). **Delete is explicit and kind-aware.** Deleting a directory Task removes only its Rove record, never the directory. Forgetting a project (**Remove project** on its header's menu) un-saves the repository and keeps every Task, branch and worktree. Deleting a managed Task removes its worktree after the dirty-worktree safety check. **The task branch stays.** Git is the durable record of the work; pass `--delete-branch` on `rove api delete` to drop it too. That runs `git branch -d`, which refuses a branch whose commits neither the repo's HEAD nor the branch's own upstream already contains — so work that was never pushed and never landed survives the flag, and `--force` is what upgrades the delete to `git branch -D`. Deleting from the TUI keeps the branch too, unless you set `worktree.deleteBranch` to `true` ([Configuration](./CONFIGURATION.md)), which applies the same `git branch -d` rule. **The remote branch is only touched when you ask for it**, with the separate `--delete-remote` — a local branch is recoverable from any clone that still has it, a remote one is recoverable by nobody, and deleting it closes an open PR, so one flag never implies the other. The separate [Worktrees page](WORKTREES.md) is an audit/cleanup tool: removing a directory there keeps its Task record and branch so the worktree can be materialized again later. `rove api remove-worktree --task-id ID` is the same operation from a shell — the inverse of `ensure-worktree`, and what a script reclaiming idle checkouts wants instead of `delete`. **What the delete did to the branch is in the reply.** With either branch flag the result carries `branch` — `{ branch, deleted, keptReason?, remote? }` — so "the branch went with it" is a fact you read rather than one you infer from `status: "removed"`, which is the worktree's outcome. When git kept the branch, `keptReason` is its own sentence about why. ## Worktree and branch Every managed Task gets its own git worktree at `~/.rove/worktrees///`, checked out to the task's branch. The slug is drawn from a pool of animal names, so parallel Tasks in one repo get distinguishable directories without anyone choosing them; `rove api add --worktree-name NAME` overrides that when a script needs to predict the path instead of reading it back, and refuses a name already in use rather than suffixing it. That's what makes running many tasks at once safe: N tasks means N working trees that can't overwrite each other or your main checkout. Edits cross over only when you merge. Directory Tasks are the exception: they point at an existing checkout or directory. Use a managed Task when you want isolation. The worktree outlives everything else. Killing a session, quitting the TUI, dropping SSH, restarting the daemon: none of them touch it. > **One thing to watch:** a child that shares its parent's directory shares its > worktree, and Rove does not coordinate their writes. Two conversations editing > the same file at once will conflict. If you need real isolation, open a new > task or `add --parent ` a child with its own worktree. ## Terminal Tabs and engine sessions A Task is one engine conversation: its `tab-1`. A second conversation is a **child task**, shown under its parent in the sidebar. A child either shares the parent's directory (`ctrl+t`, `ctrl+e`, `add --no-worktree`) or gets its own worktree cut from the parent's branch tip (`add` from a task's own session). Deleting a parent promotes its children; `delete --cascade` removes the subtree. A Task owns its Terminal Tabs. The engine tab runs an engine inside an interactive shell and can resume an engine-owned conversation. Other tabs can be shells, fixed commands/editors, or read-only file/diff content; those are not engine conversations. Splits add more shell leaves inside a tab. Tabs let you ask a side question or open a shell without changing directories. Close a tab when you're done; the Task's directory stays. Exiting the engine CLI itself returns an engine tab to its shell prompt. The hosted session ends only when that wrapping shell exits or Rove explicitly closes it. **Closing the last tab is "done for now", not "forget".** Close every tab of a managed Task and its row stays in the sidebar; entering it again opens a fresh tab in the same worktree. A project whose only row is a directory Task with no tab open leaves the sidebar, header and row together. Nothing is deleted: the Task record and the saved repository both stay on disk. A project has no standing conversation: to start one in its own checkout, open New task (`n`), pick the same repository, and choose "the project itself" instead of a new task worktree (see [TUI](./TUI.md#creating-a-task)), or `rove api send --repo PATH`. Forgetting a project (**Remove project** on its header's menu) is the separate, un-saving gesture. A Task-level reasoning-effort choice is forwarded when the engine supports it. A child task runs the engine it was started with, so conversations in one directory can use different vendors. The embedded engine CLI owns its own model and permission controls. Conversation history belongs to the engine, not to Rove (Claude Code, for example, keeps JSONL transcripts under `~/.claude/projects/**`). Hosted terminal output has separate persistence rules; see [Sessions](SESSIONS.md). ## Engines An engine is the execution backend a task runs on. Rove embeds the **real interactive CLI** (`claude`, `codex`, `copilot`, `kimi`, `pi`, `omp`, or one yourself) inside a hosted terminal session. No API wrappers, no re-rendered output: what you see is the actual engine running next to your dependencies and credentials. Details: [Engines](ENGINES.md). ## Daemon and PTY host Rove splits into three processes, and that split is why your sessions survive you: ```mermaid flowchart LR TUI["Rove (TUI)"] --> D["Daemon"] API["rove api"] --> D TUI --> P["PTY Host"] API --> P D --> IDX["Task index + worktrees"] P --> E["TUI/API engine + shell sessions"] ``` - **Daemon.** Owns your task list, worktrees, and the issue store. Starts on its own, then stops after the last attached GUI disconnects unless an enabled routine, or any live tab session in the PTY host, holds it alive (it must stay up to collect engine activity, or the status dots go stale). - **PTY host.** Owns the running engine and shell processes. Survives both the TUI *and* a daemon restart. - **The TUI.** Just a viewport. Quitting it kills nothing. Full lifetime rules, and exactly what survives a reboot: [Sessions](SESSIONS.md). ## The issue store Rove has no external issue tracker. Your backlog lives in a daemon-owned store at `~/.rove/issues.json`, shared between a repo and all its worktrees. It's deliberately simple. No type taxonomy, just a status (`open → doing → done`, plus `hold` for things parked on purpose): - **You.** The Kanban in the TUI. Open a card with `enter` and tab to its STATUS field to move it between columns; `d` on the board deletes the story outright. - **Agents and scripts.** `rove api issue-list`, `issue-create`, `issue-update` (`--status` moves a card), `issue-delete`. Issues track *what to do*; the changelog records *what shipped*. ## Where things live on disk | What | Where | |---|---| | Task index | `~/.rove/tasks.json` | | Worktrees | `~/.rove/worktrees///` | | Issue store | `~/.rove/issues.json` | | Daemon socket / log | `~/.rove/daemon.sock`, `~/.rove/daemon.log` | | Settings | `~/.config/rove/state.json` (open with `rove config`) | | Conversation history | engine-owned, e.g. `~/.claude/projects/**` | Setting `ROVE_HOME_DIR` moves Rove's home-rooted product data and compatibility runtime; `ROVE_HOME_DIR` remains a fallback. It does not relocate platform settings or engine-owned conversation stores. That's how the dev sandbox avoids touching your real `~/.rove` task data or runtime. ## Three ways people use it **Many attempts at one prompt.** Press `n` in the TUI, or script it: ```bash rove api add --repo "$PWD" \ --agents claude:2,codex:2 \ --prompt "Try independent approaches to simplify the auth flow." ``` Each attempt is its own Task with its own worktree. Workers message their outcome back to the spawning agent's engine tab (`rove api send`); compare with `rove api collect`, merge with `rove api land`. **Over SSH, on the machine your code lives on.** The daemon and PTY host run on that machine, so dropping SSH does not end hosted sessions. SSH back in and run `rove` to reattach. Clipboard and terminal notifications depend on the attached terminal connection; attention that happens while disconnected stays available in Rove's Inbox when you return. ## Glossary - **Task.** A tracked workspace record: managed worktree, or existing directory (a project's own checkout included). - **Worktree.** A git working tree on disk. Rove creates one for each managed Task; directory Tasks reuse existing directories. - **Terminal Tab.** An engine, shell, command/editor, or read-only content surface inside a Task. N per Task. - **Engine.** The coding-agent CLI a task runs on. - **Daemon.** The background process holding your task list and issues. - **PTY host.** The standalone process holding TUI/API live sessions; survives daemon restarts. - **`rove api`.** The headless surface for scripts and agents. - **Fan out / fan in.** Run N attempts of one prompt, then merge the winner.