Create a workspace

A new workspace is one click from almost anywhere in Birch. This page walks the pre-launch dialog — agent, model, effort, permissions, base branch, prompt — and explains what actually happens when you click Create workspace: a fresh worktree on a new branch, your gitignored essentials carried over, and the agent booted with your prompt waiting as an editable draft. For the ideas behind the model, see Agent workspaces and AI in Birch.

Where to start one

Entry point	How
Sidebar	The always-visible + on any repository row (New agent workspace), or right-click the row → Add workspace
Repository page	The New workspace button in the page header
Repositories dashboard	The per-row + (New agent workspace) in the ALL REPOSITORIES list
Workspace screen	The Create workspace button on the empty state
Inbox	Start workspace on a task — see Start a workspace from a task
CLI	birch worktree new <ticket> creates the worktree directly, with no dialog and no agent launched — see birch worktree

Every GUI entry point opens the same Create Workspace dialog: “An isolated git worktree on a new branch, with a terminal running the chosen agent.”

The agent picker

The segmented Agent control offers Claude, Codex, OpenCode, and Custom command. Picking Custom command reveals a text box for the exact command to run (for example aider or /usr/local/bin/my-agent). Custom agents are launched verbatim — Birch never adds flags it can’t be sure the CLI understands.

Model, effort, and permissions (Claude only)

When Claude is selected, a Model · Effort · Permissions row appears. All three default to Default, which means “pass no flag — let Claude Code decide”.

Model. The always-visible entries are family aliases: Default (Claude Code’s own model), Opus, Opus · 1M, Sonnet, Sonnet · 1M, Haiku, Fable, and Fable · 1M (Haiku has no 1M-context variant). An alias always resolves to the newest version your installed Claude Code offers — as the dialog’s help text puts it: “Opus / Sonnet / Haiku / Fable run the newest version your Claude Code offers — run claude update to get newer ones.” The More versions… row expands a curated SPECIFIC VERSIONS list of pinned ids — Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Opus 4.5, Sonnet 5, Sonnet 4.6, Sonnet 4.5, Haiku 4.5, and Fable 5 — each showing its raw model id, so a “no such model” error on an older CLI is self-diagnosing.

Effort. Default, Low, Medium, High, Extra high, Max, and UltraCode. UltraCode is not a real effort level — instead of an --effort value it enables Claude’s session-scoped UltraCode mode via a --settings file that Birch manages.

Permissions. Seven modes, passed to claude --permission-mode: Default, Accept edits, Auto, Bypass permissions, Manual, Don’t ask, and Plan.

Base branch

The new worktree and branch are created from the branch you pick here; it defaults to the repository’s default branch. Birch names the branch itself (workspace branches look like birch/terminal/0317168d), so there is nothing to type.

The prompt

The optional Prompt field (“What should the agent work on?”) is delivered to the agent once its input is actually listening — but as an editable draft, never auto-submitted. You can reword it, extend it, or clear it before pressing Enter yourself. Launching from an Inbox task pre-seeds this field with a brief of the task, including the local paths of any images Birch downloaded from the task description.

Tip

Because the prompt arrives as a draft, it’s a good place for rough notes — you get a final chance to edit before the agent starts spending tokens.

What happens on Create workspace

1. Worktree + branch. Birch creates a fresh, uniquely named worktree on a new branch off the base branch, stored under Birch’s own data folder — your working checkout stays untouched. See the worktree-first model.
2. File carryover. Gitignored local files the repo needs (.env* by default, or whatever your .worktreeinclude lists) are copied in from the source checkout.
3. Agent boot. A terminal opens in the worktree and runs the agent command, including any --model / --effort / --permission-mode flags you chose.
4. Prompt delivery. Your prompt is typed into the agent as an unsubmitted draft.
5. Defaults remembered. The dialog remembers the agent, model, effort, and permission mode you picked and offers them as defaults next time.

Instant creation: the pre-warmed workspace

While the dialog is open, Birch speculatively prepares a workspace in the background. Confirm with the default settings and that pre-warmed worktree is adopted — the terminal appears almost instantly, with carryover files already in place. Change the options and Birch creates a fresh worktree instead; you’ll briefly see the “Preparing workspace…” state while it does.

Custom agent command

Two places matter for non-built-in agents:

• The dialog’s Custom command field runs that command for the workspace — and Birch also saves it as the new default agent command, so it pre-fills the dialog next time and overwrites Settings → AI → Agent command.
• Settings → AI → Agent command (default claude) is the default agent command; leave it empty and workspaces open a plain shell instead. The Custom command… entry in the workspace tab strip’s ”+” menu also requires this to be non-empty.