Storage & data

Everything Birch stores lives in one data folder per user — the database of repos and PRs, the logs, AI artifacts like review reports and cached task images, and the worktrees behind your agent workspaces. Secrets are the exception: tokens live in the OS keychain, never on disk.

Data root

Platform	Path
macOS	~/Library/Application Support/birch
Windows	%APPDATA%\birch

What’s inside

Entry	Contents
state.db (+ state.db-wal, state.db-shm)	The SQLite database (WAL mode): repositories, worktrees, PRs, Inbox items, settings.
logs/	Daily-rolling log files, 14 days retained: birch-<date>.log (app) and birch-cli-<date>.log (CLI).
artifacts/review/<job-id>/report.md	AI code-review reports.
artifacts/comment-fix/<job-id>/suggestion.md	AI fix suggestions for PR comments.
artifacts/inbox/<issue-id>/	Cached task-description images.
repositories/<repo-id>/terminals/<id>/	The git worktrees behind your agent workspaces.
ultracode-settings.json	A small fixed-content settings file Birch writes at startup and passes to Claude Code for workspaces launched at the UltraCode effort.
webview2/	Windows only — browser data for the WebView2 engine behind the embedded terminal.

Secrets

Provider tokens and per-remote HTTPS credentials are stored in the macOS Keychain / Windows Credential Manager, never in the data folder — see Git credentials. Copying or backing up the data folder does not copy your tokens.

Disk usage and safe cleanup

Each workspace is a full worktree checkout, so a busy repository can accumulate several working copies under repositories/ — that’s the cost of the worktree-first model.

Danger

Delete workspaces from Birch (the workspace’s context menu, or birch worktree rm), not by deleting the folder. Deleting the folder by hand leaves git’s worktree metadata and Birch’s database row behind; Birch’s removal cleans up all three, and escalates until the worktree is gone even when it is dirty or locked.

Safe to delete by hand: old files under logs/ and artifacts/ — they are diagnostics and cached output, and Birch recreates the folders as needed.

Bug reports

Attach the newest logs/birch-<date>.log; for a CLI problem, also logs/birch-cli-<date>.log. Skim them for anything you consider private first — they can contain repository paths and branch names. See Troubleshooting.

Backup and reset

Quit Birch first — state.db is live while the app runs. To back up, copy the whole data folder (minus repositories/ if you only want Birch’s state, not the working copies). To reset Birch completely, move state.db, state.db-wal, and state.db-shm out of the data folder; the app starts fresh and your repositories on disk are untouched.

What uninstalling leaves behind

Uninstalling the app removes neither the data folder, nor the workspace worktrees under repositories/, nor the tokens in the OS keychain, nor an installed birch CLI PATH entry (the macOS /usr/local/bin/birch symlink / the Windows user-PATH addition). Remove those by hand if you want a clean slate.