erha19/ping-island

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

Ping Island – macOS용 AI 코딩 세션 모니터

무엇인가요 – Claude, Codex, Gemini CLI, Hermes, Pi, Qwen, Kimi, OpenClaw, Cursor, Qoder, GitHub Copilot 등 여러 AI 코딩 보조 도구의 활동을 모니터링하는 macOS 메뉴바(또는 노치) 전용 앱입니다. 보조 도구가 당신의 주의가 필요할 때(예: 도구 승인 요청, 추가 질문, 완료 알림 등) 앱은 메뉴바나 화면 노치에서 확장되어 관련 맥락을 표시하고, 터미널이나 IDE 탭을 찾아 헤매지 않고도 즉시 대응할 수 있게 해줍니다.

빠른 시작

단계	명령어 / 조작
설치	`brew install --cask ping-island` (또는 웹사이트에서 DMG 다운로드)
실행	Applications에서 Ping Island.app을 열고 요청된 접근성/Apple-Events 권한을 부여
클라이언트 연결	지원되는 AI 코딩 클라이언트 중 하나(예: Claude, Codex, Gemini CLI)를 시작합니다. 클라이언트의 훅 파일은 자동으로 번들된 `PingIslandBridge`를 가리키며, 이는 이벤트를 앱으로 전달합니다
상호작용	요청이 나타나면 노치 UI에서 승인/거부하거나 직접 답을 입력할 수 있습니다. "return" 버튼을 클릭하면 요청을 생성한 iTerm2, Terminal, tmux 패널 또는 IDE 창으로 바로 이동합니다

핵심 기능

주의 우선 UI – AI 세션이 입력이 필요할 때만 숨겨져 있으며, 메뉴바나 화면 노치에서 튀어나와 표시됩니다.
한 번 클릭으로 돌아가기 – 요청을 생성한 정확한 터미널/IDE 창으로 바로 이동합니다.
Claude Code용 자동 승인 – 세션별로 선택적으로 자동 승인을 활성화하여 Claude가 매번 권한 요청에서 멈추는 것을 방지합니다.
원격 호스트 지원 – 가벼운 PingIslandBridge를 Linux SSH 호스트에 설치할 수 있습니다. 브리지가 원격 훅 이벤트를 macOS UI로 다시 전달합니다.
다중 에이전트 커버리지 – Claude, Codex, Gemini CLI, Antigravity CLI, Hermes, Pi, Qwen, Kimi, OpenClaw, OpenCode, Cursor, Qoder 가족, GitHub Copilot 등 12개 이상의 에이전트와 플러그인을 하나의 패널에서 추적합니다.
사용자 맞춤형 경험 – 세 가지 내장 시각 테마(네이티브, macOS, Pixel)와 세 가지 사운드 모드(시스템 사운드, 내장 8비트 사운드, 사용자 제공 사운드 팩)를 제공합니다. 각 클라이언트마다 고유한 애니메이션 마스코트를 설정할 수 있습니다.
버디 분리 (v0.5+) – 활성 마스코트를 노치에서 끌어내어 화면에 떠 있는 동반자로 유지할 수 있습니다.

지원되는 클라이언트 (입구 → 포커스 경로)

클라이언트	앱이 이벤트를 수신하는 방식	포커스를 되돌리는 방식
Claude Code	`PingIslandBridge`를 통한 Claude 호환 훅 파일	Terminal.app, iTerm2, Ghostty, tmux, 또는 IDE 터미널
Codex (CLI + 앱서버)	Codex CLI 훅 + Codex 앱서버로의 실시간 웹소켓 연결	Codex 앱, 터미널, tmux, IDE
Gemini CLI	`~/.gemini/settings.json` 내 훅 항목	어떤 터미널 호스트든
Antigravity CLI	`~/.gemini/antigravity-cli/plugins/ping‑island/`에 생성된 플러그인	터미널 호스트 및 원격 SSH
Hermes 에이전트	`~/.hermes/plugins/ping_island/`에 있는 플러그인 훅	Hermes CLI 터미널
Pi 에이전트	`~/.pi/agent/extensions/ping_island/`에 있는 확장
Qwen 코드	`~/.qwen/settings.json`에 있는 훅 파일	터미널 호스트 및 원격 SSH
Kimi CLI	`~/.kimi/config.toml`의 `[[hooks]]` 항목	터미널 호스트
OpenClaw	관리되는 내부 훅 + 로컬 전사본 채우기	OpenClaw 터미널
OpenCode	`~/.config/opencode/plugins/`에 있는 플러그인 파일	OpenCode 앱 및 터미널
Cursor	Claude 호환 훅 + 선택적 VS Code 포커스 확장
Qoder 가족 (IDE / CLI)	`~/.qoder*`에 있는 훅 프로파일	Qoder IDE 창, 터미널, 또는 VS Code 호환 확장
CodeBuddy / WorkBuddy	관리되는 훅 + 선택적 VS Code 포커스 확장	앱 창, 터미널, IDE
GitHub Copilot	Copilot 훅 프로토콜	호환되는 터미널 호스트

