DOCS / WORKSPACES
Resume & restart
Closing Birch doesn’t end your workspaces. The worktree, branch, agent kind, and launch command are all persisted; the agent’s own session is rediscovered from its CLI’s store and resumed the first time you re-enter the workspace in a new app run. This page explains exactly what persists, what resumes, and what starts fresh. See AI in Birch for how sessions fit the bigger picture.
What persists — and what doesn’t
Section titled “What persists — and what doesn’t”| Persisted? | Notes | |
|---|---|---|
| Worktree + branch | Yes | On disk; worktrees are kept even after the shell exits |
| Agent kind | Yes | Which agent the workspace belongs to |
| Exact launch command | Yes | Including --model / --effort / --settings flags |
| Creation prompt | No | One-shot at creation, by design |
| Session id | No | Rediscovered live from the agent CLI’s own session store |
How resume works
Section titled “How resume works”The first time you open a workspace in a given app run, Birch locates the newest session the agent CLI itself recorded for that worktree and relaunches the recorded command with the right resume argument:
| Agent | Session store consulted | Resume command |
|---|---|---|
| Claude | ~/.claude/projects/ transcripts | claude … --resume <id> |
| Codex | ~/.codex/sessions/ rollouts | codex resume <id> |
| OpenCode | OpenCode’s project/session storage | opencode --session <id> |
| Custom | The store of the CLI named by the command’s first word, if that is claude, codex, or opencode | The matching resume argument — otherwise relaunched unchanged |
A Custom command isn’t opaque to resume: Birch looks at its first word, and a custom
command that runs claude, codex, or opencode gets that CLI’s matching resume
argument. Only genuinely unrecognized commands are relaunched exactly as recorded —
Birch never guesses a resume flag that could error out and leave you with a bare
shell. Workspaces created before Birch recorded agent kinds have every locator
probed, with the newest session winning, so they resume too.
The first-entry rule
Section titled “The first-entry rule”A resume happens once per app run, on the workspace’s first launch. If you quit the agent and re-select the workspace later in the same run, it starts fresh — the same behavior as before restarts were survivable. To continue a past session at any other time, use the Resume button on the properties panel’s AGENT SESSION card (“Continue this session in the workspace terminal”).
When there’s nothing to resume
Section titled “When there’s nothing to resume”If no session is found — a brand-new worktree, a cleaned agent store — the recorded command simply runs without a resume argument: a fresh agent in the same worktree, with all the workspace’s files and commits intact.
Picking up a CLI session in Birch
Section titled “Picking up a CLI session in Birch”Started an agent in a plain terminal? The birch-status plugin
ships a /birch slash command that runs birch open with the current session id and
working directory, handing that exact session over to a Birch workspace.
Quitting while agents run
Section titled “Quitting while agents run”Closing Birch with live agents raises an “Agents are still running” confirmation that counts how many are working and how many are waiting for your input, and warns that closing will stop them and may lose unsaved work. Cancel keeps them running; Close anyway quits.
Cleaning up
Section titled “Cleaning up”Worktrees are never deleted implicitly — exiting the agent keeps the workspace in the sidebar. To remove one:
- Sidebar — right-click the workspace row → Delete workspace… (or its trash button). After a confirmation — which warns if the branch is unmerged or the worktree has uncommitted changes — Birch deletes the worktree and its throwaway branch.
- CLI —
birch worktree rm <name>removes the worktree; branch deletion is opt-in via--delete-branch. See birch worktree.