CLI

The cavvy command talks to the same background service as the window. You use it to start sessions, hand them text, wait for them and look at what they changed. Agents in a task use it too, to find and take in other repositories.

$ cavvy send 3f9c2a1e "Add token refresh and run the tests"
$ cavvy wait 3f9c2a1e
idle
$ cavvy diff --stat 3f9c2a1e
  +24    -6  src/auth/middleware.ts
  +11    -2  src/auth/session.ts
  +38    -0  test/auth.test.ts

Install it

Settings → Command Line → Install Symlink puts cavvy into ~/.local/bin, pointing into the app. If that folder isn’t on your shell’s PATH yet, the same page shows the line to add. On a server, Cavvy installs the command next to its background service in ~/.local/bin.

Inside a Cavvy session you don’t need any of this: the background service puts its own cavvy on the session’s PATH.

Start a session

$ cavvy new --worktree feature/x -- claude

Everything after -- is the command; without one, the session starts your login shell. --worktree <branch> gives the session a worktree of its own on that branch, --base sets where a new branch starts (by default the current branch), --name and --cwd set the name and folder. The command prints the session’s ID.

List, send, wait

$ cavvy ls

Lists every session with its ID, state (starting, working, BLOCKED, idle, exited), name, folder and branch. The other commands take an ID from this list.

$ cavvy send <id> "Run the tests and fix what fails"

Types the text into the session and presses Enter; --no-enter leaves Enter out. cavvy screen <id> prints what the session shows right now.

$ cavvy wait <id>

Blocks until the session needs you or is done (blocked,idle). --until takes other states (working, blocked, idle, exited, comma-separated), --timeout a number of seconds. It prints the state it reached.

Look at the changes

$ cavvy diff --stat <id>

Shows what changed in the session’s folder since its worktree’s base branch, or the uncommitted changes outside a task. Without --stat you get the full patches.

For agents

An agent in a Cavvy task uses these commands to say when it is done and to work across repositories. Cavvy tells agents about them in the task rules; they only work inside a Cavvy session.

$ cavvy done

Says that the work asked for is finished. Only then does Cavvy show the task as ready for review once the turn ends; an agent that stops without it waits under Needs You. See Control room.

$ cavvy repos

Lists the repositories of the task’s project on this machine, one per line. The task’s own repository is marked (this task). cavvy projects still works as an alias.

$ cavvy task add shop-api

Makes a worktree of that repository on the task’s branch, starting from its main branch (after fetching from origin, if there is one), and prints its path. The agent works and commits there. The task now spans repositories: the new part shows up in your list at once, unread, with a notification, and the repository’s setup runs beside the agent.

$ cavvy task add ~/Developer/billing
cavvy task add --clone [email protected]:shop/billing.git

A path takes in another repository on the same machine; --clone clones one first, next to the project’s first repository (in a project without one, into ~/Developer). Either way the repository joins the project at once, marked new, with a notification. task add only works from a task or a task’s folder; a name the project doesn’t know is refused with the list of its repositories.

If a part already has a session of its own, the agent hands it the work with cavvy send <id> "…" and waits with cavvy wait <id> instead of changing the part itself.

Agents on a machine

$ cavvy agents

Shows which coding agents the machine has, in which version, whether they are signed in and whether an update is out. --install <agent>, --update <agent> and --login <agent> run the official installer, the update or the sign-in in a new session and print its ID. With --host, Codex signs in with a device code. Settings → Agents does the same in the window.

More commands

ls, repos, status, doctor and agents take --json for scripts.

On a server

--host (short -H) runs any command on a server, with the host alias from your SSH configuration:

$ cavvy --host build ls

See Servers.