Octane0411/open-vibe-island

Open Island – a native macOS control panel for AI coding agents

What it is – Open Island is a free, open‑source macOS app that lives in the notch (or top‑center of the menu bar) and shows the status of the AI‑coding agents you run in your terminal or IDE. It lets you see which agent is active, approve permission prompts, view usage stats and jump back to the exact terminal/IDE pane that the agent is talking to – all without leaving your workflow.

Why it matters – Many developers use tools like Claude Code, Codex, Cursor, Gemini‑CLI, etc. to generate code from the command line. Existing commercial products bundle a UI around these agents, but they are closed‑source, require accounts, and often run in the cloud. Open Island gives the same convenience locally, with no telemetry, and lets you keep full control of the software stack.

---

Key features (as described in the README)

Feature	What you get
Notch / top‑bar overlay	A tiny panel that lives in the Mac’s notch or menu‑bar, always visible while you code.
Multi‑agent support	Works with 13 agents (Claude Code, Codex, Cursor, Gemini‑CLI, Grok Build, Kimi CLI, OpenCode, Pi, Oh My Pi, Qoder, Qwen Code, Factory, CodeBuddy).
Multi‑terminal & IDE support	Detects and can jump back to 15+ terminals/IDEs (Terminal.app, iTerm2, WezTerm, Ghostty, tmux, Zellij, VS Code, JetBrains IDEs, Warp, etc.).
Live session discovery	Reads local transcript files and watches processes to automatically list active agent sessions.
Permission handling	Shows permission‑request notifications from agents; you can approve/deny directly from the overlay.
Usage dashboard	Shows recent usage windows (5‑hour / 7‑day) for agents that expose them (e.g., Claude Code, Codex).
Hook‑based integration	A small CLI (OpenIslandHooks) is invoked by each agent’s hook system; it forwards JSON events over a Unix socket to the app.
Full‑screen‑less updates	Auto‑updates via Sparkle; the DMG is signed and notarized.
Internationalisation	UI available in English and Simplified Chinese.
Open‑source & local‑first	GPL‑v3 licence, no remote server, no telemetry.

---

How it works (high‑level architecture)

1. Agent emits a hook – When an AI coding agent starts a session, receives a prompt, uses a tool, etc., it writes a JSON payload to stdout.
2. OpenIslandHooks CLI – The hook command runs a tiny Swift CLI that reads the JSON and forwards it over a Unix‑socket to the running app.
3. Bridge server inside the app – Receives the payload, updates the internal session model, and refreshes the UI.
4. Overlay UI – Shows the list of sessions, their state, and lets you click to jump back to the originating terminal/IDE.
5. Jump‑back – The app uses the appropriate mechanism for the target (AppleScript for iTerm2, CLI code -r for VS Code, SQLite lookup for Warp, etc.) to bring the correct pane to the foreground.

The architecture is split into four Swift package targets:

• OpenIslandApp – SwiftUI/AppKit UI.
• OpenIslandCore – Shared models, IPC, session persistence.
• OpenIslandHooks – The CLI invoked by agents.
• OpenIslandSetup – Helper for installing/removing hook entries in each agent’s config file.

---

Getting started

Method	Steps
Download (DMG)	Grab the latest release from the Releases page, open the DMG (it’s already notarized) and drag the app to /Applications.
Homebrew	brew install --cask open-island – upgrades later with brew upgrade --cask open-island.
Build from source	```bash
git clone https://github.com/Octane0411/open-vibe-island.git
cd open-vibe-island
open Package.swift # opens in Xcode, press Run

On first launch the app scans for running agents, installs the necessary hook files (you can manage this from the Settings window), and starts showing live sessions.

---

### Who should use it?
- Developers who spend most of their day in a terminal and use AI‑coding assistants.
- Anyone who wants a **local, privacy‑preserving** UI for those assistants instead of a paid cloud service.
- Users of any of the supported agents or terminals – the README lists a full compatibility table.

---

### Community & contribution
- **Discord** – active chat for support, feature ideas, and quick help.
- **WeChat** – QR code provided for Chinese‑speaking users.
- Contributions are welcomed; see `CONTRIBUTING.md` for guidelines. The project uses a standard Swift package layout, making it straightforward to add new agents or terminals.

---

### Quick reference checklist
- ✅ Open‑source (GPL‑v3) – you can fork or modify.
- ✅ No server, no telemetry – runs entirely on your Mac.
- ✅ Native SwiftUI/AppKit – no Electron overhead.
- ✅ Supports 13 major AI coding agents and 15+ terminals/IDEs.
- ✅ Automatic updates via Sparkle.
- ✅ Internationalised (EN/zh‑CN).

---

**Bottom line** – Open Island is a genuine, open‑source macOS companion that gives developers a lightweight, always‑visible dashboard for their AI coding agents, keeping the workflow local, fast, and under the user’s control.