ping-island: Instructions file for Claude Code

AGENTS.md

This file is a routing layer for coding agents working in this repo. Keep it short. Put long-lived detail in nearby code, focused docs, or tests.

Mission

• PingIsland is a macOS menu bar app that surfaces Dynamic Island-style status for Claude Code, Codex, Gemini CLI, Antigravity CLI, Hermes Agent, Qwen Code, Kimi CLI, Oh My Pi, and compatible hook-driven agent sessions.
• The main runtime path is:
  • hook or app-server events
  • monitoring and service layers
  • SessionStore
  • SessionMonitor and NotchViewModel
  • SwiftUI notch UI
• There are two important codepaths:
  • PingIsland/: the shipping Xcode app
  • Prototype/: a SwiftPM prototype with focused tests and reference implementations

Start Here

• Product overview: README.md
• App entry: PingIsland/App/PingIslandApp.swift, PingIsland/App/AppDelegate.swift
• Docked/detached presentation orchestration: PingIsland/App/IslandPresentationCoordinator.swift, PingIsland/App/WindowManager.swift
• First-run surface-mode onboarding and mode-switch UI: PingIsland/App/AppDelegate.swift, PingIsland/UI/Window/SettingsWindowController.swift, PingIsland/UI/Views/SettingsWindowView.swift
• Main state hub: PingIsland/Services/State/SessionStore.swift
• Session association cache: PingIsland/Services/State/SessionAssociationStore.swift
• Usage/quota snapshots for Claude status-line caches, Claude-family transcript token totals, and Codex rollout logs: PingIsland/Services/Usage/
  • Claude-family transcript token totals are tailed incrementally by ClaudeTranscriptUsageReader, which skips reopening unchanged files, rebuilds only after replacement/truncation, defers half-written trailing records, and carries a streaming FNV-1a digest so AgentUsageStore deduplication stays stable. Keep cumulative totals for the whole transcript, and do not return to whole-file reparsing for ordinary appends.
  • Local agent usage analytics keeps a backward-compatible per-day session token ledger for the statistics panel's latest-three-today total and current-calendar-week top session; preserve legacy agent-usage.json decoding when evolving it
  • AgentUsageTokenTotals keeps the input tiers apart: input is uncached input only, with cacheCreation/cacheRead alongside it. Cache reads are re-reads of context already sent, so they stay out of total, out of billableInput, and are priced at their own rate; folding them back into input overstates usage by orders of magnitude on long sessions. Bump AgentUsageDocument.currentSchemaVersion whenever stored counters change meaning, and migrate by zeroing token counters while leaving session records, tool counts, and the activity heatmap intact.
  • One assistant response spans several transcript lines (one per content block) that each repeat the same message.usage; ClaudeTranscriptUsageAccumulator counts a message.id once per consecutive run. Those repeats are always adjacent, so keep this O(1) rather than introducing a seen-set that would grow with the transcript.
• Native runtime rollout scaffold: PingIsland/Services/Runtime/, PingIsland/Core/FeatureFlags.swift
• Session bridge for UI: PingIsland/Services/Session/SessionMonitor.swift
• Claude-family transcript titles and last-message text: PingIsland/Services/Session/ConversationParser.swift
  • Missing derived Claude transcripts must not fall back to unrelated OpenClaw history. OpenClaw rotation recovery requires an explicit path in that client's sessions directory. Reload store state after awaiting transcript reads so completed or archived sessions are not restored from stale snapshots.
  • Claude Code 2.x stopped writing summary records and now persists the title shown in its own UI as a custom-title record, rewritten on every turn. Take the newest one, keep the legacy summary path as a fallback for older transcripts and other Claude-compatible clients, and only fall back to the first user message when neither exists.
