Worktree spaces

Pick Worktree when you create a space and Astra 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

Astra 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.

Creating a worktree space:

1. Astra branches off your project’s home branch and creates the worktree under ~/.astra/worktrees.
2. It copies in any files you listed as seeds — 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.

That’s provisioning, and it happens in the background. If you send a message before it finishes, the message waits and goes out the moment the worktree is ready. If a step fails, the space says which step and why rather than silently starting on a broken checkout.

The folder is nothing special — right-click the space to reveal it in Finder, or open a terminal in it. It’s your repo.

Branch names

Branches are named from a registry of stars and other celestial things — sirius, polaris, vega — picked at random and given a numeric suffix if that one’s already taken locally or on the remote. They’re short, memorable and filesystem-safe, which matters more than being descriptive when you’re looking at six of them in git branch. Each one carries a one-line piece of lore on the branch pill in the space header, which is there for fun and nothing else.

Rename the branch yourself if you want something meaningful before opening a pull request.

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 space.
• Your own checkout stays on your branch with your uncommitted work intact.
• Each space’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 space

A worktree space 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 space already has, work in that space.

New worktree spaces always start from the project’s home branch. To build on work that isn’t merged yet, fork the space that has it — a worktree fork branches from where that space is, not from home. See Running agents in parallel.

When to use local instead

Worktrees aren’t always the right answer. Reach for a local space 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 space 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.