Ping Island

AI coding session monitor for the macOS menu bar
Website • Try it • Install • Features • Supported Clients • Build • Developers • Sponsor • Privacy
English | 简体中文

_{Watch active coding sessions, answer follow-up questions, and jump back to the right terminal or IDE window.}

_{Official website: erha19.github.io/ping-island}

                         

_{Claude Code · ChatGPT · Codex CLI · Gemini CLI · Antigravity CLI · Hermes Agent · Pi Agent · Oh My Pi · Qwen Code · Kimi CLI · OpenClaw · OpenCode · Cursor · Qoder IDE · Qoder CN IDE · CodeBuddy · GitHub Copilot}

Let’s try it!

Detach the active pet from the notch and keep session status nearby while you work across other windows.

On notch-screen Macs, Ping Island expands from the notch with session context and action controls when an agent needs attention.

Installation

Install with Homebrew Cask

brew install --cask ping-island

Download a Release

1. Visit the official website for the product overview and latest download link, or go straight to Releases.
2. Download the latest DMG.
3. Move Ping Island.app into your Applications folder.
4. Launch the app and start the clients you want Ping Island to monitor.

On first launch, macOS may ask you to confirm the app or grant Accessibility / Apple Events permissions for focus features.

Build from Source

Requires macOS 14+ and an Xcode toolchain that can build the Xcode project and the Swift 6.1 Prototype package tests.

git clone https://github.com/erha19/ping-island.git
cd ping-island

# Debug build
xcodebuild -project PingIsland.xcodeproj -scheme PingIsland -configuration Debug build

# Release build
xcodebuild -project PingIsland.xcodeproj -scheme PingIsland -configuration Release build

To create a locally shareable unsigned package for local testing:

./scripts/package-unsigned.sh

The script re-signs the built app bundle with a consistent ad-hoc signature before creating the .dmg and .zip, which helps embedded frameworks launch more reliably on another machine. The package is still unsigned for distribution and not notarized, so first launch may still require Open from Finder's context menu or manual quarantine removal. The generated files land in releases/unsigned/ as PingIsland-<version>.dmg and PingIsland-<version>.zip. The DMG uses the repo-tracked installer artwork at docs/images/ping-island-dmg-installer-background.png by default; set PING_ISLAND_DMG_BACKGROUND_SOURCE if you want to preview a different background locally.

To create signed and notarized release packages in GitHub Actions, configure the release secrets described in docs/sparkle-release.md and run .github/workflows/release-packages.yml against a v* tag or the manual workflow dispatch input. Official Homebrew Cask release notes are documented in docs/homebrew-cask-release.md.

The same workflow also publishes a Linux PingIslandBridge asset that Ping Island can download when bootstrapping Linux SSH hosts.

For the full notarized release flow and the GitHub Releases backed Sparkle appcast setup, see docs/sparkle-release.md.

What is Ping Island?

Ping Island is a macOS menu bar app that expands into a compact session surface when your coding agents need attention. It listens to Claude-style hooks, Codex hooks, Gemini CLI hooks, Antigravity CLI plugin hooks, Hermes Agent plugin hooks, Pi Agent extension hooks, Oh My Pi hooks, Qwen Code hooks, Kimi CLI hooks, OpenClaw internal hooks plus session transcripts, the Codex app-server, OpenCode plugins, and compatible IDE integrations so approvals, input requests, completions, and session summaries show up without babysitting terminal tabs.

If you have seen Vibe Island, Ping Island is positioned as an independent open-source alternative in the same category: a native macOS notch/menu bar surface for monitoring and controlling AI coding sessions.

Features

Ping Island focuses on the moments that actually interrupt coding flow, then keeps them visible and actionable from a native macOS notch surface.

