Open Island

Why pay for a closed-source app just to monitor your coding agents?
Open-source, local-first, native macOS companion for AI coding agents.

中文 | English

Download · Quick Start · Roadmap · Contributing

ℹ️ About this repository

This is a community-maintained documentation companion to Octane0411/open-vibe-island, with enhanced Chinese documentation and a sharpened "multi-agent macOS console" positioning.

Binaries / Releases — signed & notarized DMGs come from upstream releases. This repo does not ship separate binaries.

Code contributions — please submit PRs to the upstream repo.

This repo's focus — bilingual README polish, FAQ, Chinese community onboarding, documentation fidelity.

What is Open Island?

Open Island sits in your Mac's notch (or top bar) and gives you a real-time control surface for your AI coding agents — session status, permission approvals, and instant jump-back to the right terminal. All without leaving your flow.

Think of it as an open-source Vibe Island — free, local-first, and you own every bit of it.

You don't need to pay for a product you can vibe, since you are a vibe coder.

Why Open Island?

Open source — GPL v3, fork it, mod it, ship your own version
Local-first — No server, no telemetry, no account. Everything runs on your Mac
Native macOS — SwiftUI + AppKit, not an Electron wrapper
Multi-agent — One surface for Claude Code, Codex, Cursor, Gemini CLI, OpenCode, and more
Multi-terminal — Jump back to the exact terminal/IDE session in one click

Supported Agents & Terminals

9 agents: Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Qoder, Qwen Code, Factory, CodeBuddy

15+ terminals & IDEs: Terminal.app, Ghostty, iTerm2, WezTerm, Zellij, tmux, cmux, Kaku, VS Code, Cursor, Windsurf, Trae, JetBrains IDEs (IDEA, WebStorm, PyCharm, GoLand, CLion, RubyMine, PhpStorm, Rider, RustRover)

Full compatibility table

Code Agents

Agent	Status	Description
Claude Code	Supported	Hook integration, JSONL session discovery, status line bridge, usage tracking
Codex	Supported	Full hook integration (SessionStart, UserPromptSubmit, Stop), usage tracking
OpenCode	Supported	JS plugin integration, permission/question flows, process detection
Qoder	Supported	Claude Code fork — same hook format, config at `~/.qoder/settings.json`
Qwen Code	Supported	Claude Code fork — same hook format, config at `~/.qwen/settings.json`
Factory	Supported	Claude Code fork — same hook format, config at `~/.factory/settings.json`
CodeBuddy	Supported	Claude Code fork — same hook format, config at `~/.codebuddy/settings.json`
Cursor	Supported	Hook integration via `~/.cursor/hooks.json`, session tracking, workspace jump-back
Gemini CLI	Supported	Hook integration via `~/.gemini/settings.json`, session tracking, fire-and-forget events

Terminals & IDEs

Terminal / IDE	Support Level	Description
Terminal.app	Full	Jump-back with TTY targeting
Ghostty	Full	Jump-back with ID matching
cmux	Full	Jump-back via Unix socket API
Kaku	Full	Jump-back via CLI pane targeting
WezTerm	Full	Jump-back via CLI pane targeting
iTerm2	Full	Jump-back with session ID / TTY matching
tmux (multiplexer)	Full	Jump-back with session/window/pane targeting
Zellij	Full	Jump-back via CLI pane/tab targeting
VS Code	Workspace	Activate workspace via `code` CLI
Cursor	Workspace	Activate workspace via `cursor` CLI
Windsurf	Workspace	Activate workspace via `windsurf` CLI
Trae	Workspace	Activate workspace via `trae` CLI
JetBrains IDEs	Workspace	IDEA, WebStorm, PyCharm, GoLand, CLion, RubyMine, PhpStorm, Rider, RustRover
Warp	Full	Precision tab jump via SQLite pane lookup + AX menu click

Other Features

