https://github.com/jarcis-cy/codex-island-app
Dynamic Island-style macOS companion for Codex CLI with local session tracking, SSH remote hosts, approvals, and transcript-aware chat history.
https://github.com/jarcis-cy/codex-island-app
codex codex-cli developer-tools dynamic-island macos notch openai-codex productivity ssh swift swiftui tmux
Last synced: about 2 months ago
JSON representation
Dynamic Island-style macOS companion for Codex CLI with local session tracking, SSH remote hosts, approvals, and transcript-aware chat history.
- Host: GitHub
- URL: https://github.com/jarcis-cy/codex-island-app
- Owner: Jarcis-cy
- License: apache-2.0
- Created: 2026-04-03T04:09:53.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-06T15:49:48.000Z (about 2 months ago)
- Last Synced: 2026-04-06T18:02:34.178Z (about 2 months ago)
- Topics: codex, codex-cli, developer-tools, dynamic-island, macos, notch, openai-codex, productivity, ssh, swift, swiftui, tmux
- Language: Swift
- Homepage: https://github.com/Jarcis-cy/codex-island-app/releases/latest
- Size: 7.73 MB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
Codex Island
A Dynamic Island-style macOS companion for Codex CLI.
Keep local and remote Codex sessions visible from the notch.
Handle approvals, switch threads, and recover context without living in terminal tabs.
macOS 15.6+ · Local hooks · SSH remote hosts · Approval flows · Transcript-aware chat
Codex Island is a macOS notch and menu bar companion for Codex CLI. It keeps local sessions visible, connects to remote hosts over SSH, and gives you a lightweight place to inspect chat state, approvals, and recent context without constant terminal context switches.
## See It In Action
Remote workflow
Connect to a remote machine, resume threads, and work through SSH-backed Codex sessions from the same UI.
Local workflow
Track local sessions, surface plan-style interactions, and jump back into the right shell only when needed.
## Highlights
- Watches Codex sessions through `~/.codex/hooks.json` and a local Unix socket.
- Connects to remote machines over SSH and talks to `codex app-server` over stdio.
- Shows recent conversation history with markdown rendering and active model/context details in chat headers.
- Supports approval flows directly from the app UI.
- Tracks multiple local sessions and remote threads, and lets you switch between them quickly.
- Lets you save SSH targets, optional default working directories, and auto-connect remote hosts from the app.
- Includes launch-at-login, screen selection, sound settings, and in-app updates.
- Falls back gracefully on Macs without a physical notch.
## What's New in 0.0.3
- Moves much more of the local session flow onto a live local `codex app-server` connection instead of transcript-only fallback.
- Adds local `/new` and `/resume`, so you can start a fresh local thread or reopen an older one from the app UI.
- Surfaces local `/plan`, `/model`, and `/permissions` flows through the local app-server-backed chat experience.
- Keeps local plan follow-up choices visible and answerable in the UI more reliably, including ``-style completions.
- Tightens collapsed-notch status summaries, hover hit testing, prompt click handling, and debug-startup stability.
## Requirements
- macOS 15.6 or later
- Codex CLI installed locally
- SSH access to any remote machine you want to manage, with Codex CLI installed on that remote host
- Accessibility permission if you want the app to interact with window focus behavior
- `tmux` if you want tmux-aware messaging and approval workflows
- `yabai` if you want window focusing integrations
## Install
Download the latest release from GitHub, or build it locally with Xcode.
For a debug build:
```bash
xcodebuild -scheme CodexIsland -configuration Debug build
```
For a release build:
```bash
./scripts/build.sh
```
The exported app bundle is written to `build/export/Codex Island.app`.
## Remote Hosts Over SSH
Open `Remote Hosts` from the notch menu to add an SSH target, an optional default working directory, and an auto-connect preference for each remote machine.
When you connect a host, Codex Island launches:
```bash
ssh -T -o BatchMode=yes codex app-server --listen stdio://
```
That means remote hosts currently expect non-interactive SSH authentication, and the remote machine must already have `codex` available on `PATH`. Once connected, you can list remote threads, start a new thread, reopen an existing thread, send messages, interrupt turns, and handle approvals from the app UI. The remote chat view supports both `/new` for explicitly starting a fresh thread and `/resume` for switching back to an older thread.
Remote app-server diagnostics are disabled by default. After you enable `Remote Debug Logs` from the menu, the app writes JSONL diagnostics to `~/Library/Application Support/Codex Island/Logs/remote-app-server.jsonl`.
## How It Works
On first launch, Codex Island installs a managed hook script into `~/.codex/hooks/` and updates `~/.codex/hooks.json`. The hook helper forwards local Codex hook events to the app over a Unix domain socket, and the app reconciles those events with transcript data to keep session state accurate.
Remote hosts use a separate path: the app opens an SSH stdio transport to `codex app-server` on the target machine and keeps remote thread state alongside the local hooks-first session model.
The current architecture is still hooks-first inside the macOS app process. The `sidecar/` directory is a reserved Rust scaffold for future work around transcript parsing, state aggregation, and IPC.
## Project Layout
- `CodexIsland/App/`: app lifecycle and window bootstrap
- `CodexIsland/Core/`: shared settings, geometry, and screen selection
- `CodexIsland/Services/`: hooks, local session parsing, remote app-server management, tmux integration, updates, and window management
- `CodexIsland/UI/`: notch views, menu UI, chat UI, and reusable components
- `CodexIsland/Resources/`: bundled scripts such as `codex-island-state.py`
- `scripts/`: build, signing, notarization, and release helpers
- `sidecar/`: future Rust sidecar scaffold
## Privacy
The app currently initializes Mixpanel for anonymous product analytics and Sparkle for app updates.
Tracked analytics are intended to cover app launch and session lifecycle metadata such as:
- app version and build number
- macOS version
- detected Codex version
- session start events
The repository does not claim to collect conversation content in analytics, but you should still review the source and decide whether that tradeoff matches your environment before distributing it broadly.
## Development
Open the project in Xcode for day-to-day work. The repository also includes release automation for signing, notarization, DMG creation, appcast generation, and optional GitHub release publishing:
```bash
./scripts/create-release.sh
```
If you change anything under `CodexIsland/Services/Hooks/` or `CodexIsland/Resources/codex-island-state.py`, treat it as user-impacting local environment behavior and verify it carefully.
## Acknowledgements
Codex Island builds on the original ideas and earlier implementation work from [`farouqaldori/claude-island`](https://github.com/farouqaldori/claude-island). Thanks to Farouq Aldori and the upstream contributors for laying the foundation this Codex-focused version continues from.
## License
Apache 2.0. See [`LICENSE.md`](./LICENSE.md).