Architecture: Direct API vs Claude CLI

Details

Raw Data

{
  "id": "67e9b608-5196-4721-9f0e-1865cd3d6142",
  "type": "general",
  "status": "completed",
  "title": "Architecture: Direct API vs Claude CLI",
  "description": "Analysis of moving to pure Claude API with self-managed context and embeddings",
  "context": {
    "output": "<div style=\"background:#1e1e1e;color:#e0e0e0;padding:20px;border-radius:8px;font-family:sans-serif;\"><h2 style=\"color:#fff;margin:0 0 16px 0;\">Direct API + Self-Managed Context</h2><div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\"><h4 style=\"margin:0 0 12px 0;color:#98c379;\">What You'd Gain:</h4><ul style=\"margin:0;padding-left:20px;line-height:1.8;\"><li><strong>Full control</strong> - No CLI spin-up time (~6s saved per turn)</li><li><strong>Custom context</strong> - Load exactly what's needed per request</li><li><strong>Embeddings</strong> - Semantic search for relevant code/docs</li><li><strong>Cost optimization</strong> - Only send what matters, use cache strategically</li><li><strong>Multi-model</strong> - Seamless Claude/GPT/Gemini switching</li><li><strong>Streaming</strong> - Direct SSE from API, no CLI stdout parsing</li></ul></div><div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\"><h4 style=\"margin:0 0 12px 0;color:#e06c75;\">What You'd Lose (from Claude CLI):</h4><ul style=\"margin:0;padding-left:20px;line-height:1.8;\"><li><strong>Tool implementations</strong> - Read, Write, Edit, Bash, Grep, Glob all built-in</li><li><strong>Auto-compacting</strong> - CLI handles context overflow automatically</li><li><strong>Session resumption</strong> - Built-in transcript/state management</li><li><strong>Permission system</strong> - CLI has sophisticated tool approval flow</li><li><strong>CLAUDE.md loading</strong> - Automatic project context injection</li></ul></div><div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\"><h4 style=\"margin:0 0 12px 0;color:#61afef;\">What You'd Need to Build:</h4><table style=\"width:100%;border-collapse:collapse;font-size:13px;\"><tr style=\"border-bottom:1px solid #444;\"><td style=\"padding:8px 0;color:#e5c07b;\">Tool executor</td><td style=\"color:#9ca3af;\">Parse tool_use blocks, execute, return tool_result</td></tr><tr style=\"border-bottom:1px solid #444;\"><td style=\"padding:8px 0;color:#e5c07b;\">Context manager</td><td style=\"color:#9ca3af;\">Track token usage, auto-summarize when needed</td></tr><tr style=\"border-bottom:1px solid #444;\"><td style=\"padding:8px 0;color:#e5c07b;\">Embedding store</td><td style=\"color:#9ca3af;\">Vector DB for semantic code search (Voyage AI?)</td></tr><tr style=\"border-bottom:1px solid #444;\"><td style=\"padding:8px 0;color:#e5c07b;\">Session state</td><td style=\"color:#9ca3af;\">Persist conversations, handle resumption</td></tr><tr><td style=\"padding:8px 0;color:#e5c07b;\">Safety layer</td><td style=\"color:#9ca3af;\">Tool permissions, dangerous command blocking</td></tr></table></div><div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\"><h4 style=\"margin:0 0 12px 0;color:#ce93d8;\">Hybrid Approach (Recommended):</h4><p style=\"margin:0 0 12px 0;color:#9ca3af;\">Use <strong>both</strong> based on task complexity:</p><table style=\"width:100%;border-collapse:collapse;font-size:13px;\"><tr style=\"border-bottom:1px solid #444;\"><td style=\"padding:8px 0;color:#98c379;\">Quick Turn</td><td style=\"color:#9ca3af;\">Direct API (already done!) - fast, stateless</td></tr><tr style=\"border-bottom:1px solid #444;\"><td style=\"padding:8px 0;color:#61afef;\">Full Sessions</td><td style=\"color:#9ca3af;\">CLI - tool access, context management, safety</td></tr><tr><td style=\"padding:8px 0;color:#ce93d8;\">Future: kontext</td><td style=\"color:#9ca3af;\">Embeddings layer that feeds BOTH paths</td></tr></table></div><div style=\"background:#1a2332;border:1px solid #61afef;padding:16px;border-radius:6px;\"><h4 style=\"margin:0 0 8px 0;color:#61afef;\">💡 Key Insight:</h4><p style=\"margin:0;color:#9ca3af;\">The Claude CLI is essentially a <strong>sophisticated tool executor</strong> with ~2 years of edge case handling. Going pure API means rebuilding that. The <strong>smart play</strong> is: API for simple/fast, CLI for complex/tools, embeddings (kontext) as the intelligence layer that decides what context to inject into either path.</p></div></div>",
    "requestedAt": "2026-01-05T03:48:00Z",
    "requestId": "86f9ec91-0a70-48d6-8f61-61417cc43c17",
    "choices": [
      {
        "label": "Explore kontext design",
        "value": "Let's design the kontext embeddings layer that could feed both API and CLI paths"
      },
      {
        "label": "Hybrid architecture doc",
        "value": "Create a detailed architecture document for the hybrid API + CLI approach"
      },
      {
        "label": "Stay with current",
        "value": "The current hybrid approach (Quick Turn API + Full CLI) is working well"
      }
    ]
  },
  "createdBy": "claude",
  "createdAt": "2026-01-05T04:03:19.860Z",
  "updatedAt": "2026-01-05T04:03:20.050Z",
  "requestId": "86f9ec91-0a70-48d6-8f61-61417cc43c17",
  "scope": "vibetools",
  "tags": [
    "architecture",
    "api",
    "strategy"
  ],
  "targetUser": "claude"
}