DOCS / AGENT PLUGINS

The birch-status plugin

The birch-status plugin is what makes workspace status live: it hooks your agent’s lifecycle events and relays them to Birch, lighting up the sidebar discs, Inbox rows, and notifications. Without it, Birch can’t tell a working agent from a stuck one. Install it once per agent CLI — from Birch’s Settings or with two plugin commands.

Why you want it

With the plugin installed, every workspace row shows what its agent is doing right now:

Live status discs — a spinner while the agent works, an amber alert when it’s waiting for you, a checkmark when the turn is done. Shown on the sidebar workspace rows, the collapsed rail, and the dashboard’s attention list.
Waiting-for-input notifications — when the agent asks a question or requests a permission, Birch raises a desktop notification and adds an Inbox row with a sound, so you never leave an agent hanging.
Per-tab titles — each agent terminal tab names itself after its own session, even when several agents run in one workspace.

The full mapping of hook events to workspace states is on Live workspace status. For how status monitoring fits into Birch’s AI features overall, see AI in Birch.

The same plugin name, birch-status, exists for both Claude Code and Codex. Install it in each agent CLI you use.

Prerequisite: the birch CLI on your PATH

The plugin’s hooks call the birch CLI. Without it, the plugin installs but reports nothing.

Open Settings → Claude Code (or Settings → Codex) and click Install birch CLI to PATH.
- On macOS this symlinks the bundled CLI to /usr/local/bin/birch (it may ask for administrator rights).
- On Windows it appends the CLI’s folder to your user PATH.
Open a new terminal and verify:

birch --help

If you prefer to do it by hand, put the birch binary shipped next to the Birch app on your PATH yourself.

Install for Claude Code

From Birch: open Settings → Claude Code and click Install plugin. Birch runs your claude CLI for you: it adds the birch plugin marketplace and installs the plugin at user scope, then verifies the install. This requires the claude CLI to be installed.

From inside Claude Code:

/plugin marketplace add https://github.com/aidmsu/birch-code
/plugin install birch-status@birch

The hooks then apply to every project you open with Claude Code — new sessions pick them up automatically.

Install for Codex

From Birch: open Settings → Codex and click Install plugin.

From the command line:

codex plugin marketplace add https://github.com/aidmsu/birch-code.git
codex plugin add birch-status@birch

Then two extra steps that Codex requires:

Restart your Codex session so the new hooks are loaded.
In the new session, run /hooks, review the birch-status commands, and trust them. Codex deliberately does not run third-party hooks until you explicitly approve them.

The /birch slash command

The Claude Code plugin also adds a /birch command: run it in any Claude Code session — including one you started in a plain terminal — to hand the session off to the Birch desktop app. Birch comes to the foreground, selects the repository the current directory belongs to, and opens an embedded terminal at that directory that resumes this exact conversation with claude --resume. If Birch isn’t running, the command launches it first and waits up to 15 seconds for the app to come up.

Under the hood it runs birch open --session-id "${CLAUDE_SESSION_ID}" --cwd "$(pwd)" — see CLI utility commands.

Updating

A plugin install is a frozen snapshot — it doesn’t follow new releases on its own. Birch watches for this: when the app ships a newer plugin version than the one you have installed, Settings → Claude Code shows an Update button, and Birch offers the update once per shipped version.

To update manually from a terminal:

claude plugin marketplace update birch
claude plugin update birch-status@birch

(The marketplace update comes first — it refreshes the marketplace clone that the plugin update installs from.)

Codex has no update command. To move to a newer plugin version there, remove the plugin and add it again:

codex plugin remove birch-status@birch
codex plugin marketplace add https://github.com/aidmsu/birch-code.git
codex plugin add birch-status@birch

Uninstalling

Claude Code: click Uninstall in Settings → Claude Code, or from inside Claude Code:

/plugin uninstall birch-status@birch

Codex: click Uninstall in Settings → Codex, or:

codex plugin remove birch-status@birch

Uninstalling the plugin does not touch the optional usage statusline — that lives in a separate slot in ~/.claude/settings.json and is enabled and removed independently.