CodeIsland: a macOS notch panel that watches your coding agents

The problem CodeIsland targets: agent sessions that block on a human

CLI coding agents spend a lot of wall-clock time waiting. A session asks for permission to run a command, or asks a clarifying question, and then it stops until someone answers. If that terminal window is behind three others, the agent is idle and you are the bottleneck. CodeIsland's answer is to move that waiting state into the MacBook notch, which is the one strip of screen that stays visible regardless of which window has focus. The README frames it plainly: no more switching windows to check whether Claude is waiting for approval or whether Codex finished a task. The intended user is someone running agent CLIs locally on a Mac, often more than one at a time, who wants to approve or deny without leaving the app they are in. It is not a cloud dashboard and not a team tool. It is a single-machine status surface, and the companion apps extend that surface to a phone and a watch rather than to other people.

Unix socket IPC plus auto-installed hooks: the actual data path

The mechanism described in the README is Unix socket IPC. Supported tools send events to the app over a local socket, and the app renders them in a panel that expands from the notch and collapses when idle. The events are not generic log lines. The supported-tools table lists per-tool event counts, from 3 for Codex and 5 for Cline up to 14 for Grok CLI, with OpenCode listed as All. That number is the honest measure of integration depth: a tool with 3 events will show less state than one with 13, and the README labels those rows Basic versus Full. Getting events out of the tools is handled by an auto hook installer that configures hooks for every detected CLI tool, with auto-repair and version tracking. That design keeps the integration inside each tool's own extension point instead of scraping terminal output. The cost is that CodeIsland's fidelity is bounded by each tool's hook surface, and the README itself marks some tools Basic. The jump feature depends on a second layer: tab-level terminal detection and Herdr pane detection, so clicking a session lands on the exact terminal tab or pane rather than just raising the terminal app. The same detection drives smart suppress, which only silences notifications when you are already looking at that specific session.

Installing it and what the first launch writes

Homebrew is the documented path: brew tap wxtsky/tap followed by brew install --cask codeisland. The manual route is to download CodeIsland.dmg from the releases page, drag CodeIsland.app to Applications, and launch it. The README states that on launch the app automatically installs hooks for all detected AI tools, so the first run is also a configuration run. macOS may show a security warning, and the documented fix is System Settings, Privacy & Security, Open Anyway. Building from source requires macOS 14 or newer and Swift 5.9 or newer. The companion setup is separate and has its own keys: on the Mac, Settings, Buddy, iPhone Buddy, then turn on Allow iPhone Buddy to discover this Mac, pair over the same Wi-Fi, and grant both Local Network and Bluetooth permission when macOS asks. Local Network carries full session snapshots while the iPhone app is in front; Bluetooth carries compact summaries that refresh the Live Activity and the Watch once the app is backgrounded. A Sync interval control in the same section sets how often those go out. The ESP32 hardware Buddy has its own switch in the hardware Buddy section of Settings, Buddy, and its flashing and pairing steps live in hardware/README.md, which the README notes is written in Chinese.

The notch dependency and the per-tool integration tax

The most concrete limitation is in the name. The UI expands from the MacBook notch. The README claims multi-display support with auto-detection of notch displays, but the core interaction assumes a notch exists. On a Mac mini, a Mac Studio, an older MacBook, or a clamshell setup driving external monitors, there is no notch to expand from, and the README does not describe a fallback surface on macOS itself. That is a hard boundary, not a preference. The second limitation is integration breadth. The README's own table rates Codex as Basic with 3 events and Cline as Full with 5, while Claude Code has 13 and Grok CLI has 14. Two different tools can both be labelled Full and still expose very different amounts of state. The auto hook installer also edits configuration for every detected tool, which means upgrading an agent CLI can invalidate a hook, and the README's answer to that is auto-repair plus version tracking rather than a guarantee. There is no documented headless mode, no Linux or Windows build, and no described way to consume the socket from your own scripts, so the events are effectively locked to this UI.

How it differs from a terminal multiplexer or a generic notifier

The obvious alternative is tmux plus a notification tool: run agents in panes, let tmux tell you a pane produced output, and click the notification to focus the window. That approach is tool-agnostic and survives any agent CLI change, because it watches the terminal rather than the tool. CodeIsland goes the other way. It installs hooks inside each agent so it receives structured events, which is why it can render a permission request with approve and deny actions and answer an agent's question from the panel. A tmux notification can tell you a pane is waiting; it cannot tell you what is being asked or let you answer it in place. The trade is coverage for depth. tmux works with anything that prints to a terminal and needs no per-tool support; CodeIsland works with the tools in its table and needs a hook for each. The smart suppress feature is a good illustration of the difference: because CodeIsland knows which session is which at the tab and Herdr pane level, it can stay quiet when you are already looking at that session, which a window-level notifier generally cannot distinguish. Choosing between them is really choosing whether you want structured agent state or universal terminal coverage.

Companion apps, licence and what upgrades cost you

The iPhone and Apple Watch companion is a separate App Store download, Code Island Buddy, and the README states it is completely free and open source, with source in this repository under ios/CodeIslandCompanion and apple-companion. It requires no account and no external server, which follows from the design: the Mac publishes session snapshots over the local network while the phone app is open, and sends Bluetooth summaries for background refreshes. The Mac project itself is MIT licensed, which permits commercial use and modification; that is a statement about the licence text, not legal advice, and the App Store distribution of the companion is a separate matter from the Mac app's licence. Maintenance cost is dominated by hook drift. The app auto-repairs hooks and tracks versions, but every agent CLI update is a chance for an event to stop arriving, and the release cadence in the repository (v1.0.31 in July 2026, v1.0.32 in August, v1.0.33 in September) suggests active upkeep rather than a frozen tool. Budget for the occasional session where a tool shows no status and the fix is to re-run the hook install, and check the supported-tools table after upgrading any agent CLI to see whether its event count changed.

Editorial conclusion

Adopt CodeIsland if you run one or more of the CLI agents it hooks on a notched MacBook running macOS 14 or newer and you lose time switching windows to answer permission prompts. Skip it if you work on a non-notched Mac or external display only, or if you want a single vendor-neutral protocol rather than per-tool hook installation. Before relying on it, check the supported-tools table for the event count attached to your specific tool, and confirm in Settings which hooks the auto-installer actually wrote.

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. wxtsky/CodeIsland on GitHub