Feature	Description
Notch / top-bar overlay	Notch area on notch Macs, top-center bar on others
Control center	Hook status, usage dashboard
Notification mode	Auto-height panel for permission requests and session events
Notification sounds	Configurable system sounds, mute toggle
i18n	English, Simplified Chinese
Session discovery	Auto-discover from local transcripts, persist across launches
Auto-update	Sparkle-based automatic updates
Signed & notarized	DMG packaging with Apple notarization

Quick Start

Option 1: Download

Grab the latest DMG from GitHub Releases — signed and notarized, ready to run.

Option 2: Build from source

git clone https://github.com/Octane0411/open-vibe-island.git
cd open-vibe-island
open Package.swift   # Opens in Xcode — hit Run

On first launch, Open Island auto-discovers your active agent sessions and starts the live bridge. Hook installation is managed from the Control Center inside the app.

Requirements: macOS 14+, Swift 6.2, Xcode

How It Works

Agent (Claude Code / Codex / Cursor / ...)
  ↓ hook event
OpenIslandHooks CLI (stdin → Unix socket)
  ↓ JSON envelope
BridgeServer (in-app)
  ↓ state update
Notch overlay UI ← you see it here
  ↓ click
Jump back → correct terminal / IDE

Hooks fail open — if Open Island isn't running, your agents continue unaffected.

Architecture details

Four targets in one Swift package:

Target	Role
OpenIslandApp	SwiftUI + AppKit shell — menu bar, overlay panel, control center, settings
OpenIslandCore	Shared library — models, bridge transport (Unix socket IPC), hooks, session persistence
OpenIslandHooks	Lightweight CLI invoked by agent hooks, forwards payloads via Unix socket
OpenIslandSetup	Installer CLI for managing `~/.codex/config.toml` and hook entries

See docs/architecture.md for the full system design.

FAQ

Is Open Island an open-source alternative to Vibe Island? Yes. Open Island is a free, open-source (GPL v3), local-first alternative to Vibe Island — fork it, modify it, ship your own build.

	Open Island	Vibe Island
License	GPL v3 (open source)	Proprietary
Price	Free	Paid
Source code	Public, forkable	Closed
Runs	Locally, no server	—

Which AI coding agents does Open Island support? 9 agents: Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Qoder, Qwen Code, Factory, and CodeBuddy — one surface for all of them.

Does Open Island require a Mac with a notch? No. On non-notch Macs and external displays, it falls back to a compact top-center bar.

Does Open Island send my data anywhere? No. It's local-first — no server, no telemetry, no account. Everything runs on your Mac.

Does Open Island work with tmux, iTerm2, Ghostty, VS Code, Cursor, Warp? Yes — 15+ terminals and IDEs. Full jump-back for terminals (Terminal.app, Ghostty, iTerm2, tmux, WezTerm, Zellij, cmux, Kaku, Warp); workspace-level jump for IDEs (VS Code, Cursor, Windsurf, Trae, JetBrains family).

How does Open Island integrate with Claude Code / Codex / Cursor? Via each agent's native hook system (e.g., ~/.claude/settings.json, ~/.codex/config.toml, ~/.cursor/hooks.json). Install/uninstall is managed inside the app. Hooks fail open — if Open Island isn't running, your agent continues unaffected.

Can Open Island read my source code? No. It only receives hook events (session start, prompt submit, permission requests, stop). It doesn't read your project files.

How do I contribute? All code in the project is AI-produced. Paste the prompt from CONTRIBUTING.md into your coding agent and start iterating.

Community

Join us on Discord for discussion, feedback, and faster issue resolution:

We welcome issues, pull requests, and new maintainers. See CONTRIBUTING.md to get started.

WeChat group (for Chinese-speaking users)

Report a Bug via Your Code Agent

Copy this prompt into your agent (Claude Code, Codex, etc.) to auto-generate a well-structured issue:

Click to expand

I'm having an issue with Open Island (https://github.com/Octane0411/open-vibe-island).

Please help me file a GitHub issue. Do the following:

