Utility commands

Five smaller commands round out the CLI: status summarizes everything Birch knows, report prepares a problem report, open hands your current agent session to the app, and agent-event / statusline are the plumbing the birch-status plugin calls — documented here so you know what they are, not because you’d run them by hand.

birch status

terminal

birch status [--json]

Always runs locally. Text output is a summary block followed by one section per repository:

text

repositories:    2
worktrees:       5
open PRs (me):   1
pending reviews: 0

<repo>  (<status>)  worktrees=<n>  default=<branch>
  <branch>  +<ahead>/-<behind>  <path>

Per repository it lists up to five most-recently-active worktrees with their ahead/behind counts (? when git can’t answer). --json returns:

json

{
  "repositories": 2,
  "worktrees": 5,
  "openPullRequestsForMe": 1,
  "pendingReviews": 0,
  "items": [
    { "id": "…", "name": "my-repo", "status": "…", "defaultBranch": "main", "worktreeCount": 3 }
  ]
}

birch report

terminal

birch report [--message <text>] [--logs] [--older-logs] [--save <file>] [--send]

Prepares a problem report — the same de-identified report as Report a problem in the app — and lists what it holds. It never opens Birch’s database or needs the app, so it works when Birch won’t start (how to use it then). Nothing leaves your machine unless you pass --send and answer y at the prompt.

Option	Effect
--message <text>	Your description of the problem. Sent exactly as typed — don’t paste passwords, tokens or code.
--logs	Include Birch’s logs from the last 3 days. Without the database they’re cleaned by stricter rules and cut to the newest 2,000 lines per file, so they’re left out unless you ask.
--older-logs	Also include the logs from 4–7 days ago.
--save <file>	Save the report, a zip, to this path. Works offline.
--send	Show the report, ask Send this report to Birch's developer? [y/N], and send it only if you answer y. Needs an interactive terminal: with its input redirected — a script, a hook, a pipe — it sends nothing and exits 2. There is no --yes.

The output lists every item — [x] included, [ ] left out (with the flag that adds it), [!] couldn’t be cleaned safely and never sent — with its size and how many values were replaced, then the folder with the prepared files (Files:) and the report zip. Look in that folder before you add --logs. Crash details and macOS crash reports are included whenever there are any; logs from before this version can only be sent from the app.

A successful send prints Report sent — thank you. Report ID BR-…; mention the ID if you follow up. Exit codes: 0 when the report was prepared, saved or sent, or you answered no; 1 when sending failed (offline, too large, too many reports, or sending turned off — save it with --save instead); 2 for --send without an interactive terminal.

With --json, stdout is one JSON document: reportId, reference, scrubContext (cache when the names Birch removes came from the list the app saved, env when only from your computer), stagingFolder, bundle (path, bytes, sha256), items (id, title, included, state, bytes, stats), excludedByCanary, saved and sent (outcome, reference, retentionDays). Under --json --send the item list and the question go to stderr instead.

What a report contains and where it goes: Privacy.

birch open

terminal

birch open [--cwd <dir>] [--session-id <guid>]

Continues the current Claude Code session in the Birch app. --cwd defaults to the current directory; --session-id must be a GUID (anything else — e.g. an unexpanded variable from an older Claude Code — is silently dropped, and the app falls back to the session it tracked for that directory).

If no app is running, birch open launches it and polls the pipe every 250 ms for up to 15 seconds before retrying. Success prints Continuing this session in Birch.; a launch or hand-off failure prints an explanation and exits 1. --json yields { "ok": …, "message": … }.

This is the engine behind the plugin’s /birch slash command, which runs birch open --session-id "${CLAUDE_SESSION_ID}" --cwd "$(pwd)" — see birch-status plugin.

birch agent-event

terminal

birch agent-event --event <kind> [--agent <kind>]

Plugin plumbing — wired to agent lifecycle hooks, not for interactive use. It reads the hook’s JSON payload on stdin, relays a status event to a running app over the pipe, and always exits 0. --event is required and takes one of seven kinds: started, working, waiting, idle, ended, subagent-started, subagent-stopped. --agent names the reporting agent CLI (e.g. claude or codex). These events drive the live workspace status indicators.

birch statusline

terminal

birch statusline

Plugin plumbing — Claude Code’s statusLine command. It reads Claude Code’s statusline JSON on stdin, prints the compact usage text shown in the terminal (model · context · rate-limit windows, e.g. Opus 4.8 · ctx 71% · 5h 34% · 7d 12%; segments drop when data is absent), and forwards the live usage to a running app. See Usage statusline.

Why the plumbing commands are silent and fail-safe

agent-event and statusline are spawned by the agent constantly — on every tool call and statusline refresh. They therefore cap the pipe call at 500 ms, never touch Birch’s database, always exit 0, and ignore unknown flags (a newer plugin may pass options an older CLI predates). A slow or failing status relay must never stall or break the agent it reports on. For the same reason open is pipe-only too — see IPC vs standalone.