8739805f99
Some checks failed
Auto-update PR branches / Update open PR branches (push) Has been cancelled
CI / Frontend Static Quality Checks (push) Has been cancelled
CI / Frontend Tests & Coverage (push) Has been cancelled
CI / Rust Tests & Quality Checks (push) Has been cancelled
CI / Linux build verification (push) Has been cancelled
Release (Alpha) / Compute alpha version (push) Has been cancelled
Release (Alpha) / Build release artifacts (push) Has been cancelled
Release (Alpha) / GitHub Release (alpha) (push) Has been cancelled
Release (Alpha) / Update docs and release pages (push) Has been cancelled
Deploy docs / Build VitePress site (push) Has been cancelled
Deploy docs / Deploy to GitHub Pages (push) Has been cancelled
2.0 KiB
2.0 KiB
type, id, title, status, date
| type | id | title | status | date |
|---|---|---|---|---|
| ADR | 0012 | Claude CLI subprocess for AI agent (replacing direct API) | active | 2026-03-01 |
Context
The AI agent panel initially called the Anthropic API directly from Rust, managing tool calling loops manually. This required implementing tool execution, conversation state, and streaming — all complex to maintain. Claude CLI (claude binary) handles all of this natively, including MCP tool integration, conversation history, and streaming NDJSON output.
Decision
The AI agent panel spawns Claude CLI as a subprocess via claude_cli.rs, passing messages with --output-format stream-json and vault MCP config via --mcp-config. The frontend parses the NDJSON event stream (Init, TextDelta, ThinkingDelta, ToolStart, ToolDone, Result, Done) for real-time display.
Options considered
- Option A (chosen): Claude CLI subprocess with NDJSON streaming — built-in tool calling, MCP integration, conversation management, no API key needed (CLI handles auth). Downside: requires Claude CLI installed, subprocess management complexity.
- Option B: Direct Anthropic API with manual tool loop — full control, no external dependency. Downside: must implement tool calling, retries, conversation state, MCP tool bridging.
- Option C: Use Anthropic Agent SDK from Rust — structured agent framework. Downside: SDK is Python/TypeScript, no Rust support.
Consequences
- The AI agent gets full tool access (MCP vault tools + shell access) without custom tool-calling code.
claude_cli.rsmanages subprocess lifecycle: spawn, stream events, kill on cancel.- The frontend (
useAiAgenthook) processes NDJSON events for reasoning blocks, tool action cards, and response display. - File operation detection (from Write/Edit tool inputs) triggers automatic vault reload.
- The simpler AI Chat panel still uses the Anthropic API directly for lightweight, no-tools conversations.
- Re-evaluation trigger: if Anthropic releases a Rust Agent SDK or if Claude CLI streaming format changes significantly.