[feat] Tiered AI configuration — Claude Code (claude -p) as primary substrate

[Sph3ricalPeter]

Priority: P1 within the AI layer — underpins all AI-using features
Effort: ~3–5 days
AI required: N/A (this is the configuration layer)

Decision (2026-06-20)

• Primary AI substrate = the user's own Claude Code, invoked as a claude -p subprocess ("bring your own Claude Code"). Local (Ollama) and BYOK API keys are fallback tiers, not the main path.
• The AI layer is the LAST stage of the v2.0.0 pivot — it lands as quiet polish on top of the no-AI spine ([feat] Linear API integration foundation #45, [feat] Issue context panel in commit/diff UI #46, [feat] Commit↔issue traceability — forward view (issue → commits) #48, [feat] Risk-flagging review pane — rules layer #52). Never a dependency: the product is fully useful with AI set to Off.

Why claude -p first

• Capability — far stronger than a 7B local model for the checks that matter, especially "does this diff satisfy the linked issue's acceptance criteria?" ([feat] Risk-flagging review pane — AI layer (claude -p primary) #53).
• TOS-safe — prefetch invokes the first-party Claude Code CLI the user already logged into; it is NOT a third-party app authenticating via subscription OAuth (which the Feb 2026 TOS restricts). Subprocess = the same model as our git CLI mutations.
• Zero credential surface — no API keys, no OAuth, no token refresh, no model downloads. Billing + auth are entirely the user's existing Claude Code setup.
• Billing reality (2026-06-20, volatile) — claude -p currently draws on the user's normal Pro/Max subscription limits. Anthropic announced (May 13) then paused on the day (June 15) a move of claude -p/Agent SDK usage to a separate metered credit pool ($20 Pro / $100 Max 5x / $200 Max 20x at API rates), and intends to meter agentic usage eventually. Design rule: AI calls stay bounded + few (reviewer-assist, a handful per review — never an agent loop) so a future metering change stays cheap.

Tiers (single config surface, per-feature routing)

Global tier + per-feature override. Ordered by preference:

1. Claude Code (claude -p) — default tier for the AI layer. Detect claude on PATH (like we detect git-lfs). Invoke claude -p --output-format json [--bare] [--model <id>] [--permission-mode ...] as a subprocess; parse the structured JSON result. No key handling.
2. Local — Ollama (default), llama.cpp, LM Studio (OpenAI-compatible endpoint). For users without Claude Code / who want fully offline.
3. BYOK Cloud — Anthropic, OpenAI, OpenAI-compatible (OpenRouter, Together, …). API key in OS keychain.
4. Off — default until the AI layer ships; no surprise calls.

Scope

• Global tier selector + per-feature override (each AI feature picks its own tier or inherits the global).
• Claude Code tier: binary detection + version/health check; clear "Claude Code not found — install from … or pick another tier" empty state; knobs for model override, timeout, default permission-mode.
• Local / BYOK tiers: provider + model selector, endpoint config, key in keychain, connection-test button.
• Rough cost/usage hint per tier (Claude Code: "uses your Claude subscription / Agent SDK allowance"; BYOK: $/operation estimate).

Acceptance criteria

• Four tiers selectable globally (Claude Code / Local / BYOK / Off); per-feature override works
• Claude Code tier detects the claude binary, reports version, degrades gracefully when absent
• claude -p invoked as a subprocess with --output-format json; result parsed into a typed struct; never blocks the UI
• BYOK keys in keychain, never plaintext; connection test surfaces clear errors
• Default config is Off — no surprise calls or costs
• AI calls are bounded (reviewer-assist only) — no unbounded / agent-loop usage
• Docs: BYO Claude Code setup + Ollama setup