README
¶
aimonitor
Multi-account Claude Code session monitor and account switcher for macOS & Linux.
Status: v1.0.0-beta (in development). Repository: https://github.com/japananh/aimonitor
aimonitor solves one problem: when several teammates share Anthropic Claude Team seats, one heavy user can drain a session quota and block everyone else. aimonitor lets you (1) see live session usage in your macOS menu bar, (2) keep multiple Claude OAuth credentials stashed in your OS keyring, and (3) switch — manually or automatically — to whichever account still has server-side headroom.
It is local-first. It has no telemetry. It never phones home.
Why "server-side headroom"?
Claude Code's local JSONL transcripts only record tokens used on this machine. The Anthropic rate-limit counter is per-account, across all devices. If a teammate burned Account A on their laptop this morning, your Mac sees "Account A: 0% used" and would happily switch you onto an exhausted account.
aimonitor defeats this by reading the anthropic-ratelimit-tokens-remaining HTTP response header before any auto-switch. The local estimate is a fast first-pass filter; the server-side probe is the gate.
Features (v1.0.0-beta)
- macOS Sonoma 14+ menu bar widget (native Swift/SwiftUI) showing live session-bar.
- CLI for macOS Sonoma 14+ and Ubuntu 22.04+.
- Multi-account Claude OAuth credential management via macOS Keychain / libsecret.
- Manual
aimonitor switch <label>between accounts. - Opt-in auto-switch (default off) with configurable thresholds, gated by a server-side rate-limit probe.
- Single-binary Go daemon, communicating with the widget over a Unix socket.
Roadmap
Directional, not committed. See ROADMAP.md for gating conditions and rationale.
- v1.1: daily usage chart, cost estimation per account, notarized macOS app.
- v1.2.x: weekly cap view (gated on a server-side data source available to non-admin users).
- v2.0: Ubuntu GTK menu bar widget, second
Providerimplementation (Codex or Copilot CLI).
Installation
macOS (Sonoma 14+)
brew install japananh/tap/aimonitor
First launch: the .app is unsigned in v1.0.0-beta. macOS Gatekeeper will refuse to open it on the first try. Workaround:
xattr -dr com.apple.quarantine /Applications/AIMonitor.app
open /Applications/AIMonitor.app
Or right-click the app in Finder → Open → confirm the Gatekeeper prompt. You only need to do this once. See docs/unsigned-app.md for the full explanation.
Ubuntu 22.04+
curl -fsSL https://aimonitor.dev/install.sh | sh
The script installs aimonitor to /usr/local/bin, registers a systemd --user unit, and verifies that libsecret is present. The menu bar widget on Linux is coming in v2.0.
Quick start
# First run adopts your existing Claude Code credentials.
aimonitor
# Add a second account (opens Claude Code's OAuth flow, then stashes the result).
aimonitor add
# See what aimonitor knows about.
aimonitor list
# Switch the active credential for the next `claude` invocation.
aimonitor switch work
# Check the true server-side remaining quota for an account.
aimonitor probe personal
# Enable auto-switch (default off).
aimonitor config set autoswitch true
aimonitor config set thresholds 40,60,100
# Audit log of every switch.
aimonitor log
# Quick health check.
aimonitor doctor
Privacy
- No telemetry. No phone-home. Anywhere.
- OAuth tokens live only in the OS keyring (Keychain on macOS, libsecret on Linux). SQLite holds references, never secrets.
- Token bytes are never logged, even at
--debuglevel. Log scrubbing matchessk-ant-(oat|ort)…. - Probe requests (~10 tokens each) are the only network traffic aimonitor initiates; response bodies are discarded after the rate-limit headers are read.
Building from source
Requires Go 1.25+ (transitively required by modernc.org/sqlite). On macOS, also requires Xcode 15+ for the menu bar widget.
git clone https://github.com/japananh/aimonitor
cd aimonitor
make build # builds the Go binary
make test # runs unit tests
make widget # builds AIMonitor.app via xcodebuild (macOS only)
License
MIT. See LICENSE.
See also
USER_STORIES.md— what v1 shipsdocs/architecture.md— daemon, IPC, storagedocs/thresholds.md— exactly how the tripwire-and-probe logic decidesdocs/security.md— keyring boundaries, scrubbing rules, threat model
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
aimonitor
command
Command aimonitor is the CLI entry point.
|
Command aimonitor is the CLI entry point. |
|
internal
|
|
|
cli
Package cli implements the aimonitor CLI subcommands.
|
Package cli implements the aimonitor CLI subcommands. |
|
config
Package config holds aimonitor's user-facing configuration: thresholds for the auto-switch tripwires, autoswitch on/off, cool-down, etc.
|
Package config holds aimonitor's user-facing configuration: thresholds for the auto-switch tripwires, autoswitch on/off, cool-down, etc. |
|
daemon
Package daemon hosts aimonitor's long-running background components: the Unix-socket JSON-RPC server, the JSONL filesystem watcher, the auto-switch engine.
|
Package daemon hosts aimonitor's long-running background components: the Unix-socket JSON-RPC server, the JSONL filesystem watcher, the auto-switch engine. |
|
install
Package install wires platform-specific autostart helpers.
|
Package install wires platform-specific autostart helpers. |
|
provider
Package provider defines the abstraction every AI-provider integration must implement.
|
Package provider defines the abstraction every AI-provider integration must implement. |
|
provider/claude
Package claude implements the Provider interface for Anthropic's Claude Code OAuth ecosystem.
|
Package claude implements the Provider interface for Anthropic's Claude Code OAuth ecosystem. |
|
secret
Package secret bridges aimonitor to the OS-native secret store: macOS Keychain on darwin, libsecret (Secret Service DBus) on linux.
|
Package secret bridges aimonitor to the OS-native secret store: macOS Keychain on darwin, libsecret (Secret Service DBus) on linux. |
|
store
Package store wraps the SQLite database that aimonitor uses for everything that is NOT a secret: account references, per-file JSONL resume offsets, usage samples, audit log, settings.
|
Package store wraps the SQLite database that aimonitor uses for everything that is NOT a secret: account references, per-file JSONL resume offsets, usage samples, audit log, settings. |
|
version
Package version holds the build-time version string for aimonitor.
|
Package version holds the build-time version string for aimonitor. |