Quickstart

This tutorial takes you through the golden path once, end to end: add a repository, understand in sixty seconds why Birch creates a worktree for every workspace, launch a Claude workspace with a prompt, watch it work, review the diff, and open the pull request. Every step links to the deeper page for when you need more.

1. Add a repository

Click Add repository on the Repositories dashboard, or the + next to Repositories in the sidebar. The dialog has two tabs:

• Local path — point Birch at an existing checkout. The folder must contain a .git directory. Nothing about the checkout is changed.
• Clone URL — paste a URL such as https://github.com/org/repo.git, pick the destination folder and a name.

Click Add. More options are covered in Add repositories.

2. Sixty seconds on worktrees

Birch never works inside your checkout. Every workspace it creates is a git worktree — a second working directory sharing the same repository — on a fresh branch cut from the base branch, placed under Birch’s own data folder:

text

~/dev/your-repo/                     ← your checkout — Birch never touches it

Birch data folder/
└─ repositories/<repoId>/terminals/
   ├─ a1b2c3d4/    ← workspace 1 · branch birch/terminal/a1b2c3d4
   └─ e5f6a7b8/    ← workspace 2 · branch birch/terminal/e5f6a7b8

Agents can therefore run in parallel, each on its own branch, and nothing they do can dirty your working copy. Git-ignored local files matching .env* are copied into each new worktree so builds keep working; the pattern list is customizable via a .worktreeinclude file. The full story is in the worktree-first model.

3. Launch a workspace

Click the + on a repository row (its tooltip is New agent workspace). The Create Workspace dialog opens:

• Agent — Claude, Codex, OpenCode, or Custom command. Picking Claude adds a row to choose a model, effort, and permission mode.
• Base branch — “The new worktree and branch are created from this branch.”
• Prompt (optional) — what the agent should work on.

Click Create workspace. Birch creates the worktree, opens its embedded terminal, starts the agent, and types your prompt as an editable, unsubmitted draft — read it over, adjust if you like, then press Enter to send. All the options are covered in Create a workspace.

4. Watch the status

Each workspace row in the sidebar carries a live status indicator next to the agent’s brand mark: a spinner while the agent is working, an amber indicator when it is waiting for your input, and a check mark when the turn is done. Waiting agents also surface as Inbox rows and desktop notifications, so you can leave the screen and come back when needed. Details in Monitor status and usage.

Tip

Live status is pushed by the birch-status plugin for Claude Code. Birch offers to install it on first run when the claude CLI is present; you can also install it any time from Settings → Claude Code. See the birch-status plugin.

5. Review what the agent did

Open the workspace’s Git tab and switch to the Review sub-tab — or click Review changes in the workspace properties panel. Review shows everything this worktree changed versus its base branch — committed, staged, unstaged, and untracked — with a header like vs main — 4 commits, 12 files.

Read the diff file by file; the Changes sub-tab is there when you want to stage, tweak, or discard before shipping. Details in Review agent changes.

6. Open the pull request

Click Create PR in the workspace properties panel. The dialog prefills the title and description from the agent’s own session title and the branch’s commits; tick Create as draft if you want a draft PR, then click Create PR.

You need a connected GitHub, GitLab, or Azure DevOps account first — connect one in Settings → Integrations (see Integrations). The full flow, including the AI title button, is in Create a pull request.

Day-one surprises

• “My local config file is missing in the workspace.” A fresh worktree contains only tracked files plus git-ignored files matching Birch’s carryover patterns (.env* by default). Add other local files to a .worktreeinclude file at the repo root.
• “There is no ✨ button next to the commit message.” The commit-message ✨ button is an Anthropic API feature and appears only when the ANTHROPIC_API_KEY environment variable is set — see Anthropic API key. The ✨ button in the Create PR dialog is different: it runs your own agent CLI on your own subscription.

Where to go next

• Inbox — tasks, PR activity, and waiting agents in one list
• Provider integrations — connect GitHub, GitLab, Azure DevOps, Jira, Linear, or YouTrack
• The birch-status plugin — the machinery behind the live status discs