작동 방식 (고수준 흐름)

AI 클라이언트 (Claude, Codex, Gemini …) → 훅 또는 앱서버 이벤트
    → Ping Island 모니터 (다양한 페이로드를 통일된 내부 모델로 변환)
        → SessionStore (클라이언트별 세션 상태를 유지)
            → SessionMonitor / NotchViewModel
                → UI: 노치 바, 세션 목록, 호버 미리보기, 완료 팝업

모니터는 각 클라이언트의 원본 훅 형식을 공통 내부 모델로 변환합니다.
SessionStore는 도구 승인, 사용자 프롬프트, 완료 등의 이벤트를 집계하여 UI가 간결한 타임라인을 표시할 수 있게 합니다.
NotchViewModel은 메뉴바/노치에 위치한 컴팩트한 UI를 제어하며, 필요 시 확장됩니다.
원격 Linux 호스트의 경우 PingIslandBridge 바이너리가 SSH를 통해 실행되며, 원격 훅을 Mac으로 다시 가리키고 원격 Codex 앱서버 스트림을 전달합니다.

빌드 및 테스트 (자체 수정을 원하는 경우)

# 복제 및 빌드 (macOS 14+ 및 Swift 6.1이 포함된 Xcode 필요)
git clone https://github.com/erha19/ping-island.git && cd ping-island
xcodebuild -project PingIsland.xcodeproj -scheme PingIsland -configuration Release build

# 로컬 테스트용 서명되지 않은 DMG 패키징
./scripts/package-unsigned.sh

# 전체 테스트 세트 실행
./scripts/test.sh   # Swift 패키지 테스트 및 Xcode 단위/UI 테스트 실행

CI 스크립트는 서명된, 노타라이즈된 릴리스와 Linux용 PingIslandBridge 자산도 생성합니다.

설정 스냅샷

카테고리	조정 가능한 항목
일반	로그인 시 자동 시작, 기본 동작
표시	사용할 노치(없을 수도 있음), 배치
마스코트	클라이언트별 마스코트 오버라이드, 애니메이션 상태
사운드	경험 테마 선택, 시스템 사운드 또는 사용자 사운드 팩 가져오기

누가 이걸 원할까?

여러 AI 코딩 보조 도구를 사용하는 개발자 – 자주 권한 또는 설명 요청을 받는 경우.
노치가 있는 맥을 사용하는 사용자 – 창 전환 없이 작고 항상 보이는 UI를 선호하는 경우.
원격 개발자 – SSH를 통해 Linux 서버에서 AI 에이전트를 실행하면서도 로컬에서 시각적 가시성을 유지하고 싶은 경우.
시각적 커스터마이징을 좋아하는 고급 사용자 – 마스코트, 레트로 픽셀 테마, 사용자 사운드.

라이선스 및 커뮤니티

라이선스: Apache 2.0 (허용적인 라이선스로 상업적 사용 허용).
기여자: 리포지토리에는 CONTRIBUTORS.md가 있으며, 새로운 경험 테마 추가 또는 추가 AI 클라이언트 지원 방법에 대한 문서도 제공합니다.
개인정보 보호: 헤더에 링크된 짧은 개인정보 보호 정책이 있으며, 앱은 로컬 훅 이벤트만 처리하고 외부로 데이터를 전송하지 않습니다.

결론적으로: Ping Island는 AI 코딩 보조 도구의 알림을 메뉴바/노치로 가져오는 집중적이고 오픈소스의 macOS 유틸리티로, 승인 및 추가 질문을 완전히 제어하면서도 작업 흐름을 끊지 않고 유지할 수 있게 해줍니다.