Install AI Battery with an AI agent

Updated October 16, 2026 · AI Battery 3.1.0 · macOS 13 (Ventura) or later on Apple Silicon, plus Claude Code and/or the Codex CLI.

This page is a runbook. If someone pasted it into you — Claude Code, Codex, Cursor, or any agent with a shell on their Mac — run the steps in order; each has a check. Stop at step 4 and hand over: two macOS prompts and the provider sign-in happen in the UI and cannot be done from a terminal. Reading this as a person? The same steps work by hand, or use the one-click methods on the homepage.

Step 1: Preflight

AI Battery needs macOS 13 (Ventura) or later on Apple Silicon, plus Claude Code and/or the Codex CLI — there is no Intel build yet. Check both, and whether Homebrew is available:

sw_vers -productVersion   # must be 13.0 or newer
uname -m                  # must print arm64
command -v brew           # a path → use 2A; nothing → use 2B

If the macOS version or the architecture check fails, stop and tell the user why — nothing below will work on that Mac.

Step 2: Install

2A. With Homebrew (preferred)

brew tap KyleNesium/tap && brew install --cask aibattery

The cask pins the release's SHA-256, installs /Applications/AIBattery.app and clears the quarantine flag. Already installed? brew upgrade --cask aibattery.

2B. Without Homebrew

curl -fsSL https://aibattery.dev/install.sh | bash

What install.sh does, in order: checks macOS 13+ and arm64 → downloads AIBattery.zip (3.3 MB) for version 3.1.0 from GitHub Releases → verifies its SHA-256 (c79702b7eae1…) → quits a running copy and unpacks into /Applications → clears the quarantine flag → launches the app. Its last line is machine-readable: AIBATTERY_INSTALL_RESULT status=ok version=3.1.0 path=/Applications/AIBattery.app launched=1.

Flags go after bash -s --: --no-launch installs without opening the app; --dir <folder> installs somewhere other than /Applications. Exit codes: 0 installed · 2 unsupported Mac · 3 checksum mismatch · 4 download or unpack failed. Prefer not to pipe into bash? curl -fsSLO https://aibattery.dev/install.sh && less install.sh && bash install.sh.

Step 3: Verify and launch

ls -d /Applications/AIBattery.app
# expect 3.1.0 or newer:
defaults read /Applications/AIBattery.app/Contents/Info CFBundleShortVersionString
open /Applications/AIBattery.app
sleep 2 && pgrep -x AIBattery >/dev/null && echo "AI Battery is running"

AI Battery lives in the menu bar as a green star — no Dock icon, no window. If pgrep finds nothing after launch, Gatekeeper blocked it; that is step 4, not an install failure.

Step 4: Stop — hand over to the user

Report the version and the method you used, then give the user these three steps as written:

1. If macOS says the app can't be opened (it isn't notarized yet): System Settings → Privacy & Security → scroll down → Open Anyway, then open it again.
2. Click "Always Allow" on the Keychain prompt — that is where the sign-in token is kept. It appears once on first launch and once more after an in-app update.
3. Click the star in the menu bar and sign in. Claude: the browser opens Anthropic's sign-in and shows a code to paste back into the app. Codex: "Sign in with ChatGPT" redirects straight back to the app; importing the Codex CLI login or pasting an OpenAI API key also works. Up to 3 accounts per provider — add more in Settings → Accounts.

Nothing else is needed. AI Battery reads Claude Code's and the Codex CLI's local session logs on its own, and updates itself through Sparkle.

Upgrade, uninstall

# upgrade — Homebrew installs (or use the in-app update):
brew upgrade --cask aibattery
# upgrade — script installs: re-run it, it replaces the app:
curl -fsSL https://aibattery.dev/install.sh | bash

# uninstall — Homebrew installs, including preferences:
brew uninstall --zap --cask aibattery
# uninstall — script installs:
rm -rf /Applications/AIBattery.app
rm -rf "$HOME/Library/Application Support/AIBattery"
rm -f "$HOME/Library/Preferences/com.KyleNesium.AIBattery.plist"

Sign-in tokens live in the macOS Keychain under the service name AIBattery; delete them in Keychain Access for a clean slate.

For agents: machine-readable

• This page as Markdown — or request /install with Accept: text/markdown
• app.json — current version, release assets with byte sizes and SHA-256, every install command
• install.sh — the pinned installer above; checksums-sha256.txt on the release for independent verification
• llms.txt — index of everything else on this site