• Notch state and layout: PingIsland/Core/NotchViewModel.swift, PingIsland/UI/Views/NotchView.swift
• App-wide low-power policy for background polling, event monitoring, UI animation tiers, and silent update gating: PingIsland/Core/EnergyGovernor.swift
• Session-aware keep-awake: PingIsland/Core/SessionKeepAwake.swift, PingIsland/Core/KeepAwakePolicy.swift, and behavior/verification. Use one assertion owner and one persisted keepAwakeMode shared by the notch shortcut and settings. Auto-mode power checks must continue while work or grace exists even after low battery releases the assertion; measure the 120-second grace from the last working session stopping, not its last published activity. Always mode bypasses the battery floor and must not run a grace timer.
• User idle protection for temporarily routing blocking approvals/questions back to terminals: PingIsland/Core/UserIdleAutoProtection.swift, PingIsland/Core/Settings.swift, PingIsland/Services/Hooks/BridgeRuntimeConfigWriter.swift
• Detached floating capsule: PingIsland/UI/Window/DetachedIslandWindowController.swift, PingIsland/UI/Views/DetachedIslandPanelView.swift, PingIsland/UI/Views/IslandOpenedContentView.swift
  • Detached pet interactions now keep the pet anchored in place while hover/click previews expand sideways as message-bubble lists; trace both the panel layout and window-anchor math together when changing this flow
  • Expanded content routing is shared with the docked notch through IslandOpenedContentView + IslandExpandedRouteResolver; keep hover/click/notification semantics aligned instead of reintroducing detached-only content priorities
• Global shortcuts and shortcut persistence: PingIsland/Services/Shared/GlobalShortcutManager.swift, PingIsland/Utilities/GlobalShortcut.swift, PingIsland/Core/Settings.swift, PingIsland/UI/Views/SettingsWindowView.swift
• Claude hook ingress: Prototype/Sources/IslandBridge/, PingIsland/Services/Hooks/HookInstaller.swift, PingIsland/Services/Hooks/HookSocketServer.swift
  • PingIslandBridge is the unified Claude/Codex hook entrypoint and is responsible for terminal, tmux, SSH-remote, and IDE terminal context capture before envelopes hit Swift code
  • AskUserQuestion must remain answerable under bypassPermissions and session auto-approval. A question response already allows the tool with updatedInput; never mark its tracked tool as waiting for approval, or the next hook resurrects a redundant approval card.
  • Claude questions intercepted at PreToolUse need the same long hook timeout as PermissionRequest in both local and remote installs. Only recognized question tools own that answer channel; a normal tool's questions argument must never turn it into an Island question.
  • State-only hook delivery is acknowledged by the app after envelope decoding and routing; keep bridge socket writes complete and do not report deliveryOutcome=delivered without a matching app acknowledgement
• Codex ingress: PingIsland/Services/Codex/, PingIsland/UI/Views/CodexSessionView.swift
  • The desktop client is branded ChatGPT; retain the codex-app profile, Codex provider/CLI identifiers, com.openai.codex bundle ID, and codex:// thread links for compatibility. App-server discovery prefers ChatGPT.app, keeps legacy Codex.app as a fallback, and may only launch its bundled codex binary after validating the canonical com.openai.codex app. Other IDEs can embed a binary with the same filename; their app identity must not be applied to every Codex thread. Rollout originator stays host/source metadata and must not replace the canonical client-profile display name.
  • Qoder statistics variables never establish host identity. Desktop evidence beats bare IDE hints; TTY, terminal program/session, and tmux evidence preserve real Codex CLI routing. Routing repairs must replace nullable fields in both persisted associations and current memory instead of merging stale hosts back in. See Codex identity and filtering.
  • Title and ambient suggestion helpers can use real project directories and execute tools. Recognize exact helper sources or dedicated opening prompts in CodexAuxiliaryHookFilter across hooks, app-server snapshots, rollout recovery, and restored UI rows. Never hide ordinary JSON replies or user-created ambient_suggestion_task threads by their output shape.
  • Hook-less fallback parsing for Codex sessions lives in PingIsland/Services/Codex/CodexRolloutParser.swift
  • The fallback parser tails append-only rollout JSONL incrementally, rebuilds after file replacement/truncation, skips pathological oversized records, and retains a bounded recent history. Keep the full content of each retained item, and do not return to whole-file reparsing for ordinary appends.
  • App-server thread/list rows are canonicalized by thread ID before ingestion. Keep active/newer/readable rollout candidates preferred, keep rollout recovery cache keys path-scoped, and discard the old parser cache only when the canonical rollout path genuinely changes.
