Parallel agents
Run several agents on one repository without collisions — worktrees, subagents, workflows, steering and the Board — and what's still in preview.
Running agents in parallel only helps if their work doesn't collide and you can keep up with reviewing it. This page covers what Cusp does today to keep parallel work apart and visible, and marks what's still coming.
What works today
One worktree per writer
A worktree is a second checkout of your repository on its own branch. Changes in one worktree don't touch your working copy or any other worktree, so agents in separate worktrees can edit the same files without stepping on each other.
- Sessions can run in their own worktree. Start one in a worktree whenever you want a second agent working on the same repository as the first.
- Race lanes always get one worktree each in a git repository. See Race.
- Subagents that write can ask for one with
isolation: worktreein their definition. The worktree is cut from the parent session's branch. - Read-only subagents (exploring, searching, reviewing) share the parent's folder, which keeps them fast.
Worktrees live under the Cusp data directory (~/.cusp/worktrees/ by default; set worktreeDir to change it), never inside your repository.
Within a single folder, Cusp keeps one writer: the main session edits the workspace, and helpers that need to write get their own worktree.
Subagents and workflows
A session can hand work to subagents, and run several at once. Each works in its own context and reports back a result, so the parent's context isn't filled with everything the subagent read.
For larger fan-outs, the agent can write a workflow: a short script that starts agents in parallel or in a pipeline, with a fixed shape you can read before it runs. Starting a workflow is a mutating action, so it asks for permission in the default, plan and auto modes. Saved workflows are picked up from .cusp/workflows/ and ~/.cusp/workflows/ (and the .claude equivalents). Turn workflows off with "disableWorkflows": true in settings or CUSP_DISABLE_WORKFLOWS=1.
Steering a running agent
You don't have to wait for an agent to finish to change its course.
- Messages you send while a session is working are queued. You can edit or remove them, and they're sent in order when the session is free.
- Send now (⌘↵ / Ctrl+Enter on a queued message) delivers the message to the running turn instead. The agent reads it at its next step, between tool calls, and adjusts.
- Interrupt with Esc to stop the turn outright.
Agents can also message each other. A message from another agent arrives as information, never as an instruction from you, and can't grant permissions. A message to a session running with more autonomy than the default waits for your approval.
The Board
The Board (in the sidebar) shows every session as a card in one of five columns:
| Column | Sessions that are |
|---|---|
| Working | Running a turn |
| Needs you | Waiting for a permission, an answer or a plan approval |
| Ready for review | Finished with changes you haven't looked at |
| Done | Finished |
| Failed | Stopped with an error |
When more than five sessions are working at once, the Board points out that review is now the bottleneck. That's the moment to clear the inbox and the Ready for review column before starting more.
In preview
The features below are designed and built as a tested library, but not yet running in the daemon or visible in the app. They're listed so you know what's coming, not as something you can use today.
| Feature | What it will do | Until then |
|---|---|---|
| Shared rate limits | One scheduler shares each provider's rate limit across every running agent, adapts concurrency from the provider's headers, and backs off on quota errors, so parallel agents don't trigger waves of 429s | Each session retries rate-limit errors on its own. Keep large fan-outs to a handful of agents per provider key |
| File leases | Writers announce which files they're editing on a shared board, so overlapping work is flagged before it conflicts | Give each writer its own worktree |
| Merge queue | Finished work lands one change at a time: rebase onto the base branch, run your checks, resolve conflicts with an agent, then merge. Failures go to the inbox | Merge worktree branches yourself, or ask the agent in that session |
| Mission control | A live tree of every run, with pause, resume, cancel and re-budget for any branch of it | Use the sidebar, the Board and the inbox |
Tips
- Give each parallel agent a clearly separate task. Parallel work pays off for independent changes; it rarely helps when every agent needs the same files.
- Use read-only subagents freely for exploration. They're cheap and don't need worktrees.
- Watch your budgets. Four agents spend four times as fast.