• Attention-first UI - Stay compact until a session needs approval, input, review, or intervention.
• Act from the notch - Approve tools, deny requests, and answer follow-up prompts without hunting through tabs.
• Claude Code auto-approve - Turn on per-session auto-approval when you want Claude Code to stop pausing on every permission request.
• One-click return - Jump back to the right iTerm2, Ghostty, Terminal.app, tmux pane, or IDE window.
• SSH terminal support - Bootstrap a remote PingIslandBridge over SSH, rewrite remote hooks to point back at your Mac, forward remote Codex app-server activity and usage snapshots, and keep remote terminal activity visible in the same local Island UI.
• Multi-agent coverage - Track Claude Code, Codex, Gemini CLI, Antigravity CLI, Hermes Agent, Pi Agent, Oh My Pi (OMP), Qwen Code, Kimi CLI, OpenClaw, OpenCode, Cursor, Qoder IDE, Qoder CN IDE, CodeBuddy, WorkBuddy, GitHub Copilot, and other compatible sessions in one place.
• OpenClaw gateway support - Follow OpenClaw sessions from managed internal hooks, then refill the conversation from OpenClaw's local session transcripts so the Island UI can show the actual back-and-forth instead of a single inbound message.
• Codex hook + app-server sync - Support Codex CLI hooks, live app-server threads, and rollout parsing fallback when needed.
• Experience themes - Choose PingIsland native, macOS, or Pixel (with two classic palettes); themes coordinate window chrome, icons, controls, motion, and semantic audio.
• Custom sounds - Pick per-event macOS sounds or import local sound packs without changing the selected visual experience.
• Custom agent mascots - Give each client its own animated mascot override across the notch, session list, and hover UI.
• Buddy detach in v0.5.0+ - Drag the active Buddy out of the notch so it can stay nearby as an independent floating companion.
• Hermes courier-fox mascot - Hermes Agent uses a gold courier fox with a winged helmet and satchel so plugin-hook sessions stay visually distinct from the Claude/Qwen family.
• Pi terminal-cloud mascot - Pi Agent uses its own terminal-cloud mascot so extension-hook sessions are easy to spot in the Island UI.
• Oh My Pi mascot and prompts - Oh My Pi (OMP) has its own orange pixel mascot, with tool approvals and ask questions answerable from the Island.
• Qwen capybara mascot - Qwen Code now ships with a mint-scarf capybara mascot tuned for prompt, reply, and notification-heavy flows.
• Kimi keyboard-orb mascot - Kimi CLI keeps its original blue keyboard-orb mascot so its hook sessions stay visually distinct in the README strip and app UI.

Supported Clients

Testing

The fastest full-repo regression path is:

./scripts/test.sh

That covers:

swift test --package-path Prototype
xcodebuild -project PingIsland.xcodeproj -scheme PingIsland -configuration Debug CODE_SIGNING_ALLOWED=NO test -only-testing:PingIslandTests
xcodebuild -project PingIsland.xcodeproj -scheme PingIsland -configuration Debug CODE_SIGN_IDENTITY=- test

Useful targeted slices:

swift test --package-path Prototype --filter IslandBridgeE2ETests
xcodebuild -project PingIsland.xcodeproj -scheme PingIsland -configuration Debug CODE_SIGNING_ALLOWED=NO test -only-testing:PingIslandTests
xcodebuild -project PingIsland.xcodeproj -scheme PingIsland -configuration Debug CODE_SIGN_IDENTITY=- test -only-testing:PingIslandUITests

If PingIslandUITests-Runner stays suspended on macOS, run the UI tests from Xcode with a valid local signing identity and check amfid / AppleSystemPolicy logs before treating it as an app regression.

Settings

Ping Island currently ships a 4-category settings panel:

• General - appearance (System / Light / Dark), launch at login and baseline app behavior
• Display - notch display target and placement behavior
• Mascot - client mascot previews, per-client overrides, animation states
• Sound - experience-theme selection, event-specific sounds, sound pack mode, sound pack import

Experience Themes

Ping Island includes three built-in experience themes under Settings -> Sound -> Experience theme:

Pixel includes Arcade Neon and Game Boy Olive palettes. They share one component, motion, and sound implementation; changing the palette does not reset your sound selection.

Themes are more than a color preset: the same theme supplies visual tokens, confirmation-action appearance, motion timing, lifecycle sound mappings, and auxiliary cues. In addition to the five configurable notification stages, themes cover launch, new sessions, approvals, waiting reminders, rapid submits, and usage warning/recovery edges.

The screen-attached notch remains canonical black across every theme. Theme selection changes Settings and theme-aware detached surfaces, but never recolors the macOS notch area.

All three themes share the same native Settings window shell, so dragging, traffic lights, resizing and full-screen behavior remain consistent. The PingIsland, macOS and Pixel families then render distinct sidebar rows, icons, surfaces and controls inside that shell. Category selection updates immediately; heavier refresh work is deferred, cancellable and cached.

Choosing a theme applies its recommended sound mode. You can then switch to a local CESP/OpenPeon sound pack; this changes audio only and does not replace the active visual or interaction theme. See the theme architecture and extension guide for the contributor-facing contract.

Custom Sounds

Ping Island currently supports three sound modes under Settings -> Sound:

• System sounds - choose a macOS sound for each event.
• Built-in 8-bit - use Island's bundled retro sound set, including themed startup and action feedback.
• Sound pack - load a local OpenPeon / CESP-compatible pack from disk.

Quick setup

1. Open Settings -> Sound.
2. Turn on Enable sounds.
3. Pick the mode you want:
   • System sounds if you just want a different macOS sound per event.
   • Sound pack if you want fully custom audio files.
4. Preview each event with the play button and leave only the event toggles you want enabled.

Import a local sound pack

1. Switch Sound mode to Sound pack.
2. Click Import local sound pack.
3. Choose a folder that contains openpeon.json.
4. Pick the imported pack from the Sound pack dropdown.

Ping Island also auto-discovers packs placed under ~/.openpeon/packs and ~/.claude/hooks/peon-ping/packs.

Minimal sound pack layout

my-pack/
  openpeon.json
  session-start.wav
  attention.ogg
  complete.mp3
  error.wav
  limit.wav

