erha19/ping-island

A Dynamic Island-style command center for managing all your AI coding agents on macOS.

Ping Island – AI‑coding‑session monitor for macOS

What it is – A native macOS menu‑bar (and notch) app that watches the activity of many AI‑coding assistants (Claude, Codex, Gemini CLI, Hermes, Pi, Qwen, Kimi, OpenClaw, Cursor, Qoder, GitHub Copilot, etc.). When an assistant needs your attention—e.g. a tool‑approval request, a follow‑up question, or a completion notification—the app expands from the menu bar or the screen notch, shows the relevant context, and lets you act without hunting down the terminal or IDE tab that launched the request.

Quick start

Step Command / Action
Install brew install --cask ping-island (or download the DMG from the website)
Run Open Ping Island.app from Applications and grant the requested Accessibility / Apple‑Events permissions
Connect a client Start any supported AI‑coding client (e.g. Claude, Codex, Gemini CLI). The client’s hook file will automatically point to the bundled PingIslandBridge which forwards events to the app
Interact When a request appears, approve/deny or type a reply directly in the notch UI; click the “return” button to jump back to the originating iTerm2, Terminal, tmux pane, or IDE window

Core features

  • Attention‑first UI – stays hidden until an AI session needs input, then pops up from the menu bar or the screen notch.
  • One‑click return – jumps to the exact terminal/IDE window that generated the request.
  • Auto‑approve for Claude Code – optional per‑session auto‑approval to stop Claude from pausing on every permission request.
  • Remote‑host support – a lightweight PingIslandBridge can be installed on a Linux SSH host; the bridge forwards remote hook events back to the macOS UI.
  • Multi‑agent coverage – tracks 12+ agents and plugins (Claude, Codex, Gemini CLI, Antigravity CLI, Hermes, Pi, Qwen, Kimi, OpenClaw, OpenCode, Cursor, Qoder family, GitHub Copilot, etc.) in a single pane.
  • Customizable experience – three built‑in visual themes (native, macOS, Pixel) and three sound modes (system sounds, built‑in 8‑bit, user‑supplied sound packs). Each client can have its own animated mascot.
  • Buddy detach (v0.5+) – drag the active mascot out of the notch to keep a floating companion on the screen.

Supported clients (ingress → focus path)

Client How the app receives events How it returns focus
Claude Code Claude‑compatible hook files via PingIslandBridge Terminal.app, iTerm2, Ghostty, tmux, or IDE terminals
Codex (CLI + app‑server) Codex CLI hooks + live websocket to the Codex app‑server Codex app, terminal, tmux, IDE
Gemini CLI Hook entries in ~/.gemini/settings.json Any terminal host
Antigravity CLI Generated plugin under ~/.gemini/antigravity-cli/plugins/ping‑island/ Terminal hosts & remote SSH
Hermes Agent Plugin hooks in ~/.hermes/plugins/ping_island/ Hermes CLI terminal
Pi Agent Extension under ~/.pi/agent/extensions/ping_island/ Pi terminal host
Qwen Code Hook file in ~/.qwen/settings.json Terminal hosts & remote SSH
Kimi CLI [[hooks]] entries in ~/.kimi/config.toml Terminal hosts
OpenClaw Managed internal hooks + local transcript back‑fill OpenClaw terminal
OpenCode Plugin file under ~/.config/opencode/plugins/ OpenCode app & terminal
Cursor Claude‑compatible hooks + optional VS Code focus extension Cursor project window & terminal
Qoder family (IDE / CLI) Hook profiles in ~/.qoder* Qoder IDE windows, terminal, or VS Code‑compatible extensions
CodeBuddy / WorkBuddy Managed hooks + optional VS Code focus extension App windows, terminal, IDE
GitHub Copilot Copilot hook protocol Compatible terminal hosts

How it works (high‑level flow)

AI client (Claude, Codex, Gemini …) → hook or app‑server event
    → Ping Island monitor (normalizes different payloads)
        → SessionStore (keeps per‑client session state)
            → SessionMonitor / NotchViewModel
                → UI: notch bar, session list, hover preview, completion popup
  • The monitor translates each client’s native hook format into a common internal model.
  • SessionStore aggregates events (tool approvals, user prompts, completions) so the UI can show a concise timeline.
  • The NotchViewModel drives the compact UI that lives in the menu bar/notch and expands on demand.
  • For remote Linux hosts, the PingIslandBridge binary runs over SSH, rewrites the remote hooks to point back at the Mac, and forwards the remote Codex app‑server stream.

Building / testing (if you want to tinker)

# Clone and build (requires macOS 14+ and Xcode with Swift 6.1)
git clone https://github.com/erha19/ping-island.git && cd ping-island
xcodebuild -project PingIsland.xcodeproj -scheme PingIsland -configuration Release build

# Package an unsigned DMG for local testing
./scripts/package-unsigned.sh

# Run the full test suite
./scripts/test.sh   # runs Swift package tests and Xcode unit/UI tests
  • CI scripts also produce a signed, notarized release and a Linux PingIslandBridge asset.

Settings snapshot

Category What you can tweak
General Launch at login, default behavior
Display Which notch (if any) to use, placement
Mascot Per‑client mascot overrides, animation states
Sound Choose an experience theme, select system sounds or import a custom sound pack

Who might want this?

  • Developers who use multiple AI coding assistants and get frequent permission or clarification prompts.
  • People working on notch‑equipped Macs who prefer a tiny, always‑visible UI rather than switching windows.
  • Remote developers who run AI agents on Linux servers via SSH and still want local visibility.
  • Power‑users who like visual customisation – mascots, retro pixel theme, custom audio.

License & community

  • License: Apache 2.0 (permissive, allows commercial use).
  • Contributors: The repo lists a CONTRIBUTORS.md and provides documentation for adding new experience themes or supporting additional AI clients.
  • Privacy: A short privacy policy is linked in the header; the app only processes local hook events and does not send data elsewhere.

Bottom line: Ping Island is a focused, open‑source macOS utility that brings AI‑coding‑assistant notifications into the menu bar/notch, letting you stay in the flow while still keeping full control over approvals and follow‑up questions.

Related

  • Project
    Octane0411/open-vibe-island

    Open Island is a free, native macOS app that lives in the notch or menu bar and provides a live dashboard for AI coding agents (Claude Code, Codex, Cursor, Gemini‑CLI, etc.). It shows session status, handles permission prompts, displays usage stats, and lets you jump back to the exact terminal or IDE pane with a click. Integration is hook‑based: agents emit JSON events, a tiny CLI forwards them via Unix socket to the app, which updates its UI. Supports 13 agents and 15+ terminals/IDEs, runs locally with no telemetry, and is distributed as a signed DMG or Homebrew cask.

  • Project
    wxtsky/CodeIsland

    A real-time AI coding agent status panel for the macOS Dynamic Island that tracks sessions, tool calls, and permissions across 15 different AI tools.

  • Project
    manaflow-ai/cmux

    cmux is a native macOS terminal (built on Ghostty) that adds vertical tabs, a notification system, an in‑app scriptable browser, and SSH workspaces to help developers run and monitor multiple AI coding agents (Claude Code, Codex, OpenCode, etc.) in parallel.

  • Project
    MioMioOS/MioIsland

    A macOS native companion for Claude Code that brings agent status monitoring and permission approvals to the Dynamic Island and synchronizes sessions to iPhone.

  • Project
    Nanako0129/TokenBar

    A native macOS menu bar application that monitors AI token usage and subscription quotas across 25+ AI coding agents by parsing local session logs.