1. Collect my environment info:
   - Run `sw_vers` to get macOS version
   - Run `swift --version` to get Swift version
   - Check if Open Island is running: `ps aux | grep -i "open.island\|OpenIslandApp" | grep -v grep`
   - Get the app version: `defaults read ~/Applications/Open\ Island\ Dev.app/Contents/Info.plist CFBundleShortVersionString 2>/dev/null || echo "unknown"`
   - Check which terminal I'm using

2. Ask me to describe:
   - What I expected to happen
   - What actually happened
   - Steps to reproduce

3. Create the issue on GitHub using `gh issue create` with this format:
   - Title: concise summary
   - Body with sections: **Environment**, **Description**, **Steps to Reproduce**, **Expected vs Actual Behavior**
   - Add label "bug" if applicable

Repository: Octane0411/open-vibe-island

Star History

Contributors

Roadmap

See docs/roadmap.md.

Agent Parts

This section is written for agents.

The open-source macOS companion for terminal-native AI coding.

Open Island puts a lightweight control surface in your notch or top bar so you can keep an eye on live coding agents, follow session progress, and jump back to the right terminal without breaking flow.

Why This Product Exists

AI coding is becoming part of the daily development loop, but the surrounding control layer still too often means handing your machine over to a closed-source paid app.

Open Island takes the opposite approach:

Open source
Local first, no server dependency
Native macOS (SwiftUI + AppKit)
Built to support the terminal workflow, not replace it

Who It Is For

Developers who already live in the terminal and want a better way to work with coding agents on macOS without losing context.

Agent Integrations

Codex — Full hook-based integration. Receives SessionStart, UserPromptSubmit, and Stop events by default. Reads 5-hour and 7-day account usage windows from local rollout files. Install/uninstall managed hooks from the control center or CLI.
Claude Code — Hook-based integration via ~/.claude/settings.json. Discovers sessions from ~/.claude/projects/ JSONL transcripts. Persists and restores sessions across app launches. Managed status line bridge with opt-in installation. Reads cached 5-hour and 7-day usage windows.
OpenCode — JS plugin integration via ~/.config/opencode/plugins/. Plugin auto-installed on first launch. Receives session lifecycle, tool use, permission, and question events. Permission approval and question answering flows supported. Process detection via ps.
Qoder — Claude Code fork. Same hook format and events via ~/.qoder/settings.json. Use --source qoder with the hooks binary.
Qwen Code — Claude Code fork. Same hook format and events via ~/.qwen/settings.json. Use --source qwen with the hooks binary.
Factory — Claude Code fork. Same hook format and events via ~/.factory/settings.json. Use --source factory with the hooks binary.
CodeBuddy — Claude Code fork. Same hook format and events via ~/.codebuddy/settings.json. Use --source codebuddy with the hooks binary.
Cursor — Hook-based integration via ~/.cursor/hooks.json. Receives beforeSubmitPrompt, beforeShellExecution, beforeMCPExecution, beforeReadFile, afterFileEdit, and stop events. Session persistence across app launches. Workspace jump-back via cursor -r. Use --source cursor with the hooks binary.
Gemini CLI — Hook-based integration via ~/.gemini/settings.json. Receives SessionStart, PreToolUse, PostToolUse, Stop, and UserPromptSubmit events. Fire-and-forget (no block/deny). Use --source gemini with the hooks binary.

Terminal Support

Terminal.app, Ghostty, cmux, Kaku, WezTerm, iTerm2, and Zellij — Full jump-back support with session attachment matching (cmux via Unix socket API, Kaku/WezTerm/Zellij via CLI pane targeting, iTerm2 via AppleScript session/TTY probe)
VS Code, VS Code Insiders, Cursor, Windsurf, Trae — Workspace-level jump via respective CLI (code -r, cursor -r, etc.)
JetBrains IDEs (IntelliJ IDEA, WebStorm, PyCharm, GoLand, CLion, RubyMine, PhpStorm, Rider, RustRover) — Workspace-level jump via IDE CLI launcher
Warp — Precision tab jump via SQLite pane lookup, pid-based sibling-tab disambiguation, and AX menu click

