Skip to content

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.

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.md
index 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-tim
V1 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 Logic
1. 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)