storkit/.story_kit/spikes/spike-1-claude-code-integration.md

# Spike: Claude Code Integration via PTY + CLI

**Question:** Can we run Claude Code programmatically from our Rust backend while using Max subscription billing instead of per-token API billing?

**Hypothesis:** Spawning `claude -p` inside a pseudo-terminal (PTY) will make `isatty()` return true, causing Claude Code to use Max subscription billing while giving us structured JSON output.

**Timebox:** 2 hours

**Result: HYPOTHESIS CONFIRMED**

---

## Proof

Spawning `claude -p "hi" --output-format stream-json --verbose` inside a PTY from Rust (`portable-pty` crate) produces:

```json
{"type":"system","subtype":"init","apiKeySource":"none","model":"claude-opus-4-6",...}
{"type":"rate_limit_event","rate_limit_info":{"status":"allowed","rateLimitType":"five_hour",...}}
{"type":"assistant","message":{"model":"claude-opus-4-6","content":[{"type":"text","text":"Hi! How can I help you today?"}],...}}
{"type":"result","subtype":"success","total_cost_usd":0.0102,...}
```

Key evidence:
- **`apiKeySource: "none"`** — not using an API key
- **`rateLimitType: "five_hour"`** — Max subscription rate limiting (not per-token)
- **`model: "claude-opus-4-6"`** — Opus on Max plan
- Clean NDJSON output, parseable from Rust
- Response streamed to browser UI via WebSocket

## Architecture (Proven)

```
Browser UI → WebSocket → Rust Backend → PTY → claude -p --output-format stream-json
                                         ↑
                                    isatty() = true → Max subscription billing
```

## What Works

1. `portable-pty` crate spawns Claude Code in a PTY from Rust
2. `-p` flag gives single-shot non-interactive mode (no TUI)
3. `--output-format stream-json` gives clean NDJSON (no ANSI escapes)
4. PTY makes `isatty()` return true → Max billing
5. NDJSON events parsed and streamed to frontend via WebSocket
6. Session IDs returned for potential multi-turn via `--resume`

## Event Types from stream-json

| Type | Purpose | Key Fields |
|------|---------|------------|
| `system` | Init event | `session_id`, `model`, `apiKeySource`, `tools`, `agents` |
| `rate_limit_event` | Billing info | `status`, `rateLimitType` |
| `assistant` | Claude's response | `message.content[].text` |
| `result` | Final summary | `total_cost_usd`, `usage`, `duration_ms` |
| `stream_event` | Token deltas (with `--include-partial-messages`) | `event.delta.text` |

## Multi-Agent Concurrency (Proven)

Created an `AgentPool` with REST API (`POST /api/agents`, `POST /api/agents/:name/message`, `GET /api/agents`) and tested 2 concurrent coding agents:

**Test:** Created `coder-1` (frontend role) and `coder-2` (backend role), sent both messages simultaneously.

```
coder-1: Listed 5 React components in 5s (session: ca3e13fc-...)
coder-2: Listed 30 Rust source files in 8s (session: 8a815cf0-...)
Both: apiKeySource: "none", rateLimitType: "five_hour" (Max billing)
```

**Session resumption confirmed:** Sent coder-1 a follow-up "How many components did you just list?" — it answered "5" using `--resume <session_id>`.

**What this proves:**
- Multiple PTY sessions run concurrently without conflict
- Each gets Max subscription billing independently
- `--resume` gives agents multi-turn conversation memory
- Supervisor pattern works: coordinator reads agent responses, sends coordinated tasks
- Inter-agent communication possible via supervisor relay

**Architecture for multi-agent orchestration:**
- Spawn N PTY sessions, each with `claude -p` pointed at a different worktree
- Rust backend coordinates work between agents
- Different `--model` per agent (Opus for supervisor, Sonnet/Haiku for workers)
- `--allowedTools` to restrict what each agent can do
- `--max-turns` and `--max-budget-usd` for safety limits

## Key Flags for Programmatic Use

```bash
claude -p "prompt"                    # Single-shot mode
  --output-format stream-json         # NDJSON output
  --verbose                           # Include all events
  --include-partial-messages          # Token-by-token streaming
  --model sonnet                      # Model selection
  --allowedTools "Read,Edit,Bash"     # Tool permissions
  --permission-mode bypassPermissions # No approval prompts
  --resume <session_id>               # Continue conversation
  --max-turns 10                      # Safety limit
  --max-budget-usd 5.00              # Cost cap
  --append-system-prompt "..."        # Custom instructions
  --cwd /path/to/worktree            # Working directory
```

## Agent SDK Comparison

The Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`) is a richer TypeScript API with hooks, subagents, and MCP integration — but it **requires an API key** (per-token billing). The PTY approach is the only way to get Max subscription billing programmatically.

| Factor | PTY + CLI | Agent SDK |
|--------|-----------|-----------|
| Billing | Max subscription | API key (per-token) |
| Language | Any (subprocess) | TypeScript/Python |
| Streaming | NDJSON parsing | Native async iterators |
| Hooks | Not available | Callback functions |
| Subagents | Multiple processes | In-process `agents` option |
| Sessions | `--resume` flag | In-memory |
| Complexity | Low | Medium (needs Node.js) |

## Caveats

- Cost reported in `total_cost_usd` is informational, not actual billing
- Concurrent PTY sessions may hit Max subscription rate limits
- Each `-p` invocation is a fresh process (startup overhead ~2-3s)
- PTY dependency (`portable-pty`) adds ~15 crates

## Next Steps

1. **Story:** Add `--include-partial-messages` for real-time token streaming to browser
2. **Story:** Production multi-agent orchestration with worktree isolation per agent
3. **Story:** Streaming HTTP responses (SSE) instead of blocking request until agent completes
4. **Consider:** Whether Rust backend should become a thin orchestration layer over Claude Code rather than reimplementing agent capabilities