Quick start

Rove is an agentic development environment (ADE) for your terminal: one window where Claude Code, Codex, Copilot and other coding agents work side by side and hand tasks to each other. Each managed Task gets its own git worktree and branch, so parallel Tasks never step on each other. Extra tabs inside one Task share that Task's directory.

You need git and at least one engine CLI on your PATH. Rove ships built-in support for claude, codex, copilot, kimi, pi, omp and bob (IBM Bob), and launches gemini, opencode, cursor-agent, grok, droid, amp, devin, qodercli, cline, kiro-cli, maki, agy (Antigravity), hermes, kilo, and mastracode too — the full list, and how to add your own, is in Engines.

The Rove CLI itself runs on the Bun runtime (≥ 1.3.11). You do not have to install Bun yourself; every route below brings it along.

Windows also requires Node.js and Git for Windows. Rove uses Node.js for its Windows PTY host and Git Bash as the POSIX shell behind engine and terminal tabs. Restart Rove after installing either one so the new executables are on PATH.

Install

macOS / Linux

Run this in a POSIX shell. It installs Bun if it is missing, then Rove:

curl -fsSL https://rove.run/install.sh | sh

# pin a version
curl -fsSL https://rove.run/install.sh | sh -s -- <version>

Or use a package manager you already have:

npm install -g @sma1lboy/rove   # npm; the first launch offers to install Bun
bun install -g @sma1lboy/rove   # bun
npx @sma1lboy/rove              # try it without installing

Native Windows (PowerShell)

Install Node.js and Git for Windows including Git Bash, then restart your terminal so node, npm and git are on PATH. Use the npm route; do not paste the POSIX curl … | sh command into PowerShell:

npm install -g @sma1lboy/rove

WSL

Use the Linux instructions inside your WSL distribution. Install git and your engine CLI and sign in inside WSL too. Native Windows installations and their login state are not substitutes for the Linux environment.

Runtime troubleshooting

Rove looks for Bun on PATH, in $BUN_INSTALL/bin, in ~/.bun/bin, and in a bun npm package installed beside Rove. If yours lives somewhere else, point Rove at it with ROVE_BUN=/path/to/bun. To never be asked about installing Bun (CI, images, locked-down machines), set ROVE_NO_BUN_BOOTSTRAP=1. Rove then prints the install commands and exits.

A Bun older than 1.3.11 is refused rather than used: Rove's terminals need Bun's PTY API, and on an older Bun every terminal and engine tab opens empty with no error. install.sh upgrades a self-installed Bun for you and tells you the command for a Bun it does not own; the launcher skips a too-old Bun in favour of any newer one on the machine.

Check one engine is ready

You only need one engine for this walkthrough; use the same one for both tasks. Install and sign in to its own CLI first, then run:

rove doctor

Expected: git is found, your engine binary is found, and (where supported) its login check succeeds. A binary-only check is not proof of authentication; open that engine directly to confirm it can answer a short prompt. Missing a CLI or login? Follow Doctor's instruction before creating a task. Rove does not sign you in or supply a provider subscription. See Engines.

First launch

Open a small repository you are comfortable experimenting in, with at least one commit and a clean checkout. Make sure the two rove-onboarding-*.txt filenames below do not already exist. Avoid production credentials for this exercise.

cd your-repo
rove

The welcome dialog first checks installed engines and accounts. If none is usable, it explains how to install an engine and sign in. Press enter to continue to optional shell completions and the agent skill, followed by Keyboard basics. Choose with j/k or the arrow keys and confirm with enter. Not now skips an install; accepted installs run after you quit. esc skips unanswered questions and preserves earlier confirmed choices.

With no tasks and a usable engine, the welcome panel offers Start a task with a prompt when you launched Rove inside a Git repo with a commit. Click it, type a prompt, and press enter to create an isolated worktree and open its engine tab. It defaults to the current repo and branch and a usable engine. n still opens the full task dialog for repository, engine, and task intent.

The first ctrl+t also shows a one-time reminder that tabs share the current task's files. It creates the tab immediately, without a confirmation. Settings → Engines lists integrations; rove doctor checks the environment again.

Using Codex? In its engine pane, open /hooks and review/approve the Rove hook command yourself. Rove writes the definition but does not grant this trust for you. Until events arrive, do not treat a quiet badge as proof that work has finished. A short prompt below checks both output and activity; Engines → Activity badges explains the limits.

Your first task: A, one visible result

1. Focus the Tasks sidebar (click it, or press ctrl+q from the workspace), then n. In For Existing, choose this repo, its current base branch and your ready engine. If an opens choice appears, keep a new task worktree, not the project itself. Create the task.

2. Expected: a new managed Task with its own branch and a directory under ~/.rove/worktrees/. Rename the task A — first result with r from its sidebar row. Open its engine tab with enter.

3. Send this deliberately small prompt in the engine pane:

   Create rove-onboarding-a.txt containing exactly "Task A works" and a newline.
   Do not change other files, commit, push, or install dependencies.
   Show the file contents, your current directory, and git branch --show-current.