{
  "cesp_version": "1.0",
  "name": "my-pack",
  "display_name": "My Pack",
  "categories": {
    "task.acknowledge": {
      "sounds": [{ "file": "session-start.wav", "label": "Session Start" }]
    },
    "input.required": {
      "sounds": [{ "file": "attention.ogg", "label": "Attention" }]
    },
    "task.complete": {
      "sounds": [{ "file": "complete.mp3", "label": "Complete" }]
    },
    "task.error": {
      "sounds": [{ "file": "error.wav", "label": "Error" }]
    },
    "resource.limit": {
      "sounds": [{ "file": "limit.wav", "label": "Limit" }]
    }
  }
}

Event mapping

• Processing started checks task.acknowledge, then session.start.
• Attention required checks input.required.
• Task completed checks task.complete.
• Task error checks task.error.
• Resource limit checks resource.limit.

Release builds can also publish a Linux PingIslandBridge artifact alongside the macOS app packages, which Ping Island uses when bootstrapping remote SSH hosts that are not running macOS.

Sound packs can use .wav, .mp3, or .ogg files. If a selected pack does not provide a matching category for an event, Ping Island falls back to the macOS system sound selected for that event.

How It Works

Claude / Codex / Gemini CLI / Antigravity CLI / Hermes Agent / Pi Agent / Oh My Pi (OMP) / Qwen Code / Kimi CLI / OpenCode / Cursor / Qoder IDE / Qoder CN IDE / CodeBuddy / WorkBuddy / Copilot / ...
  -> hook or app-server event
    -> Ping Island monitor + normalization layer
      -> SessionStore
        -> SessionMonitor / NotchViewModel
          -> notch, list, hover preview, completion popup

Implementation details worth knowing:

• Claude-family tools enter through managed hook files plus the embedded PingIslandBridge launcher.
• Codex sessions can come from hook events or the live codex app-server websocket monitor.
• Gemini CLI hooks are installed into ~/.gemini/settings.json; tool matchers use Gemini's regex-based hook matcher syntax.
• Antigravity CLI uses a generated native plugin under ~/.gemini/antigravity-cli/plugins/ping-island/; Ping Island returns ask from its observational PreToolUse hook so Antigravity's own permission engine remains authoritative.
• Pi Agent is wired through a generated TypeScript extension under ~/.pi/agent/extensions/ping_island/ and forwards events through the Claude-compatible bridge with Pi-specific client metadata.
• Oh My Pi (OMP) uses a generated TypeScript hook at ~/.omp/agent/hooks/pre/ping-island.ts and forwards events with its own OMP client identity. Built-in ask questions are routed to Island first, falling back to OMP's native question UI if the bridge is unavailable or the connection closes without an answer.
• Qwen Code hooks are installed into ~/.qwen/settings.json; the bridge follows the official event names and uses Stop / SessionEnd / Notification messages to surface popup-ready summaries in Island.
• Kimi CLI hooks are installed into ~/.kimi/config.toml; Ping Island preserves unrelated TOML content and maps Kimi Stop to turn completion while SessionEnd closes the session.
• OpenCode is wired through a generated plugin file under ~/.config/opencode/plugins/ and enabled from the documented global config at ~/.config/opencode/opencode.json; legacy config.json entries are still recognized for cleanup.
• Remote SSH hosts can bootstrap PingIslandBridge, rewrite remote Claude-compatible hooks to target that bridge, and forward remote events plus Codex usage snapshots back into the local Ping Island UI.
• Focus routing spans iTerm2, Ghostty, Terminal.app, tmux, and VS Code-compatible IDE extensions.

Themes and the floating task count

Right-click the floating pet to open Settings → General → Appearance. Choose Follow System (the default), Light, or Dark. The choice is saved and applies immediately to Settings, detached panels, and the task count (black in light mode, white in dark mode). System mode follows macOS appearance changes automatically. The screen-attached notch stays black.

Appearance is independent of Sound → Experience theme (PingIsland native, macOS, or Pixel): changing appearance does not reset your theme, Pixel palette, or sounds, and selecting a theme does not reset appearance.

Requirements

• macOS 14.0 or later
• Best experience on MacBooks with a notch, but external displays are supported too
• Install whichever CLI or desktop clients you want Ping Island to monitor

Developers

Ping Island grows with the people who build it. From client integrations and interaction design to bug fixes and documentation, every contribution makes the island a little better. Thank you to everyone who shares code, tests a release, or brings a fresh idea. ❤️

Explore their contributions and give them a follow. Want to help shape Ping Island? Share an idea or report a bug in Issues, or contribute a Pull Request.

Acknowledgments

Ping Island follows the lineage of notch-first agent monitors such as claude-island, and adapts that idea into a broader multi-client session surface with hooks, app-server sync, and IDE routing.

Support & Sponsoring

If Ping Island helps you stay focused while your agents work, consider supporting its ongoing development and maintenance. Thank you for helping this little island grow. ❤️

You can also scan a QR code with Alipay or WeChat Pay:

License

Apache 2.0 - see LICENSE.md.