Tasks

A task is one brief for one agent, in one project. It gets a branch of its own and, in each repository it touches, a worktree of its own, so agents working in parallel don’t get in each other’s way, and the repositories’ main folders stay untouched.

New Task…

New Task… (⌘N, or the button at the top of the window) asks for:

• Project: the project the task belongs to.
• Repositories: the repositories it works in, as chips. A project with one repository has it chosen; with none or several, the task works across repositories.
• Assignment: what should happen. Describe the result, not the steps. Drop images into the sheet, paste a screenshot or attach files with the paperclip; the agent gets their paths with the assignment. The microphone starts macOS dictation.
• Agent: Claude Code, Codex, opencode, Gemini CLI or a shell. For Claude Code and Codex the sheet shows the current five-hour usage and when it is free again.
• Approach: Start right away, or with Claude Code Plan first.
• Branch: the prefix comes from the project’s settings, you type only the rest. Left empty, the branch is named after the assignment.
• Base and server: the branch it starts from, and where it runs.

Start creates the branch, here feature/ plus the first words of the assignment, and the worktree under ~/.cavvy/worktrees. Change the prefix per project under Project Info → Settings → Tasks.

The worktree is a normal folder. Open it in your editor, run things in it, look around: it’s yours as much as the agent’s.

Start from the latest state

Pull the base from origin first fetches the base branch from origin before the task starts, so the agent doesn’t work on yesterday’s code. Cavvy only moves forward; where that isn’t possible, the task starts from the local branch and says so. You set the default per project in Project Info → Settings → Tasks and can turn it off in the sheet.

Setup

A fresh worktree holds only what git tracks: no node_modules, no .venv, no vendor. Setup, on the repository’s page under Settings, lists commands that run in the new worktree before the agent starts. Under Found: Cavvy suggests them from the lockfiles in the repository:

The commands run one after another in a side terminal named Setup, which stays open so you can read how it went. The agent waits meanwhile; the card says so and offers Start Now to let the agent begin while the setup goes on.

If a command fails, the agent starts all the same, and the task moves to Problems with Setup failed. Show Setup opens the side terminal, Dismiss takes the task out of Problems.

The commands live in the repository’s git config, not in a commit.

Copy ignored files: .worktreeinclude

Small ignored files a task needs, such as a local tool config, can come along. List them in a .worktreeinclude in the repository, with the same syntax as .gitignore:

$ mise.toml
.env.local

Cavvy copies the files that match a pattern and are ignored by git, before the setup runs. On a Mac it clones them (copy-on-write), so even large folders cost no space. Without a .worktreeinclude, nothing is copied: copying secrets unasked would be the wrong default.

While the agent works

The task stands under Working. When the agent asks something, or stops before it ran cavvy done, it moves to Needs You; when it is done with new commits, Done Means checks the work. The task’s three tabs show Terminal, Changes and History. ⌘J opens a side terminal in the same worktree.

In a task, Cavvy tells Claude Code and Codex to commit on the task’s branch, but not to merge, push or open merge requests. The exact wording is on What Cavvy changes in agents.

When it is done

Look at the changes in the review window, send them back with notes if needed, and end the task with Finish….