Frequently asked questions
A free, open-source menu-bar status companion for AI coding agents — Claude Code, Codex, Antigravity, Grok, and Cursor. It shows live session state, calls you when it is your turn, and keeps quota and cost in view, all computed locally on your machine.
macOS 13 or newer (Apple silicon and Intel, one universal build) and Windows 10/11 via a native WPF port. macOS is on v2.1.2; the Windows build syncs shortly.
Run brew install tristan666666/tap/agentisland, or download the DMG from the GitHub releases page and drag it to Applications. Step by step: install and update guide.
Download the zip from GitHub releases and run AgentIsland.exe, or install via winget or scoop.
Yes. MIT-licensed open source, no account, no paid tier, no trial clock.
The build is ad-hoc signed (no paid Apple developer certificate), so the first launch needs one right-click then Open. Updates verify their own EdDSA signature independently. Step by step: install and update guide.
The app checks GitHub releases and updates in place via Sparkle with signature verification. Homebrew users can also brew upgrade.
Quit from the settings sidebar and delete the app — or brew uninstall --cask agentisland. No background services remain.
No. Agent Island is a native macOS app (SwiftUI, macOS 13+) and a native Windows app (WPF, Windows 10/11). There is no Linux build and no Electron fallback — the trade for native feel is that each platform is written separately.
No. It lives in the menu bar on macOS and the system tray on Windows, with no Dock icon and no app window in the switcher. The island expands in place when you need detail and gets out of the way when you do not.
In the guides. Each one is a short manual with prerequisites, numbered steps, what you should see after each step, and a troubleshooting section — start with getting a Claude Code your-turn alert.
Five: Claude Code, Codex, Antigravity, Grok, and Cursor. Live session state (working / stalled / your turn) covers Claude Code, Codex, Grok, and Antigravity; Cursor contributes billing-cycle usage and plan.
Yes. Since 2.1.2 Cursor is a full citizen: live session state and your-turn alarms fire on its own completion signal, on top of billing-cycle usage and plan. instead of pretending.
Yes. Sessions started in Claude Desktop and in a terminal are both tracked, each with its own title and project.
The Antigravity CLI (agy) installed and signed in with Google. Quota is read from its local language server rather than a cloud endpoint, and API-key or Vertex setups stay unsupported rather than showing invented numbers.
An existing grok CLI login on the machine. Quota, reset countdowns, monthly spend, and live session state all ride that login.
Pick any two of the five agents for the menu-bar island. Every selected agent keeps a full data row in the expanded panel regardless of slots.
It reads the session records each agent already writes locally and looks for explicit end-of-turn markers — Claude's stop reason, Codex's task-complete event, Grok's turn-completed event. No wrapper, no traffic interception. Step by step: your-turn alert guide.
By design. While the session's app is frontmost the alarm holds; it fires the moment you switch away with the turn still open. An optional chime can sound even while frontmost.
Alerts queue instead of replacing one another. Responding to a session clears its reminder.
No, never. Machine-spawned child threads are filtered out entirely; only turns a human is waiting on can alert.
A session that was recently working but has stopped producing output mid-turn — usually worth a look.
The architecture is built for it — new providers plug into the same scanner and panel. Requests are tracked on GitHub issues.
Because Google retired Gemini Code Assist for individual accounts on 2026-06-18 and pointed those users at Antigravity; only Standard and Enterprise organisation licences continued. The slot followed the users. If you had selected Gemini before, your selection migrates to Antigravity automatically — nothing to reconfigure.
From each provider's own usage endpoint — the same call their official dashboards make — using the credentials already on your machine.
No. Usage endpoints don't consume model requests. Polling runs at the interval you choose: 5, 15, or 30 minutes.
Providers meter subscriptions with rolling windows. Agent Island shows the used percentage and a reset countdown for each window the provider reports.
Quota percentages come from the provider and match. Token totals and cost are computed locally and labeled as estimates; for Codex the official server-side figure is shown alongside the local ledger.
The island shows the exhaustion state and can alert you. For Codex, an optional auto-switch can rotate to your next parked account.
Yes. Park each login under a name and switch from the provider menu in one click. Opt-in auto-switch rotates when the active quota reads exhausted — off by default.
Total tokens with an estimated API value, a provider duel at your real usage split, daily bars, every model that ran, and your island rank.
Yes. Both cards accept any start date from a calendar picker, back to your earliest scanned data.
They're estimates computed from public per-token pricing and always labeled as such. Your subscription bill is what you actually pay; the estimate shows what the same usage would cost via API.
Provider pages typically count input + output only. Agent Island's default counts every token that crossed the wire, including cache reads — a toggle lets you match the provider's counting style instead.
No. Copying, saving, or sharing a card is always an explicit action you take. Nothing is ever posted for you.
Nothing. No telemetry, no account, no analytics in the app. The only network calls are to the providers' own usage endpoints, made with your own credentials.
They're read from where each CLI already stores them — the macOS keychain or local auth files — used in place, and never uploaded. When Anthropic rotates a refresh token, the rotation is written back exactly where the CLI expects it.
Yes. The entire app is open source under MIT — read the fetchers, build from source, and compare.
Session indexes, preferences, and caches live in standard local app storage on your machine. There is no cloud component.
It reads session files to determine state — whether a turn ended, which project a session belongs to, how many tokens were used. Nothing is transmitted, and conversation content is never uploaded or displayed beyond session titles.
No. Scanning is bounded and incremental; heavy transcript libraries are skipped when cold. Sustained CPU stays in the low single digits.
Session state and alarms work fully offline — they read local files. Quota numbers need network to refresh and show their last-synced age.
Notifications, and nothing else by default. On macOS the app requests alert permission the first time it runs. It does not ask for accessibility, screen recording, or microphone access. If macOS blocks it from reading a session folder, you may need to grant file access — see session not detected.
Run claude /login once in a terminal. The app discovers the freshest keychain entry automatically — no configuration needed.
Run agy in a terminal and complete the Google sign-in. If your account can't access Code Assist, the CLI itself will say so — API-key mode won't light up the row by design. Step by step: session not detected guide.
Check the Synced caption in the panel footer and click it to refresh. If credentials expired, the row switches to a re-auth prompt instead of showing wrong numbers.
As of 2.1.2 Windows ships the same five providers and the same live session state as macOS, released from the same tag. Newer surfaces still land on macOS first and are verified per platform.
Homebrew installs strip the quarantine attribute automatically. For manual DMG installs, re-download from GitHub releases; every update is signature-verified before applying. Step by step: install and update guide.
MIT. Use it, fork it, ship it.
Tristan Tang, as an independent open-source project — with the community's issues and PRs.
Open an issue or PR on GitHub. Reproducible session fixtures and platform testing are especially valuable.
Dashboards are authoritative but live in a browser tab; ccusage is a terminal report. Agent Island is ambient — live sessions plus quota in the menu bar, computed locally. The compare hub has factual side-by-sides.
A star on GitHub and a share with a friend are the two things that keep it going.