UI & Display

Notch overlay — On Macs with a built-in notch, the island sits in the notch area; on external displays or non-notch Macs, it falls back to a compact top-center bar
Control center — Codex/Claude hook status, usage dashboard, debug scenarios
Settings — General, Display, Sound, Shortcuts, Lab (advanced), About
Notification mode — Auto-height notification panel for permission requests and session events
Notification sounds — Configurable system sounds (default: Bottle) with mute toggle
i18n — English and Simplified Chinese

Session Management

Live session visibility with expandable detail rows
Session state reducer (SessionState.apply) as single source of truth
Automatic session discovery from local transcript files and cache
Process discovery via ps/lsof for active agent matching

Architecture

Four targets in one Swift package:

Target	Role
OpenIslandApp	SwiftUI + AppKit shell — menu bar, overlay panel, control center, settings
OpenIslandCore	Shared library — models, bridge transport (Unix socket IPC), hooks, session persistence
OpenIslandHooks	Lightweight CLI invoked by agent hooks, forwards payloads via Unix socket
OpenIslandSetup	Installer CLI for managing `~/.codex/config.toml` and hook entries

Quick Start (Agent)

Build and run locally:

open Package.swift

Build a local .app bundle:

zsh scripts/package-app.sh

That script creates output/package/Open Island.app and output/package/Open Island.zip. Pass OPEN_ISLAND_SIGN_IDENTITY to sign the bundle. See docs/packaging.md for the full path, including notarization.

Connect Codex

Open the package in Xcode to run the macOS app target. On launch, the app restores its local cache, scans recent ~/.codex/sessions/**/rollout-*.jsonl files for existing Codex sessions, and starts the live bridge for new hook events.

The control center shows live Codex hook install status from ~/.codex, and can install or uninstall managed hook entries directly. Installs copy the helper into ~/Library/Application Support/OpenIsland/bin/OpenIslandHooks so repo renames do not break existing hooks.

swift build -c release --product OpenIslandHooks
swift run OpenIslandSetup install
swift run OpenIslandSetup status
swift run OpenIslandSetup uninstall

Connect Claude Code

Claude usage setup is available from the app's control center and remains opt-in. The bridge writes a managed statusLine.command to ~/.open-island/bin/open-island-statusline, caches rate_limits into /tmp/open-island-rl.json, and refuses to overwrite an existing custom status line automatically.

Repository Map

Start with docs/index.md for the current doc map.
Read docs/quality.md for the quality baseline and verification approach.
Read docs/hooks.md for all supported hook events, payload fields, and directive response formats.
Run scripts/harness.sh for automated checks (docs validation, tests, build).

Requirements

macOS 14+
Swift 6.2
Xcode (for the app target)

License

GPL v3

Name		Name	Last commit message	Last commit date
Latest commit History 743 Commits
.github		.github
Assets/Brand		Assets/Brand
Sources		Sources
Tests		Tests
config/packaging		config/packaging
docs		docs
ios		ios
scripts		scripts
.editorconfig		.editorconfig
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTING.zh-CN.md		CONTRIBUTING.zh-CN.md
LICENSE		LICENSE
PRIVACY_POLICY.md		PRIVACY_POLICY.md
Package.swift		Package.swift
README.md		README.md
README.zh-CN.md		README.zh-CN.md
appcast.xml		appcast.xml

Folders and files

Latest commit

History

Repository files navigation

Open Island

What is Open Island?

Why Open Island?

Supported Agents & Terminals

Code Agents

Terminals & IDEs

Other Features

Quick Start

Option 1: Download

Option 2: Build from source

How It Works

FAQ

Community

Report a Bug via Your Code Agent

Star History

Contributors

Roadmap

Agent Parts

Why This Product Exists

Who It Is For

Agent Integrations

Terminal Support

UI & Display

Session Management

Architecture

Quick Start (Agent)

Connect Codex

Connect Claude Code

Repository Map

Requirements

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages