ping-island

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, Hermes Agent plugin hooks, Pi Agent extension 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 keep remote terminal activity visible in the same local Island UI.
• Multi-agent coverage - Track Claude Code, Codex, Gemini CLI, Hermes Agent, Pi Agent, Qwen Code, Kimi CLI, OpenClaw, OpenCode, Cursor, Qoder, Qoder CN, 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.
• Custom sounds - Pick per-event macOS sounds or import local sound packs for your own notification style.
• 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.
• 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