4. Answer any engine permission question after reviewing it. Expected: the engine reports the file contents and its worktree path/branch. In Files → Changes, select rove-onboarding-a.txt and press d to read its diff. You should see one added line, Task A works. Actual output and the diff are the success check, not a spinner stopping.

Three panes: Tasks, Workspace, Files. Click any pane to focus it. F1 explains shortcuts for your current focus; the screenshot illustrates the layout, not the exact output of this exercise.

Your second task: B, switch and prove isolation

1. Return to the sidebar with ctrl+q, press n, and create another managed task from the same original base branch and same engine. Name it B — separate files. Do not use ctrl+t: that creates another conversation in the same Task directory, not an isolated attempt.

2. Send this prompt:

   Check whether rove-onboarding-a.txt exists here and report the result.
   Create rove-onboarding-b.txt containing exactly "Task B works" and a newline.
   Do not change other files, commit, push, or install dependencies.
   Show your current directory and git branch --show-current.

3. Expected: B cannot see A's uncommitted file. B has a different worktree path and branch; its Changes pane shows rove-onboarding-b.txt.

4. Press ctrl+q, use arrow keys to select A's engine tab, then enter. Expected: A's conversation and rove-onboarding-a.txt are still there; B's file is absent. Switch back to B the same way. Sidebar / searches task titles if you have many tasks.

The isolation boundary is a managed Task. Extra tabs and splits share its files. Project-main tasks and rove . directory tasks use your existing checkout; they do not create an isolated branch/worktree. This exercise specifically creates two managed tasks via n.

Read state, then detach and return

While B answers, switch to A. For engines with activity tracking, B's tab can show a spinner while working and ● when a turn finishes unread; opening B consumes that completion and returns it to ○. ! asks for your attention. ○ can also mean idle or not observed, so check the actual engine output when tracking is unavailable. States vary by engine; they are not a universal completion guarantee.

Open the Inbox with ctrl+a then i, or use F7 to jump to a pending item. Expected: a tracked completion or request points to its task/tab. Visiting it clears the item; an empty Inbox after you already opened both tabs is normal. See The TUI for attention and recent visits.

Press ctrl+q to focus Tasks, then ctrl+q again to quit. Run rove again. Expected: A and B and their files remain. Quitting the TUI or dropping SSH detaches; live engines keep working while their host stays awake. This exercise does not stop processes, delete tasks or merge either branch.

• Host sleep / laptop lid: local work does not keep computing while the host sleeps; connections may need recovery after wake. Closing a laptop used only as an SSH client leaves work on an awake remote host running.
• Daemon restart: live PTYs are hosted separately and survive it.
• Host restart / reboot: processes end. Attach restores saved screens and relaunches commands; conversation resume depends on the engine. Restored output is not evidence that the interrupted turn completed. Review it and send the next instruction if needed. See Sessions.

Desktop notifications need an attached TUI and a terminal supporting OSC 9. While detached, consult the durable Inbox on return instead.

Install the agent skill

The companion skill teaches your coding agent (Claude Code, Codex, and so on) how to drive Rove itself: spawn tasks, fan a prompt out to several attempts, compare them, land the winner.

The welcome guide offers it on first launch, with Yes preselected. Until every coding agent set up on this machine has it, Rove keeps a ROVE SKILL NOT INSTALLED strip at the top of the window (TUI and web) naming the agents that lack it; click it to install. Settings → Engines shows each engine's copy and has the same Install button, and rove skill install / rove skill status do it from a shell. Installed copies refresh themselves when Rove upgrades.

Claude Code users have a one-stop alternative: the Rove plugin carries the skill AND the activity hooks in one install, with no PATH or settings.json setup:

/plugin marketplace add Sma1lboy/rove
/plugin install rove@rove

If you were already running Rove before installing the plugin, run rove hook cleanup once afterwards. Details in Configuration → Claude Code plugin.

Optional: run many attempts at once

After the two-task exercise, you can automate independent attempts. This example requires both Claude Code and Codex installed and authenticated:

rove api add --repo "$PWD" \
  --agents claude:2,codex:2 \
  --prompt "Try independent approaches to simplify the auth flow."

Compare the attempts, then land the winner:

rove api collect --task-ids a,b,c      # read-only comparison
rove api land --task-id a              # merge the winning branch

Let your agent drive

With the agent skill in place, you do not have to type those commands yourself. Ask your coding agent for three attempts at a prompt; it runs the rove api loop above and reports back which branch to land.

If something's wrong

rove doctor            # check daemon, engines, git
rove doctor --report   # write a bundle for a bug report

More fixes in Troubleshooting.

Design preview (not the walkthrough)

The following launch film is a concept preview, not a recording to follow step by step. Use the current-interface walkthrough above for your first tasks.

The launch film, 50 s. Parts of its UI are a design preview that Rove doesn't ship yet: the island layout and its colors, the one-line launch bar, the six-agent grid, the lanes timeline, and the glance pill.

Next steps

• Concepts: tasks, sessions, and what survives what.
• The TUI: status glyphs, the Inbox, diff review, and the pages.
• CLI reference: every rove command.
• rove api: the scriptable surface for scripts and agents.
• Configuration: engines, themes, notifications.