• Terminal and focus control: PingIsland/Services/Tmux/, PingIsland/Services/Window/, PingIsland/Utilities/TerminalVisibilityDetector.swift
  • Terminal focus flows currently cover iTerm2, Ghostty, Terminal.app, tmux, and IDE-hosted terminals
  • Sessions hosted inside the Claude desktop app are focused by tab, not by app: PingIsland/Services/Session/ClaudeDesktopSessionIndex.swift maps the hook session_id (the CLI session id) to the desktop-side local_… id recorded in ~/Library/Application Support/Claude/{claude-code-sessions,local-agent-mode-sessions}/<org>/<account>/local_*.json, and SessionLauncher opens claude://claude.ai/epitaxy/<local id> (the app's own session route; /code/<id> reloads the page and lands on the last-focused tab since Claude 1.46). The claude://code/continue?session=… entry link is a server-gated surface and cannot be relied on
• Remote SSH forwarding and remote-host management: PingIsland/Services/Remote/
  • Remote hosts can bootstrap a bridge on the SSH target, rewrite remote hooks, install managed plugin-directory integrations such as Hermes under the remote home directory, and attach a bidirectional forwarding channel back into PingIsland
  • The remote bridge forwards recent Codex app-server thread activity from the SSH target's ~/.codex/state_*.sqlite through the existing remote hook-event channel
• Provider/client routing: bridge envelopes are normalized in PingIsland/Services/Hooks/HookSocketServer.swift, stored on SessionState, and launched via PingIsland/Services/Window/SessionLauncher.swift
  • IDE host names mirrored into client_originator and terminal bundle IDs describe the terminal surface, not the agent. Keep them out of runtime client matching; generic Claude hooks must retain a concrete claude-code profile so fresh events can correct stale client associations.
• Client profile registry: installable hook clients and runtime client branding / recognition are centralized in PingIsland/Models/ClientProfile.swift
  • The Kimi desktop app is a separate target (kimi-app-hooks). It runs a vendored kimi-code kernel (@moonshot-ai/agent-core) out of ~/Library/Application Support/kimi-desktop/daimon-share/daimon/runtime/kimi-code/config.toml, so chat and agent turns both speak the same hooks protocol as the CLI. That file is rewritten every time Kimi's daimon runner starts, which drops the managed block; KimiAppHookGuard is started/stopped by SessionMonitor, polls it and reinstalls whenever the block goes missing; failed writes must stay retryable even if the file timestamp is unchanged. Sessions from this target carry --client-kind kimi-app so they resolve to the kimi-app runtime profile and badge as "Kimi App".
• VS Code-compatible IDE focus extension install / URI launch: PingIsland/Services/Window/IDEExtensionInstaller.swift, PingIsland/Services/Window/TerminalSessionFocuser.swift
• Session list UI: PingIsland/UI/Views/SessionListView.swift
• Client mascot system: PingIsland/UI/Components/MascotView.swift, PingIsland/UI/Views/MascotSettingsView.swift
• App updates and release notes: PingIsland/Services/Update/, PingIsland/UI/Views/ReleaseNotesWindowView.swift, PingIsland/UI/Window/ReleaseNotesWindowController.swift
• Sparkle build configuration: Config/App.xcconfig, Config/LocalSecrets.xcconfig, docs/sparkle-release.md
• Mac App Store distribution lane: PingIslandAppStore target / scheme, PingIsland/Info-AppStore.plist, PingIsland/Resources/PingIsland-AppStore.entitlements, Config/AppStore.xcconfig, scripts/build-app-store.sh, and docs/mac-app-store-submission.md