Tasks across repositories

Many changes touch more than one repository: a field in the API, its display in the app, a line in the docs. A task can do all of it. It has one part per repository, each a worktree on the same branch name. You can choose the repositories beforehand, or let the agent take in what it needs; either way you see each one the moment it joins.

Start a task across repositories

There are two ways:

In New Task…, choose no repository or several. The agent starts in a folder of its own under ~/.cavvy/initiatives, which isn’t a repository and already holds a worktree of each repository you chose. It takes in more as it needs them.
An ordinary task in one repository. It gets a second part as soon as its agent takes in another repository. The agent keeps working where it started, and cavvy task add gives it the new worktree’s path.

How the agent takes in a repository

In a task, Cavvy tells Claude Code and Codex which other repositories the project has. The agent lists them and takes in what it needs:

$ cavvy repos
cavvy task add shop-api

cavvy task add makes a worktree of that repository on the same branch, from its main branch, and prints its path. The agent works and commits there. The repository’s setup and .worktreeinclude apply as for any task; the setup runs in a side terminal while the agent goes on.

The agent isn’t limited to the project. cavvy task add ~/Developer/billing takes in another repository on the same machine, cavvy task add --clone <url> clones one first, next to the project’s first repository. Such a repository joins the project at once, marked new. See CLI.

Nothing happens unnoticed

Each part an agent takes in appears in the list at once, under its task, unread and with a notification: “… took in shop-api”. A repository new to the project also shows new in the sidebar. The task’s row shows the most urgent state of all its parts, and its parts always stand below it, never folded away. The task shows under every repository it has a part in.

A part can have a session of its own, for example one you started in it. Then the task’s agent doesn’t change that part alongside: its rules tell it to hand the work to that session with cavvy send and wait for it with cavvy wait.

Step in

When you select a task or one of its parts, a bar above the tabs offers:

Control	What it does
Take In a Repository	Adds a repository of the project yourself, the same way the agent would with `cavvy task add`.
Review All Changes…	One window with the changes of every repository, with Viewed marks kept per task.
Finish Task…	Finishes all parts together; see below.
Stop Task…	Stops every agent of the task after asking. Worktrees and commits stay; Restart continues each session.
History	Who started what, which repository was taken in, which checks passed or failed, what was merged, parked or deleted.

Check

Each part is checked on its own: Done Means runs in each repository with new commits, and each repository keeps its own checks and reviewer. Review All Changes…, also as Review All Changes of the Task… in the task’s menu, shows every repository in one window. The review window of a part lists all repositories of the task at the top; one click switches to another repository’s changes, overview and checks. A part without a session of its own gets the full review too (Open Review, ⇧⌘D); comments and Return… go to the agent working on it.

Finish together

Finish Task… in the bar, or Finish… on the task’s card, finishes all parts at once, or none. The sheet numbers the parts in the order they go in; drag to change it, because each base is pushed in turn and a push can start a deployment. Each part says what would keep it from merging.

Option	What happens
Merge All Parts	Checks every part first and merges only if none would fail. Then it merges all of them in their main folders, and only then pushes them, in order.
Open Merge Requests	Pushes each part with commits and opens a merge request there; the requests name each other. The parts stay open for review fixes.
Park All Parts	Pushes each part’s branch and removes its worktree. They wait under Parked until you resume or finish them.

Push the bases to origin and Clean up worktrees and branches are switches above the options; they start out as the project’s settings say. If checks failed in a part, nothing merges until you turn on Also parts whose checks failed. Merging and parking stop the task’s agents first.

If a push fails half way, the parts already on the server are done, and the rest stays merged here. Push the Rest Again pushes those, in order. Nothing is ever force-pushed. Once the merge requests are merged on the server, the same sheet has nothing left to merge, and its button reads Clean Up the Task.

A part that doesn’t belong in the result can go first: Remove Part… deletes it, and Cavvy keeps its work for 30 days (see Finishing a task).

You can still finish a single part with its own Finish…. Once no part is left, Remove Task in the task’s menu removes its folder.

Limits

All parts of a task run on one machine: the one with the repositories you chose, otherwise the one with most of the project’s repositories, in an empty project your Mac. A project may hold repositories of other machines, but a task can’t take them in.