Troubleshooting

Start from the symptom, not the subsystem. Each entry gives the most likely cause, the fix, and the page that explains the machinery.

The install is blocked by SmartScreen or Gatekeeper

Symptom: Windows shows “Windows protected your PC”; macOS says the app “cannot be opened because the developer cannot be verified”.

Likely cause: Birch builds are currently unsigned and not notarized, so both operating systems flag the first launch. This is expected; code signing is planned.

Fix:

• Windows: in the SmartScreen dialog, click More info → Run anyway.

• macOS: in Finder, right-click Birch.app → Open → Open. Or remove the quarantine attribute in a terminal:

  terminal

  xattr -dr com.apple.quarantine /Applications/Birch.app

Full install steps, including system requirements: Installation.

The agent status disc never updates

Symptom: a workspace’s status indicator never shows working / waiting / done while the agent is clearly busy, and agent activity never reaches the Inbox.

Likely cause: status is push-based — Claude Code hook events reach Birch through the birch-status plugin, which runs the birch CLI. The chain breaks when:

1. the birch-status plugin isn’t installed in Claude Code, or
2. the birch CLI isn’t on your PATH, so the plugin’s hooks have nothing to run, or
3. a different (older) birch binary shadows the bundled one — Settings → Claude Code reports this as “A different birch is first on your PATH”.

Fix: open Settings (⌘, / Ctrl+,) → Claude Code and use Install plugin and Install birch CLI to PATH. Then open a new terminal and confirm birch --help works. You can also install the plugin from inside Claude Code:

text

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

If the plugin is installed but outdated, use the pane’s Update button — plugin installs are frozen snapshots and don’t update themselves.

How the pipeline works end to end: The birch-status plugin.

✨ buttons are missing or error out

Symptom: the ✨ button next to the commit message is not there, or an AI action fails with “AI provider is not configured. Set ANTHROPIC_API_KEY.”

Likely cause: the Anthropic API features — commit-message generation, AI code review, conflict suggestions, comment-fix suggestions — read the ANTHROPIC_API_KEY environment variable; there is no key field in Settings. A GUI app launched from the Dock or Start menu does not inherit exports from your shell profile, so a key that works in your terminal can be invisible to Birch.

Fix: make the variable visible to GUI apps and restart Birch — platform-specific steps are in Anthropic API key.

Note

The ✨ button beside the PR Title is different: it runs your own agent CLI (claude or codex) and does not need the API key. If that one fails, the agent CLI itself is missing or not found on your PATH.

A new workspace is missing my .env

Symptom: a freshly created workspace doesn’t contain the .env (or similar local config) that exists in your main checkout.

Likely cause: Birch carries over files that are git-ignored and match a carryover pattern (the built-in default is .env*). Two common ways this breaks:

• the file is not git-ignored — tracked files are checked out by git anyway, but an untracked-and-not-ignored file is deliberately never copied;
• a .worktreeinclude file at the repository root replaces the default patterns wholesale — an empty or unreadable file means nothing is carried.

Fix: git-ignore the file, and either rely on the default .env* or list it in .worktreeinclude. Carryover runs only when the worktree is created, so re-create the workspace (or copy the file by hand) after fixing the patterns. Details: .worktreeinclude.

Provider sync or auth failures

Symptom: PRs or tasks stop updating for one account, or connecting an account fails.

Likely cause: an expired or revoked token, an under-scoped token (GitLab needs api, read_user), or a wrong self-hosted base URL (Jira / Azure DevOps / YouTrack / GitHub Enterprise).

Fix: open Settings → Integrations and check the account card — it shows the last Verified timestamp. Try Sync now; if that fails, Remove the account and reconnect with a fresh token. Verify & connect validates the credential before anything is saved, so a failed connect never clobbers a working account. Per-provider token scopes and URL formats: Integrations overview and the individual provider pages.

The CLI can’t reach the app

Symptom: a birch command doesn’t affect the running app, or birch open fails.

Likely cause: the CLI talks to a running Birch app over a named pipe. If no app is listening, behavior depends on the command:

• worktree new, worktree rm, pr checkout, review run — try the pipe first, then fall back to executing locally; the result appears in the app the next time it runs.
• open — launches Birch if it isn’t running and waits up to 15 seconds for the pipe; exit code 1 means the launch failed or the app didn’t accept.
• worktree ls, pr create, pr merge, pr list, status — always run locally and never need the app.

Fix: run the command with --verbose — it prints the routing decision to stderr (GUI detected — relayed via IPC or GUI not running — executing locally), which tells you immediately whether the pipe was reachable. Command reference: CLI overview.

The app launches but no window appears

Symptom: the Birch process starts but no window ever shows, and the log ends without an error.

Likely cause: a rare startup condition — most often a stale database migration lock left behind when a previous Birch process was killed mid-startup.

Fix:

1. Quit Birch completely (⌘Q / close it from the taskbar) and make sure no Birch process is still running.
2. Relaunch. Birch detects and reclaims a stale migration lock at startup, so a clean relaunch normally recovers on its own.
3. If the window still doesn’t appear, collect the log files (below) and report a bug — don’t attempt to edit the database by hand.

Logs, and what to include in a report

Birch writes daily rolling log files named birch-<date>.log to the logs folder inside its data directory; the most recent 14 days are kept:

Platform	Log folder
macOS	~/Library/Application Support/birch/logs/
Windows	%APPDATA%\birch\logs\

When reporting a problem, include:

• the log file covering the session where the problem happened,
• your OS and Birch version,
• what you were doing when it occurred (and the exact command line, for CLI issues).

The full layout of the data directory is documented in Storage & data; where to file reports is on the For contributors page.