ping-island AGENTS.md

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
  • 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
• 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
  • 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
  • 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
• 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
• Client profile registry: installable hook clients and runtime client branding / recognition are centralized in PingIsland/Models/ClientProfile.swift
• 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