Raven
All docs

Concepts

Running agents in parallel

The workflow Raven is built for — several agents working at once on isolated copies of the same repo, and how to keep track of them.

One agent is easy to supervise: you watch it work. Four is a different job. The bottleneck stops being the model and starts being you — knowing which one needs an answer, which one is still going, and which one just finished and is waiting.

Raven’s answer has two halves. Worktree workspaces make it safe to run several agents at once. The sidebar makes it legible.

Starting work in parallel

Create a worktree workspace per piece of work and send each one off. Because every workspace has its own checkout and branch, they don’t interact: two agents can install different dependencies, rewrite the same file, and run the same test suite at the same time without any of it colliding.

The New Workspace dialog’s (⌘⇧N) Start in background, in the send button’s menu, leaves you where you are while the new workspace provisions and starts, which is the natural way to fan out. The choice sticks for next time.

There’s no ceiling in the app. The practical limit is your machine and your plan’s rate limits.

Keeping track

The left sidebar is the control surface. Workspaces sort themselves into In progress while an agent is working and Inbox when it stops, so “what needs me?” is a glance rather than a hunt. Workspaces you haven’t looked at since the agent finished carry an unread marker. Pin the ones you’re actively steering and drag them into the order you think in.

Next unread — the pill above the composer, or ⌘⇧U — steps through what’s waiting: the next unread tab in this workspace, then the next unread workspace, then the next pinned one (the pill reads Next pinned once nothing is unread).

Each worktree workspace also shows how its branch stands relative to your home branch — commits ahead and behind, until it’s merged — and, once a pull request exists, what state it’s in. You can watch a set of branches converge without opening any of them.

Forking a conversation

Sometimes the fork you want is in the conversation, not the repo. The ⋯ on any reply offers to branch the chat from that point, which is the fix for a turn that went wrong: fork just before it, rephrase, and go again.

Where the fork lands is your choice, and it’s a separate question from isolation:

Fork to What you get
A new tab Same workspace, same checkout — a side thread on the same work.
A new workspace New workspace in the sidebar, still your project folder — a new exploration you want tracked separately. Offered from local workspaces.
A new worktree workspace New workspace with its own branch and copy — the isolation fork. From a worktree workspace, the branch starts where that workspace is.

A tab’s right-click menu offers the same three as Duplicate, carrying the whole conversation. Either way, a fork into a new workspace starts from what’s committed — uncommitted work stays where it was — and nothing can be forked or duplicated while its tab’s turn is still running.

Running several tabs in one workspace

Parallelism doesn’t have to mean parallel branches. A workspace can hold several chat tabs, all against the same checkout, which is the right shape when two conversations are genuinely about the same change — one writing the code, one reading it back. Just remember that tabs in a workspace share files: they can overwrite each other exactly the way local workspaces can.

Practical notes

  • Give each workspace one job. The clean-branch, clean-PR payoff depends on the branch containing one reviewable change.
  • Set a setup command. Every worktree runs it, so a project that needs pnpm install should say so once rather than in every conversation. See Project setup.
  • Archive when you’re done. Reclaims the disk, keeps the history. See Archiving and deleting.
  • Keep your Mac awake. Raven holds it open while agents run; the switch is Settings › General › Power › Keep your Mac awake, on by default.