Cavvy
Download

Documentation

Getting started

From download to your first task in a few minutes.

Install Cavvy

Download Cavvy for macOS 26 Tahoe or newer. It runs on Apple Silicon and Intel Macs and is signed and notarized. Cavvy starts its background service in your login session; sessions run there, not in the window.

The window

Cavvy has three columns:

  1. The sidebar on the left: the project switcher at the top, below it All Tasks and the project’s repositories, Usage at the bottom. A repository on a server says where it runs.
  2. Tasks in the middle, sorted by what they need from you: Needs You and Problems first, then Ready for Review, Automatic Check, Working, Resting, Parked and Merged Today. See Control room.
  3. The task on the right: its terminal, its changes and its history.

Set up your agents

Settings → Agents shows which agents each machine has: Claude Code, Codex, opencode and Gemini CLI. Install…, Update… and Sign In… run the official installer, the update or the sign-in in a new session, so you see what happens. Each agent uses its own login; Cavvy doesn’t need an account.

Add a project

A project is a set of repositories you put together. In New Project… (⇧⌘N), From: offers Existing Folder, Clone from an address, Start Empty, or No Repository Yet. Then pick the server the repository lives on, a name and, for an existing folder, an icon. Add Repository… in the project switcher adds more.

If your repositories sit side by side in one folder, choose that folder: Cavvy lists them, and the ones you check join the project. See Projects & repositories.

Tell Cavvy how each repository works

Click a repository in Project Info (⌘I) for its page. Its Settings hold what Cavvy needs to know; each section offers suggestions it found in the repository under Found:.

  • Setup: commands that prepare a new worktree before the agent starts, such as pnpm install --frozen-lockfile. See Tasks.
  • Done Means: commands that check the work when an agent is done, such as make test. See Done Means.
  • Review: whether a second opinion reads each change, and which agent gives it.

Give the first task

New Task… (⌘N): choose the project and its repositories, write what should happen, pick the agent and press Start. Cavvy creates a branch and a worktree, runs the setup and starts the agent there. The task shows up under Working, and when the agent needs you, under Needs You.

The worktree is a plain folder: open it in your editor whenever you like. Cavvy doesn’t bring an editor of its own.

Next