DOCS / WORKSPACES
Monitor status & usage
The right-hand properties panel is the workspace’s dashboard: which task it came from, what you asked the agent to do, where its branch stands and whether it has a PR, and which model the agent is running and how much context and quota it has burned. It has four sections — TASK, PROMPT, GIT, and AGENT — and can be collapsed to a thin rail and back with the toggle at its top right. This page decodes every row, then the agent status shown around the rest of Birch.
Agent status throughout Birch is push-based: it arrives from hooks installed by the birch-status plugin, so install that first — without it the status indicators stay empty. The AGENT section reads several sources, best first: the usage statusline, the hooks, the agent’s own transcript, and finally the launch command — so even before any session data arrives it shows the model and effort the workspace was started with. See also AI in Birch.
Shown when the workspace was started from an Inbox task: the task’s number and title, with a button that opens the task in the browser.
PROMPT
Section titled “PROMPT”The prompt the workspace was created with, exactly as Birch typed it into the agent — the task brief and the attachments block included. The card shows a three-line preview, and its copy button (Copy prompt) copies the full text. The prompt is for reference only: Birch never types it again, not even when it resumes the session.
The section appears only when a prompt was actually delivered: a workspace created without the dialog, or as a plain shell, has none. For a cloud workspace it shows the description sent to claude.ai. Workspaces created before Birch 0.38 didn’t record their prompt, so they show no PROMPT section.
- Open folder ↗ — beside the section heading; opens the worktree folder in Finder / Explorer. Hover it to see the path.
- Branch — the workspace branch, with a copy button.
- Base branch — the branch the workspace was created from, when Birch knows it.
- {N} files changed vs {base} — shown while the branch has changes; opens the Git tab’s Review view.
- Create PR — opens the create-PR flow on the Git tab. It shows only while the branch has work no pull request holds yet: files that differ from the base branch, committed or not. While a live (open or draft) PR exists for the branch, the button gives way to the PR chip. After a PR is merged it stays hidden until something new happens on the branch — a new commit or an uncommitted change; a PR closed without merging brings it back as long as the branch has changes.
- PR chip — the branch’s PR as
#{number} {title} · {state}, with a CI-checks badge once checks report (hover it for details). Click the chip to open the PR in your browser. It is refreshed when you enter the workspace and after a successful push, throttled to about one provider call per branch per 30 seconds — and it is never blanked when offline: a failed or empty refresh leaves the last known state in place rather than pretending the PR vanished.
The AGENT section appears once Birch knows anything about the workspace’s agent — a workspace that never ran one shows none — and each row appears only when it has a value:
| Row | What it shows |
|---|---|
| Profile | The Claude profile the workspace runs as — only once you have more than one profile, and never for a Codex workspace |
| Account | The Claude account signed in to that profile, once Birch knows it |
| Model | The model the session is running; before any session data arrives, the model the launch command declared (the tooltip says which) |
| Effort | The session’s effort level, else the one the launch command declared, else Claude Code’s default, labelled (default) |
| Context | Context-window usage, e.g. 142k of 200k, with a fill bar while the statusline reports the window — amber from 75%, red from 90% |
| Tokens | Input and output token totals for the session, subagents included (Claude Code) |
| Cache | Cache tokens written and read (Claude Code) |
| 5-hour limit | Usage of the 5-hour rate-limit window, and when it resets |
| 7-day limit | Usage of the weekly rate-limit window, and when it resets |
A workspace running more than one agent tab (added from the + menu) gets the Model, Effort, Context, Tokens, and Cache rows once per tab, each group under that tab’s title. The two rate-limit rows belong to the account rather than a session, so they appear once.
The panel has no resume control of its own: Birch resumes a Claude Code, Codex, or OpenCode session by itself the first time you open the workspace in a new app run. See Resume & restart.
A workspace whose agent runs in Claude’s cloud also gets an Open cloud session button pinned to the bottom of the panel, which opens the session on claude.ai.
Agent status
Section titled “Agent status”An agent is always in one of these states:
| Status | Meaning |
|---|---|
| Working… | The agent is actively running a turn |
| Waiting for your input | It asked a question or hit a permission prompt — amber, and mirrored everywhere attention surfaces |
| Ready for your input | The session is up and idle at its prompt — typical right after opening or resuming a workspace, and after you interrupt a turn with Esc or Ctrl+C |
| Done | The turn finished |
| Stopped with an error | The turn ended with an error; the collapsed rail’s tooltip carries the first line of it |
| No active session | No live agent in this workspace |
Where status surfaces
Section titled “Where status surfaces”The properties panel doesn’t repeat the agent’s status — it appears everywhere a workspace is drawn:
- Sidebar rows — the agent’s brand mark plus a small status glyph (spinner = working, amber bell = waiting, dot = ready, check = done, alert = error). The rows have no hover tooltip; screen readers get the agent and status from the row’s accessible name. Entering the workspace acknowledges a finished turn’s indicator.
- Collapsed rail — the top five workspaces with a live session. Its buttons are icon-only, so each keeps a tooltip that names the agent, the status in words (with an error’s first line), the source task, and the worktree path.
- Repository page — the WORKSPACES list spells each workspace’s status out in words.
- Repositories dashboard — waiting workspaces appear in the needs-attention list.
- Inbox — a waiting agent gets its own row (and optional sound and desktop toast; see Notifications).