Worktree workspaces

Pick Worktree when you create a workspace and Raven gives that conversation its own checkout of your project, on a branch of its own. Break things in it, try an approach you’re not sure about, run three of them at once — your own working copy never moves.

What actually happens

Raven uses git worktrees. A worktree is a second working directory attached to the same repository: real files on disk, a real branch, sharing the repo’s object store rather than duplicating its history.

A worktree needs a commit to start from, so in a repo with nothing committed yet the Worktree option is disabled — Nothing committed yet — a worktree would be empty. Otherwise, creating a worktree workspace:

1. Raven cuts a branch off your project’s home branch — or off the local or remote branch you choose in the from picker — and creates the worktree under ~/.raven/worktrees/<repo>/<branch>.
2. It copies in the files carried into each worktree — typically gitignored things like .env, which a fresh checkout wouldn’t have.
3. It runs the project’s setup command, if you set one, so dependencies are installed before the agent starts.
4. For an Xcode project, it creates the workspace’s iOS simulator.

That’s provisioning, and it happens in the background — the workspace shows each step as it lands. If you send a message before it finishes, the message is held and goes out once setup completes; a ✕ discards it. If a step fails, the workspace says which one and why, with Re-run setup and Edit setup command right there, rather than silently starting on a broken checkout.

The folder is nothing special — Reveal in Finder in the workspace header’s chip menu opens it. It’s your repo.

Branch names

Branches are named from a registry of birds — raven, kestrel, albatross — picked at random and given a numeric suffix if that one’s already taken locally, on the remote, or by another workspace. They’re short, memorable, and filesystem-safe, which matters more than being descriptive when you’re looking at six of them in git branch. The worktree folder takes the same name, and that name carries a line of lore, shown when you hover it in the workspace header, which is there for fun and nothing else.

The branch is where the workspace starts, not what it is. The workspace’s identity is its worktree folder, and it follows whatever branch is checked out there: switch to another branch, create a new one, or rename it from the terminal, and the sidebar, the composer’s branch readout, and the pull-request control all follow. The readout can switch back to any branch the worktree has been on (see Projects and workspaces). Ask the agent for a descriptive PR title rather than renaming the branch for the sake of it.

What isolation gives you

• Agents can’t overwrite each other’s edits, because they aren’t editing the same files.
• A dependency install, a migration, or a half-finished refactor stays inside one workspace.
• Your own checkout stays on your branch with your uncommitted work intact.
• Each workspace’s changes are reviewable on their own, as a branch and then a pull request.

One thing it is not: a security boundary. A worktree isolates work, not permissions. The agent still runs as you, on your machine, with access to the rest of it.

One branch per workspace

A worktree workspace owns its branch for as long as it exists — git won’t let two worktrees check out the same branch, so that’s a hard constraint rather than a policy. If you want to keep going on a branch a workspace already has, work in that workspace.

To build on work that isn’t merged yet, fork the workspace that has it: Fork in new worktree workspace branches from where that workspace is, not from home. See Running agents in parallel.

If the folder goes missing

Delete a worktree by hand and the workspace notices: a bar reads Worktree folder was removed. The branch is still in the repo. with Recreate, which provisions a fresh copy on the same branch, and Delete workspace. A local workspace whose project folder has gone says so too, but there’s nothing to recreate — the folder was yours.

When to use local instead

Worktrees aren’t always the right answer. Reach for a local workspace when:

• The change is small and you’d merge it immediately anyway.
• You want the agent’s edits in the files you already have open in your editor.
• Setup is slow and the isolation isn’t worth the wait.

A useful default: local for the work you’re doing, worktree for the work you’re delegating.

Housekeeping

Worktrees are real directories and they accumulate. Archiving a workspace reclaims its copy from disk while keeping the branch, the transcript, and any uncommitted work — so archiving is the cheap way to clean up, and deleting is the permanent one.