Codex Island keeps local Codex and Claude Code session titles and activity near the top of your screen. See when work needs your attention, then click the island to open the displayed provider’s desktop app.
Independent project. Not affiliated with OpenAI or Anthropic. This is a 0.x preview built around local Codex and Claude Code compatibility.
See the island in action
Four everyday states, on a MacBook with a notch and a standard external display. Full mode keeps the session title above the current activity and uses a distinct outline for each state.
These are native SwiftUI view renders with synthetic content, showing the current Simplified Chinese UI and the asset-free fallback cat symbol. They are illustrative screen compositions, not desktop screenshots or hardware validation. How the previews are made.
| MacBook · Notched display | External · Standard display |
|---|
| WorkingFollow commands and tool activity at a glance. | WorkingFollow commands and tool activity at a glance. |
| Needs your inputA clear signal when an answer is needed. | Needs your inputA clear signal when an answer is needed. |
| Work blockedA distinct error state when a turn fails. | Work blockedA distinct error state when a turn fails. |
| IdleA quiet presence while Codex is open. | IdleA quiet presence while Codex is open. |
Mini mode
A quieter presence: a 44 × 22 pt capsule on standard displays, or a light outline that automatically follows the notch. Choose Mini mode in the menu bar or Settings → Appearance → Display mode. Hover for status and click to open the displayed provider’s desktop app. Titles and pets stay hidden in Mini; Full mode keeps your pet and height preferences. Enable title privacy to also hide titles from hover text and VoiceOver.
| Notched display | Standard display |
|---|
| Working | Working |
| Needs your input | Needs your input |
| Work blocked | Work blocked |
| Idle | Idle |
A little less window switching
- Session and activity together. Follow thinking, commands, file changes, and tool activity in two compact lines.
- A signal when you are needed. Recognized unanswered questions trigger a pulse; errors get a distinct visual state.
- At home on macOS. SwiftUI and AppKit, notch-aware placement, a menu-bar control, and Reduce Motion support.
- Make it yours. Adjust colors, height, visibility, and animation. Middle-click for 30 seconds of click-through.
- Your Codex companions. Select built-in, local custom, or locally cached cloud pets. No personal pet images are bundled. If cloud artwork is missing, view the pet in Codex and resync. Pet sources and limits.
- Local by default. Read-only access to local state, with no app telemetry or network service.
Get started
v0.9.0 adds Claude Code compatibility. Choose Codex, Claude, or automatic rotation in the menu bar or Settings → Connection. Existing preferences are preserved; Codex remains the default.
Preview packages: GitHub Releases. The release workflow publishes a universal DMG and ZIP after its checks pass. Release guide.
Build from source: macOS 14+, Swift 6+, and Xcode or Command Line Tools. Install Codex or a supported Claude Code entry point for live local status. There are no third-party Swift package dependencies.
From the project root:
./Scripts/package_app.sh
open build/CodexIsland.app
The app appears in your menu bar. The island follows the selected provider’s connection state; recognized idle sessions stay visible. Show or hide it manually from the menu bar.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
