Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.
Rust acpagent-client-protocolai-agentsai-assistantclaudeclaude-codecodexcoding-agentscursorgeminigemini-cligrok-bot-alternativeiosiphonelinuxmacosmcpopen-sourcerustself-hosted
fix: sandbox, path encoding, computed fields, 4KB limit
libokai36388d911bea
diff --git a/docs/superpowers/specs/2026-03-17-codepulse-design.md b/docs/superpowers/specs/2026-03-17-codepulse-design.mdindex a7886850..594c287f 100644--- a/docs/superpowers/specs/2026-03-17-codepulse-design.md+++ b/docs/superpowers/specs/2026-03-17-codepulse-design.md@@ -28,29 +28,47 @@ CodePulse is a macOS menu bar app that monitors Claude Code sessions in real-timV1 uses FSEvents file watching for zero-config operation. V2 adds optional Claude Code hooks for lower-latency updates.+### Filesystem Access++The macOS app must read files under `~/.claude/`, which is outside the App Sandbox container. Options:++1. **Disable App Sandbox** (recommended for V1) — common for developer tools. Requires entitlement exception justification for App Store review.+2. **Security-scoped bookmark** — prompt user to grant access to `~/.claude/` via Open Panel on first launch, persist the bookmark. More complex but sandbox-compatible.++V1 will disable App Sandbox. This is standard practice for developer tools (e.g., Command, Tower, iTerm2).+### Data Sources (Claude Code files on macOS)+Path encoding: `~/.claude/projects/<mangled-cwd>/` where `<mangled-cwd>` is the session's `cwd` with all `/` replaced by `-` (e.g., `/Users/foo/myproject` → `-Users-foo-myproject`).+| File | Path | Data ||------|------|------|| Active sessions | `~/.claude/sessions/<PID>.json` | pid, sessionId, cwd, startedAt |-| Todo/task progress | `~/.claude/todos/<sessionId>-agent-*.json` | [{content, status, activeForm}] |-| Session index | `~/.claude/projects/<project>/sessions-index.json` | summary, firstPrompt, messageCount, gitBranch |-| Conversation log | `~/.claude/projects/<project>/<sessionId>.jsonl` | model, context%, cost (read tail only) |+| Tasks (primary) | `~/.claude/tasks/<sessionId>/` | Per-task files with id, subject, description, status, activeForm, blocks, blockedBy |+| Todos (fallback) | `~/.claude/todos/<sessionId>-agent-*.json` | [{content, status, activeForm}] — may be empty |+| Session index | `~/.claude/projects/<mangled-cwd>/sessions-index.json` | summary, firstPrompt, messageCount, gitBranch |+| Conversation log | `~/.claude/projects/<mangled-cwd>/<sessionId>.jsonl` | message.model, usage.input_tokens/output_tokens (read tail only) |++**Computed fields (not directly available in files):**++- **context%**: Compute from `usage.input_tokens + usage.cache_read_input_tokens` in the latest assistant message, divided by model context window size (e.g., 200K for Opus, 200K for Sonnet). This is an estimate.+- **cost (USD)**: Compute by accumulating token usage across assistant messages × per-model pricing. Pricing is hardcoded and must be updated when Anthropic changes rates. Consider making this configurable or fetching from a bundled config.### Data Flow```Claude Code writes files to ~/.claude/- → macOS app watches via FSEvents (debounce 2s)- → Parses todos JSON + session JSON + JSONL tail- → Aggregates into SessionState- → Writes to CloudKit Private DB (debounce 2s, only on change)- → CKSubscription pushes to iPhone- → iPhone updates Live Activity- → Watch mirrors automatically+ → macOS app watches via FSEvents (debounce 1s)+ → Parses tasks/ + session JSON + JSONL tail+ → Computes context% and cost from token usage+ → Aggregates into SessionState+ → Writes to CloudKit Private DB (debounce 2s, only on change)+ → CKSubscription pushes to iPhone+ → iPhone updates Live Activity+ → Watch mirrors automatically```-Total latency: ~3-5 seconds from Claude Code state change to iPhone display.+Total latency: ~5-10 seconds from Claude Code state change to iPhone display. CKSubscription delivery is best-effort and may be delayed by iOS, especially in low-power mode. When a Live Activity is active, the iOS app also polls CloudKit every 30 seconds as a fallback to ensure updates are not missed.### CloudKit Schema@@ -61,15 +79,16 @@ Record Type: SessionState├── sessionId (String, indexed)├── projectName (String)├── gitBranch (String)-├── status (String: working/idle/needsInput/completed)+├── status (String: working/idle/needsInput/error/completed)├── model (String: Opus/Sonnet/Haiku)├── summary (String: from sessions-index.json)├── currentTask (String: activeForm of in_progress task)-├── tasks (Data: JSON encoded [TaskItem])-├── contextPct (Int)-├── costUSD (Double)-├── durationSec (Int)-├── deviceId (String)+├── tasks (Data: JSON encoded [TaskItem], truncated to last 10 tasks for 4KB limit)+├── contextPct (Int, computed)+├── costUSD (Double, computed)+├── startedAt (Date)+├── durationSec (Int, computed from startedAt)+├── deviceId (String, identifies which Mac — supports multi-Mac setups)└── updatedAt (Date)```@@ -100,14 +119,15 @@ CodePulse/│ ├── Services/│ │ ├── CloudKitReceiver.swift ← CKSubscription listener│ │ └── LiveActivityManager.swift ← Activity lifecycle-│ ├── Views/-│ │ ├── SessionListView.swift-│ │ ├── SessionDetailView.swift-│ │ └── OnboardingView.swift-│ └── CodePulse-LiveActivity/ ← Widget Extension target-│ ├── CodePulseLiveActivity.swift-│ ├── LockScreenView.swift-│ └── DynamicIslandView.swift+│ └── Views/+│ ├── SessionListView.swift+│ ├── SessionDetailView.swift+│ └── OnboardingView.swift+│+├── CodePulseLiveActivity/ ← Widget Extension target (separate Xcode target)+│ ├── CodePulseLiveActivity.swift+│ ├── LockScreenView.swift+│ └── DynamicIslandView.swift│└── CodePulseShared/ ← Shared framework├── Models/@@ -133,7 +153,7 @@ No watchOS target needed — watchOS 11+ mirrors iPhone Live Activities automati### Session List (Command-style)Each row shows:-- Status dot (animated): working (green), idle (cyan), needs input (orange), error (red), completed (gray)+- Status dot (animated): working (green), idle (cyan), needs input (orange), error (red pulse), completed (gray)- 5-word summary (from sessions-index.json summary or firstPrompt)- Claude tag badge- Relative time ("now", "2m ago", "1h ago")@@ -154,12 +174,20 @@ Each row shows:### Status Detection Logic```-PID not alive → completed-Has in_progress task → working-Last message is assistant + >30s idle → needsInput-Otherwise → idle+PID not alive → completed+JSONL last entry has tool error/exit≠0 → error+Has in_progress task → working+JSONL growing (new bytes in last 10s) → working+No JSONL growth for >30s → needsInput (likely waiting for user)+Otherwise → idle```+Note: "needsInput" is a best-effort heuristic. Claude Code may pause for various reasons (thinking, permission prompt, rate limit). This is acceptable for V1 — hooks in V2 will provide precise state.++### First Launch Behavior++On first launch, the macOS app scans all existing `~/.claude/sessions/*.json` files, checks which PIDs are still alive, and begins monitoring those sessions. Sessions started before CodePulse was installed are picked up immediately.+### Performance Targets- Memory: < 30MB@@ -214,6 +242,10 @@ struct CodePulseAttributes: ActivityAttributes {}```+#### Content Size Limit++Apple enforces a 4KB limit on `ActivityAttributes.ContentState` updates. The `tasks` array is truncated to the 10 most recent tasks, with task content capped at 50 characters each. If more detail is needed, the user taps to open the full app.+### Auto-Switch Logic1. Default: track the most recently started session@@ -231,7 +263,7 @@ struct CodePulseAttributes: ActivityAttributes {- `SessionState` — core data model shared between macOS and iOS- `TaskItem` — individual task with content, status, activeForm-- `SessionStatus` — enum: working, idle, needsInput, completed (with color/icon helpers)+- `SessionStatus` — enum: working, idle, needsInput, error, completed (with color/icon helpers)### CloudKit@@ -245,6 +277,13 @@ struct CodePulseAttributes: ActivityAttributes {- Cleanup: completed sessions auto-delete after 24 hours, max 20 records- Offline: Mac queues locally, iPhone shows last known state + "offline" label+## CloudKit Configuration++- Container identifier: `iCloud.com.pokai.CodePulse`+- Must be created in Apple Developer portal+- Both macOS and iOS targets include the CloudKit entitlement+- Bundle IDs: `com.pokai.CodePulse` (macOS), `com.pokai.CodePulse.ios` (iOS), `com.pokai.CodePulse.ios.LiveActivity` (widget extension)+## Privacy- All data in CloudKit Private Database (user's own iCloud)