MioIsland provides macOS Dynamic Island-like notifications and control for AI coding agents, specifically Claude Code sessions. Targeting developers who utilize AI assistants on macOS, it enhances productivity by offering real-time monitoring and interaction capabilities directly from an iPhone companion app, minimizing context switching.

How It Works

MioIsland integrates with Claude Code via hooks installed in ~/.claude/settings.json, communicating session state through a Python script and Unix socket. A key component is the "Code Light Sync module," which bridges the Mac application with an iPhone companion app (Code Light) via a self-hostable, zero-knowledge relay server. It employs sophisticated terminal routing using process information and environment variables to direct messages to the precise Claude session. The system also supports sending slash commands from the iPhone, capturing their output, launching remote sessions, and handling image attachments through system integrations.

Quick Start & Requirements

• Primary Install: Recommended installation via Homebrew (brew install --cask xmqywx/codeisland/codeisland). Manual installation involves downloading a .zip file and requires bypassing macOS Gatekeeper.
• Prerequisites: macOS 15+ (Sequoia) is required. A MacBook with a notch is ideal, though floating mode is available on external displays. An HTTP proxy can be configured for network-restricted environments.
• Links: Releases: https://github.com/MioMioOS/MioIsland/releases, Code Light App Store: https://apps.apple.com/us/app/code-light/id6761744871.

Highlighted Details

• Dynamic Island Integration: Provides live session status, AI buddy animations, and notifications on the iPhone's Dynamic Island.
• Claude Code Buddy Support: Full integration with Claude Code's /buddy companion system, displaying detailed stats and ASCII art.
• Permission Approval: Allows users to approve or deny Claude Code permission requests directly from the iPhone, with code diff previews.
• Plugin Marketplace: Extensible via a marketplace for themes, sounds, and utility plugins.
• cmux Recommendation: Optimized for use with the cmux terminal multiplexer for precise control and interaction.

Maintenance & Community

This project is described as a "passion project" with contributions welcomed. The primary community hub is the GitHub repository. No specific details on maintainers, sponsorships, or dedicated community channels like Discord/Slack are provided.

Licensing & Compatibility

The project is licensed under CC BY-NC 4.0 (Creative Commons Attribution-NonCommercial 4.0 International). This license permits personal use but explicitly prohibits commercial use.

Limitations & Caveats

The companion iPhone app, Code Light, is currently unavailable in mainland China due to ICP filing requirements. Manual installation of MioIsland requires bypassing macOS Gatekeeper as the application is unsigned. Commercial use of the software is prohibited by its license. The application requires macOS 15 or newer.