Utility commands

Four smaller commands round out the CLI: status summarizes everything Birch knows, 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 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.