Cavvy
Download

Documentation

What Cavvy changes in agents

Every change Cavvy makes to the agents it starts, and how to turn it off.

Cavvy starts your agents as they are: the official Claude Code, Codex, opencode and Gemini CLI, with their own logins and settings. Where it adds something, this page says what, word for word, and how to turn it off. All switches are in Settings → Agents → What Cavvy Changes in Agents, are on by default and apply to sessions started from then on, on every server.

Claude Code: report tool calls

Cavvy passes Claude Code a --settings with four hooks: PreToolUse, PostToolUse, UserPromptSubmit and Stop. Each runs cavvyd record-tool, which notes the call for Cavvy and always succeeds, so a hook never blocks a tool.

What it gives you: Claude Code’s questions and permission requests stand readable above the terminal, and Cavvy knows exactly when Claude Code waits for you. See Control room.

Off: questions and permissions show only once Cavvy reads them on the screen, later and less exactly. A session started with a --settings of its own never gets the hooks.

Claude Code and Codex: add the task’s rules

In a task, Cavvy appends rules to the agent’s instructions: to Claude Code with --append-system-prompt (unless the session passes its own), to Codex as developer_instructions. The two switches, Claude Code: add the task’s rules and Codex: add the task’s rules, work independently.

In a task in one repository, the rules read, with your base branch in place of main:

You work in a Cavvy task: a git worktree whose branch started from main. Commit your work on this branch. Don’t merge it into main or any other branch, don’t push, and don’t open a merge or pull request, even when the work looks done: the user reviews the task and finishes it in Cavvy, which runs the project’s checks first. If the user asks you to merge, tell them to use Finish… in Cavvy (German: Abschließen…), unless they insist.

In a project, this follows, with its name and its other repositories:

This task belongs to the Cavvy project “Shop”. Its other repositories: shop-api, shop-docs. If the task needs changes in another repository, run cavvy task add <repo>: it makes a worktree of it on this task’s branch and prints its path; work and commit there, never in the repository’s own folder. Another repository on this machine is taken in by its path (cavvy task add <path>), one that isn’t here yet by cloning it (cavvy task add --clone <url>); it then joins the project. Take in only what the task needs; the user sees every repository you take in. cavvy repos lists them. A part can have a session of its own, which cavvy projects and cavvy task add name. Don’t change such a part yourself, nor through subagents: hand that session the work with cavvy send <id> "…", then cavvy wait <id> for it to finish, and read the result in its worktree.

An agent whose task touches no repository or several works in a task folder and gets:

You work on a task in the Cavvy project “Shop”. This folder isn’t a git repository; files directly in it are lost when the task ends. The project’s repositories: shop-web, shop-api, shop-docs. Taken in already: shop-web/, shop-api/. For each repository the work needs, run cavvy task add <repo>: it makes a worktree of it inside this folder on the branch feature/checkout and prints its path; work and commit there, never in the repository’s own folder. Another repository on this machine is taken in by its path (cavvy task add <path>), one that isn’t here yet by cloning it (cavvy task add --clone <url>); it then joins the project. Take in only what the work needs; the user sees every repository you take in. cavvy repos lists them. Don’t merge, don’t push, and don’t open merge or pull requests, even when the work looks done: the user reviews each repository’s part and finishes the task in Cavvy, which runs the checks first. If the user asks you to merge, tell them to use Finish… in Cavvy (German: Abschließen…), unless they insist. A part can have a session of its own, which cavvy projects and cavvy task add name. Don’t change such a part yourself, nor through subagents: hand that session the work with cavvy send <id> "…", then cavvy wait <id> for it to finish, and read the result in its worktree.

Every variant ends with:

When the work you were asked for is finished and nothing is left for you to do, run cavvy done as your very last step: only then does Cavvy show the task as ready for review. Don’t run it when you stop to ask something, to report progress, or while work is still open.

The rules are in English, whatever language Cavvy shows.

What it gives you: the agent knows that you merge, which repositories it can take in for a task across repositories, and tells Cavvy with cavvy done when its work is finished.

Off: the agent doesn’t know the rules or the other repositories, and Cavvy counts it as done whenever it stops.

What the rule is, and what it isn’t

The rule is an instruction to the agent, not a lock. An agent that ignores it, or that you tell to push, can still run git push in its worktree; Cavvy doesn’t stop it. What Cavvy guarantees is its own side: Cavvy itself merges, pushes the base or opens a merge request only when you choose it in Finish…, in a dialog, never by shortcut and never by itself.

Agents started through a wrapper such as npx get no rules, because Cavvy recognizes only the commands claude and codex.

Always, without a switch

These don’t change what an agent does, but they are part of every session:

  • The background service puts its own cavvy command on the session’s PATH and sets CAVVY_SESSION_ID, so the CLI knows which session calls it.
  • Claude Code and Gemini CLI start with a session ID chosen by Cavvy, so the conversation can continue after a restart. See Agents.
  • On a Mac, sessions find security at /usr/bin/security, so agents can read their logins from the keychain. See Keychain & Doctor.

opencode and Gemini CLI get no hooks and no rules.

The principles behind it

  • Nothing happens unnoticed. If an agent takes in a repository, it appears in the list at once, unread, with a notification and in the history.
  • You see who started what. Each task keeps its history, across all its repositories.
  • You can step in at any time: Stop Task…, Take In a Repository, Return… with a note, line comments as a prompt.
  • Nothing reaches your main branch without you. Merging has no shortcut, it is always a dialog.
  • Nothing with consequences happens by itself. With red checks the button reads Merge into … Anyway, in red; a second opinion runs by itself at most twice.
  • Limits are visible and adjustable, on this page.