Installation

Birch ships as self-contained builds for Windows 10/11 (x64) and macOS 11+ (Apple Silicon and Intel) — no separate .NET install is needed. This page walks through the downloads, the first-launch security warnings on each platform, and what happens after install (auto-updates, the optional CLI install). Linux is not supported.

Download

Downloads live on the GitHub Releases page of aidmsu/birch-code-releases. Pick the file for your platform:

Platform	Architecture	File
Windows 10/11	x64	Birch-X.Y.Z-win-x64.zip
macOS 11+	Apple Silicon (M-series)	Birch-X.Y.Z-osx-arm64.dmg
macOS 11+	Intel	Birch-X.Y.Z-osx-x64.dmg

Install and first launch

macOS

1. Open the .dmg and drag Birch.app into your Applications folder.
2. On first launch, Gatekeeper reports that the app “cannot be opened because the developer cannot be verified”. Use either workaround:

   • Right-click: in Finder, right-click Birch.app → Open, then click Open in the dialog.

   • Terminal: remove the quarantine attribute:

     terminal

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

Windows

1. Unzip Birch-X.Y.Z-win-x64.zip into any folder (for example C:\Program Files\Birch).
2. Run Birch.exe.
3. On first launch, SmartScreen shows “Windows protected your PC”. Click More info → Run anyway.

Note

Birch’s embedded terminal requires the WebView2 runtime. It is preinstalled on Windows 11; on Windows 10, install Microsoft’s WebView2 Evergreen runtime if it is missing.

Why the security warnings appear

Current Birch builds are not code-signed on Windows and not signed or notarized on macOS, so SmartScreen and Gatekeeper flag them as coming from an unidentified developer. That is expected for now — signed builds are planned. The workarounds above are one-time: after the first successful launch, the OS remembers your choice.

After install

Automatic updates

Birch checks its own update feed roughly every 6 hours and offers Download & restart when a new version is available. Builds run from the portable Windows zip cannot self-update — download the new zip instead. Details, including the release channel, are in Updates & channels.

Install the birch CLI (optional)

The birch command-line tool ships inside the app. To put it on your PATH, open Settings (⌘, / Ctrl+,) → the Claude Code (or Codex) pane → click Install birch CLI to PATH:

• macOS — creates a symlink at /usr/local/bin/birch; you may be asked for your administrator password.
• Windows — appends the CLI folder to your user PATH.

Open a new terminal afterwards and run birch --help to confirm. See the birch CLI overview. The CLI is also what the birch-status plugin uses to push live agent status into the app.

Uninstalling

• macOS — quit Birch and delete Birch.app from Applications.
• Windows — delete the folder you unzipped.

Uninstalling does not remove Birch’s data folder — the local database, AI artifacts, and any agent-workspace worktrees stay at ~/Library/Application Support/birch/ (macOS) or %APPDATA%\birch\ (Windows). If you installed the birch CLI, also remove the /usr/local/bin/birch symlink (macOS) or the Birch entry from your user PATH (Windows). Everything Birch writes to disk is listed in Storage & data.