MioIsland: a macOS notch panel for Claude Code sessions

What MioIsland does for Claude Code users on macOS

Claude Code runs in a terminal, and the moments that need a human are easy to miss: a permission prompt waiting for an answer, a session that has finished, a session that has stalled. MioIsland is a macOS app that moves those moments into the notch area of the screen. The README describes it as a native companion for Claude Code with status monitoring, a session list, permission approval, "4-5 Buddies", a pixel cat and 8-bit sound effects. The companion feature set, labelled Code Light in the README, extends the same state to an iPhone with two-way real-time sync.

The intended user is someone running Claude Code on a Mac, in one of the terminals the project lists: cmux, iTerm2, Ghostty, Terminal.app, Warp, Kitty, WezTerm, VS Code, Cursor and Zed. That list matters more than the feature list. If your terminal is not on it, the value proposition weakens considerably, because the app's job is to sit between the agent and the terminal you already use rather than to replace it.

Architecture: hook events, a Unix socket and cmux send

The README's architecture diagram lays out the data flow in one line: hook events go to a Unix socket at /tmp/codeisland.sock, which feeds cmux send, remote launch, a dash output diff and iPhone sync. Permission allow/deny decisions, buddy data, code sharing and the pair-and-redeem flow all hang off the same path.

That design has a clear consequence. MioIsland is not reading your terminal's output by scraping the screen; it is receiving structured events that Claude Code emits through hooks. Everything the app displays is only as complete as the hook events it receives, and the socket path is fixed rather than configurable, at least as far as the README shows. The iPhone side receives a synced view of the same state, which is why the README can promise a reply preview and remote start on the phone: the phone is not talking to the terminal, it is talking to the Mac app.

The architecture also explains the Accessibility permission the setup flow asks for. Sending input back into a terminal window is not something a normal app can do without it.

Installing MioIsland and approving your first permission prompt

The README gives two installation routes. The Homebrew tap is the shorter one:

brew install xmqywx/codeisland/codeisland

The alternative is a zip from the Releases page. The README states the build requires macOS 15 or later and ships as a Universal Binary. If macOS refuses to open the app after a zip install, the README's setup notes point to the Gatekeeper "Open Anyway" path in System Settings rather than asking you to disable Gatekeeper.

After the app is running, the setup flow covers hooks, Accessibility permission, pairing an iPhone and launch presets. The hooks step is what wires Claude Code into /tmp/codeisland.sock. Once hooks are registered, start a Claude Code session in one of the supported terminals and trigger something that needs approval. The prompt should appear in the notch, where you can allow or deny it, and the same decision is reflected in the terminal session.

If nothing appears, the first thing to check is the hooks step, not the notch. The app cannot display events it never receives.

Where MioIsland stops being the right tool

The licence is the hardest constraint. The README states the project is free and open source for personal use and prohibits commercial use, with CC BY-NC 4.0 named as the licence. The repository's licence field is reported as NOASSERTION, which means GitHub could not map the file to a standard identifier, so the README text is the clearest statement available. If you are evaluating this for a company machine, that is a conversation to have before installation, not after.

Platform is the second constraint. This is a macOS app built in Swift and SwiftUI, and the notch is a hardware feature. There is no Linux or Windows path described anywhere in the README.

The third constraint is the terminal list. Ten-plus terminals are supported, which is broad, but the mechanism depends on being able to send input into the terminal window. A terminal outside that list is not merely unsupported in the cosmetic sense; the approval flow may not be able to act on your decision.

Finally, the project is young and moving. The three most recent releases on the repository are v3.1.1, v3.1.2 and v3.1.3, all dated within about a month of each other in July and August 2026, and the release titles include fixes such as a phone echo repair and a silent-failure fix. Frequent point releases with fix-oriented titles are normal for a project at this stage, but they also mean you should expect to update rather than install once.

How MioIsland differs from a plain menu-bar monitor

The obvious comparison is to a menu-bar utility that watches agent sessions and shows a status icon. Those exist, and they are lighter: no Accessibility permission, no hooks written into your Claude Code configuration, no socket. The difference in approach is that a monitor observes, while MioIsland intervenes. It carries an allow/deny decision back into the session and, per the README, can start a session remotely and sync state to an iPhone.

That is a real capability difference, and it comes with a real cost in trust. Once an app can approve tool calls on your behalf, the question of what it can and cannot approve matters. The README documents the allow/deny flow and the socket it travels over; it does not, in the documentation available, describe a policy layer that restricts which commands may be auto-approved. Treat the notch as a faster approval surface, not as a safety boundary.

The README also notes the project is forked from Claude Island. If you have used that project, the lineage explains the shape of the app, and the MioIsland additions are the iPhone sync, the terminal coverage and the buddy and sound layer.

Licence, updates and the cost of keeping it working

The README names CC BY-NC 4.0 and states personal use is free while commercial use is prohibited. That is a non-commercial licence applied to a developer tool, which is an unusual combination and one worth reading carefully rather than skimming. Nothing here is legal advice; if your use is ambiguous, the README lists a contact address for questions.

The upgrade cost is the hooks. MioIsland works by registering Claude Code hooks that emit events to a socket. When Claude Code changes its hook interface, or when MioIsland changes what it expects, the integration is what breaks, and the failure mode is silence rather than an error dialog. One of the recent release titles refers to a "silent failure" fix, which tells you the maintainers have already met this class of bug. Budget for checking the notch after an upgrade of either side, and keep the hooks step of the setup flow somewhere you can find it again.

Editorial conclusion

Adopt MioIsland if you run Claude Code in a supported terminal on macOS 15 or later and want permission prompts and session state to appear in the notch instead of being hunted down in a terminal window. Do not adopt it if you need a commercially licensable dependency, since the README states personal use is free and commercial use is prohibited under CC BY-NC 4.0, or if you work outside macOS. Before installing, check that your terminal is on the supported list, decide whether you are willing to grant Accessibility permission, and confirm the hooks it installs are acceptable to you.

Frequently asked questions

Official sources

1. Issues
2. MioMioOS/MioIsland on GitHub
3. Project website
4. README
5. Releases