DOCS / CONCEPTS
AI in Birch
Birch uses AI through two completely separate channels, and knowing which is which saves you both confusion and money. Anthropic API features call the Anthropic API directly and need the ANTHROPIC_API_KEY environment variable. Your agent CLI features run the claude / codex binary you already have installed, on the subscription you already pay for. Neither is required — Birch is a full Git client without any AI at all.
Which feature uses which channel
Section titled “Which feature uses which channel”| Feature | Channel | What you need | Cost lands on |
|---|---|---|---|
| AI code review — on demand and automatic | Anthropic API | ANTHROPIC_API_KEY | Your Anthropic API usage |
| Per-comment fix suggestions (currently no UI entry point) | Anthropic API | ANTHROPIC_API_KEY | Your Anthropic API usage |
| ✨ Commit message generation | Anthropic API | ANTHROPIC_API_KEY | Your Anthropic API usage |
| Conflict-resolution suggestions | Anthropic API | ANTHROPIC_API_KEY | Your Anthropic API usage |
| Agent workspaces | Your agent CLI | claude, codex, opencode, or a custom agent installed | Your agent subscription (or that CLI’s own key) |
| ✨ PR title generation | Your agent CLI | claude or codex installed | Your agent subscription (or that CLI’s own key) |
Anthropic API features
Section titled “Anthropic API features”These four features send a request straight to the Anthropic API, using a Claude Sonnet model chosen by the app (not configurable):
- AI code review — reviews a pull request’s diff and writes a report. Runs on demand (currently via the
birchCLI) or automatically for new PRs when you enable Settings → AI → Automatically review new PRs (off by default; it never runs on the first sync of a repository). See AI code review. - Comment fix suggestions — turns a reviewer’s PR comment into a concrete fix suggestion.
- ✨ Commit message generation — the ✨ button in the commit area of the Changes tab (“Generate commit message with AI”). See Commit changes.
- Conflict suggestions — the AI suggest button in the conflict resolver, which asks for a merged version of a conflicted file. See Resolve conflicts.
All of them are gated on one thing: the ANTHROPIC_API_KEY environment variable. There is no field in Settings to paste a key — Birch reads it from the environment only. Without it, these features are unavailable and report “AI provider is not configured. Set ANTHROPIC_API_KEY.” Setup: Anthropic API key.
Your agent CLI
Section titled “Your agent CLI”These features never touch the Anthropic API from Birch. Instead, Birch runs the agent CLI you installed yourself, so the cost lands on whatever that CLI is already set up with — typically your Claude or ChatGPT subscription:
- Agent workspaces — the core of it. Birch launches your agent in a real terminal inside an isolated worktree; everything the agent does runs through your own CLI and account. See Agent workspaces.
- ✨ PR title generation — the ✨ button beside the Title field in the Create PR dialog runs your installed
claudeorcodexonce over the branch diff to propose a title. Claude runs in non-interactive print mode, deliberately avoiding the invocation that would force API-key-only authentication — so it bills your subscription, not an API key. See Create a pull request.
Birch finds the CLI even when the app was launched from Finder or the Start menu: it probes the common install locations (~/.local/bin, /usr/local/bin, /opt/homebrew/bin) in addition to your PATH.
The PR-title cost warning
Section titled “The PR-title cost warning”Because PR title generation spends your agent quota, it never runs automatically. The first time you click ✨, Birch shows a confirmation dialog with a cost note; tick Don’t ask again to silence it (stored as the pr.titleGenerateConfirmed setting). Declining — or a generation that produces nothing usable — never clears a title you already typed.
What leaves your machine
Section titled “What leaves your machine”Anthropic API features send the content the feature works on to the Anthropic API: the diff under review, the comment being addressed, the conflicted file, or your pending changes. Reports and suggestions come back and are stored locally under Birch’s data folder (see Storage & data).
Agent CLI features run a local process. What that process transmits is governed by the agent CLI and the account it’s signed into — Birch hands it the work (for PR titles, the diff travels in the prompt) and reads back the result.
Nothing runs silently. Automatic PR review is opt-in and off by default; every other AI action is an explicit click, and PR title generation sits behind its own confirmation. With no API key set and no agent installed, Birch makes no AI requests at all — the only network traffic is ordinary git and provider sync.
Using Birch with no AI
Section titled “Using Birch with no AI”Skip both channels and Birch is still a complete Git client: repositories, commits, history, branches, diffs, pull requests, and the Inbox all work without any AI configured. AI-only controls like the ✨ commit-message button simply don’t appear without a key, and workspaces can run as plain shells with no agent.
Set up one path (or both)
Section titled “Set up one path (or both)”- Anthropic API features: set the environment variable — Anthropic API key.
- Your agent CLI: install Claude Code, Codex, or OpenCode per its vendor’s instructions, then create a workspace. For live status indicators, add the birch-status plugin.