Agent Island
A status companion for Claude Code and Codex.
See what every run is doing. Step away, and Agent Island calls you back when it is your turn. Local-first, no Agent Island account, no product telemetry.
▶ HD version
Quick Start
Choose your platform and install the current v1.7.1 release directly:
| Platform | Recommended download | Requirement |
|---|---|---|
| macOS | AgentIsland-1.7.1.dmg | macOS 13+, Apple silicon or Intel |
| Windows | AgentIsland-1.7.1-win-x64.zip | Windows 10/11 x64 |
On macOS, drag Agent Island into Applications. The app is ad-hoc signed rather than notarized, so the first launch requires right-clicking the app in Finder and choosing Open.
On Windows, unzip the archive and run AgentIsland.exe.
Homebrew, WinGet, and Scoop may lag behind the latest GitHub release. Check the version they offer before installing.
brew install tristan666666/tap/agentisland
winget install TristanTang.AgentIsland
scoop bucket add agent-island https://github.com/tristan666666/scoop-bucket
scoop install agent-island/agentisland
Build the macOS app from source:
git clone https://github.com/tristan666666/agent-island.git
cd agent-island
./scripts/verify.sh
open build/AgentIsland.app
Windows build and test instructions are tracked in issue #10.
Table of Contents
- Features
- Community
- How it works
- Why Agent Island
- Privacy and safety
- FAQ
- Contributing
- Roadmap and releases
- Credits and license
Features
Status monitoring
Agent Island mirrors local Claude Code, Claude Desktop, and Codex session activity in a compact top bar. You can scan the state without bringing each session to the foreground — the two states below sit one hover apart:
| Cue | Meaning |
|---|---|
| Logo rotates | A session is working |
| Logo is still | No session is currently working |
| Logo pulses red | A session needs attention because of a provider, login, network, or rate-limit error |
Usage
Swipe through local usage and cost views for Claude and Codex. Provider usage data comes from provider-owned usage endpoints through the local credential store; cost and model summaries are calculated locally from session records.
Machines with a single subscription get the solo layout automatically — the provider's mark and name hold one half of the panel, the live windows the other:
Weekly & monthly report cards
Shareable cards rendered locally: total tokens with an ≈ API value line, a Claude-vs-Codex faction duel whose clash sits exactly at your usage split (the leading side wins the crown), 7-day bars with a TOP-3 model donut (weekly) or a TOP-5 donut (monthly), and your island rank as the closing line. Copying or sharing a card is an explicit user action; Agent Island does not publish it for you.
It's-your-turn clock
When a background turn finishes, Agent Island can show an alarm window, send a system notification, and play a sound. Multiple completed turns queue instead of replacing one another, and responding clears the corresponding reminder. If you are already looking at the session's terminal or editor, the alarm holds — it fires the moment you switch away with the turn still open.
Personalization
The island is yours to tune. Usage tiles come in five chart styles with a used-or-remaining quota toggle and cycling cost styles. The ambient light runs Vivid — halo and orbit sweep in your pick of teal, cobalt, violet, or silver — or fully-dark Calm, which saves color for real warnings. Screens without a notch get a 100–150% interface scale.
macOS and Windows
Agent Island is a native desktop app on both supported platforms, with English and Simplified Chinese interfaces.
- macOS 13+: SwiftUI universal app for Apple silicon and Intel, with wide and compact top-bar layouts.
- Windows 10/11 x64: native WPF app with a top bar, draggable floating widget, and tray presence.