DOCS / CONCEPTS

The worktree-first model

This is the one idea Birch is built on: agents never work in your checkout. Every agent workspace gets its own fresh git worktree on a new branch, created under Birch’s data folder. Your own working directory is never touched, agents can run in parallel without stepping on each other, and “reviewing the agent’s work” is always a clean diff against the base branch.

A 30-second worktree refresher

A git worktree is a second (third, tenth…) working directory attached to the same repository. It’s a standard git feature, not a Birch invention:

One repository, one object store. All worktrees share the same commits, branches, and history — nothing is cloned twice.
Each worktree is a separate directory with its own checked-out branch, its own index, and its own working files.
A branch can only be checked out in one worktree at a time, so two directories can never fight over the same branch.

If you’ve ever kept a second clone around just to test something on another branch, a worktree is that — without the duplicate history and the separate remotes.

Birch’s rule

Every agent workspace Birch creates is:

A fresh worktree in its own folder under Birch’s data directory — never inside your repository.
On a new branch, created from the repository’s default branch (or the base branch you pick in the create-workspace dialog — “The new worktree and branch are created from this branch”).
Where everything in that workspace runs. The agent, any extra terminal tabs, and all git operations on the workspace’s Git tab operate on the worktree’s path, not your checkout.

Branch names Birch generates look like birch/terminal/0317168d — unique, machine-made names, since the branch’s identity is the workspace, not a ticket.

 your clone (untouched)          Birch's data folder
 ~/dev/my-repo                   workspace A          workspace B
 branch: main                    birch/terminal/7f2…  birch/terminal/d41…
      │                               │                    │
      └───────────────┬───────────────┴────────────────────┘
                      ▼
          one shared git object store
          (commits, branches, history)
                      │
                      ▼
                origin (remote)

What this buys you

Parallel agents without conflicts. Three agents on three tasks means three worktrees on three branches. None of them can see the others’ uncommitted files, and none of them can switch a branch out from under another.

Your uncommitted work is safe. The agent never runs in your checkout, so your half-finished refactor, your stash-worthy experiments, and your local config stay exactly where you left them.

Review is always a clean diff. Because a workspace starts from a known base branch, “what did the agent change?” has a precise answer: everything in the worktree versus that base — committed, staged, unstaged, and untracked alike. That’s what the workspace’s Review tab shows; see Review agent changes.

Disk cost is a checkout, not a clone. Worktrees share the object store, so each workspace costs roughly one set of working files — plus whatever the agent generates there (dependency installs, build output). Budget accordingly for repos with heavy node_modules-style trees.

Where worktrees live — and how they’re cleaned up

Workspace worktrees are created under Birch’s data folder: ~/Library/Application Support/birch/ on macOS, %APPDATA%\birch\ on Windows. See Storage & data for the full layout.

Worktrees are deliberately kept on disk after the agent exits. A workspace isn’t a throwaway sandbox: it appears in the repository’s worktree list, survives app restarts, and can be reopened later (see Resume and restart).

When you’re done with one, remove it — worktree, branch and all — with birch worktree rm:

birch worktree rm my-branch --delete-branch

Deletion is guaranteed: if a plain removal fails (a dirty or locked worktree), Birch escalates to a forced removal and, as a last resort, deletes the folder directly — the workspace always disappears from Birch either way.

Gitignored files: `.env` doesn’t travel — unless you say so

A fresh worktree contains exactly what git tracks. Files git ignores — .env, local secrets, machine-specific config — exist only in your original checkout, so a plain git worktree add would leave the agent without them and your dev server broken.

Birch closes that gap with carryover: when it creates a worktree, it copies gitignored files matching .env* (the built-in default) from your source checkout into the new worktree. To carry more (or less), put a .worktreeinclude file at the repository root — it uses gitignore syntax and replaces the default pattern entirely. Carryover is best-effort by design: a problem copying files logs a warning but never blocks workspace creation.

See .worktreeinclude for the pattern rules and edge cases.

Migrating an existing clone

Birch also contains a migration flow that converts a regular clone into a bare repository plus a primary worktree on the default branch, preserving the original folder unless you opt in to remove it.

You don’t need it to use workspaces: Birch creates worktrees against your ordinary clone as-is.