Agent workspaces

An agent workspace is Birch’s unit of AI work: a worktree plus a branch, an agent session running in an embedded terminal, and the metadata Birch keeps about it. Workspaces survive app restarts, resume their agent sessions, and report live status — working, ready, waiting for you, done — everywhere you look.

This page explains what a workspace is; Create a workspace covers the how-to.

Anatomy of a workspace

Part	What it is
Worktree + branch	A fresh git worktree on a new branch off the base branch you chose, under Birch’s data folder. Gitignored files like .env are carried over per .worktreeinclude.
Agent session	The agent CLI (Claude Code, Codex, …) running in the workspace’s primary terminal tab.
Terminal tabs	The primary agent tab, a Git tab (the worktree’s changes, history, stash, and review — always present, can’t be closed), and any extra tabs you open from the tab strip’s ”+” menu: a plain terminal or another enabled agent.
Metadata	Persisted on the workspace: which agent it belongs to (the harness kind), the exact launch command it was started with (flags included), its base branch, and the source task when it was launched from the Inbox.

Because the agent identity and launch command are persisted, a workspace keeps its meaning across restarts: a Codex workspace stays a Codex workspace even if your default agent setting says claude, and an ad-hoc codex tab opened inside a Claude workspace doesn’t change what the workspace is.

The four harnesses

The create-workspace dialog offers four agent kinds (in advanced contexts Birch calls these harnesses):

Agent	Launch command	Extras
Claude	claude	Model, effort, and permission-mode pickers — passed as --model / --effort / --permission-mode
Codex	codex	—
OpenCode	opencode	—
Custom command	Whatever you type (e.g. aider)	—

The prompt you enter in the dialog is typed into the agent as an editable draft — you can adjust it before pressing Enter.

The status lifecycle

Every workspace reports a live status, shown as a small disc next to the agent’s brand mark in the sidebar (and echoed in the collapsed rail, the dashboard’s attention list, and the Inbox):

Status	Indicator	Meaning
Working	Spinner	The agent is in the middle of a turn.
Ready	Muted dot	The session is up and idle at its prompt — “Ready for your input”. What a freshly reopened workspace shows.
Waiting	Amber bell	The agent asked you something or needs permission. This is the only state that fires a desktop toast, an Inbox entry, a beep, and a dashboard attention row.
Done	Checkmark	The agent finished its turn.

A few rules keep the indicators honest:

• Entering a workspace acknowledges a finished turn. Selecting the workspace clears its Done checkmark and its Inbox entries. A live agent (working or waiting) keeps its indicator until it actually finishes or you answer it.
• The most urgent session wins. A workspace can run several agent tabs; the sidebar shows the highest-ranked status: waiting beats working, working beats done — and a tab merely sitting ready at its prompt never hides another tab’s finished checkmark.
• A dead terminal retires a live status. If the agent crashes or you close its last tab, Birch clears a stranded spinner or amber bell instead of showing it forever. A finished turn keeps its checkmark.

See Monitor status and usage for everywhere status surfaces.

Where the status comes from

Status is push-based, not guessed: the birch-status plugin wires the agent CLI’s hook events (session start, tool use, notifications, turn end) to the birch agent-event command, which relays them to the running app over a local named pipe. Birch then decides what becomes visible — including subtleties like not marking a turn “done” while background subagents are still running.

This means live status depends on the plugin being installed in your agent CLI (plugins exist for both Claude Code and Codex). Without it, workspaces still work — you just don’t get live indicators. See Live workspace status for the pipeline and birch-status for installation.

Restarts and resume

A workspace survives an app restart, and so does its agent session:

• Birch persists the workspace’s agent kind and the exact launch command it was started with — --model, --effort, and other flags included.
• The first time you open a workspace in a given app run, Birch looks up the agent’s most recent session for that folder in the CLI’s own session store and relaunches it as a resume: claude … --resume <id>, codex resume <id>, or opencode --session <id>.
• A Custom or unrecognized agent command is launched exactly as recorded — Birch never guesses a resume flag that could error out and leave you at a bare shell.
• The resume happens only on that first entry. If you quit the agent and reselect the workspace later in the same app run, it starts fresh.
• The prompt from the create dialog is deliberately not replayed — it was a one-shot at creation.

See Resume and restart for the day-two workflow.

Why creating a workspace feels instant

When you open the create-workspace dialog, Birch speculatively pre-warms a workspace in the background: the worktree, the branch, and the carried-over files are already prepared while you read the dialog. Confirm with the default options and Birch simply adopts the pre-warmed workspace — the terminal appears immediately. Change the options and Birch creates the workspace fresh instead.

Workspaces without an agent

A workspace doesn’t have to run an agent at all. If it was created without an agent command (the Agent command setting in Settings → AI left empty means new terminals open as plain shells), Birch records it explicitly as a plain-shell workspace — and it stays a plain shell on every reopen, no matter what your default agent setting says later. You still get the isolated worktree, the Git tab, and the same review workflow; there’s just no agent to report status.

Workspaces are one of the two AI channels in Birch — the one that runs your own agent CLI on your own subscription. See AI in Birch for how that differs from the Anthropic API features.