Gap Analysis: Provider CLI Installation & Onboarding

Details

Raw Data

{
  "id": "c66cf24f-d0b8-4098-b9b6-d022cf810f05",
  "type": "general",
  "status": "completed",
  "title": "Gap Analysis: Provider CLI Installation & Onboarding",
  "description": "The design doc doesn't cover how CLI providers are installed or onboarded",
  "context": {
    "requestId": "b53ce820-86a5-4636-9b7a-bde2e78a9e31",
    "output": "<div style=\"background:#1e1e1e;color:#e0e0e0;padding:20px;border-radius:8px;font-family:'Segoe UI','Helvetica',sans-serif;\">\n<h2 style=\"color:#fff;margin:0 0 16px 0;\">Gap Analysis: Provider CLI Installation</h2>\n<p style=\"color:#e5c07b;margin:0 0 16px 0;\">You're right - the current document does NOT cover CLI provider installation or onboarding.</p>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:20px;border-left:3px solid #e06c75;\">\n<h3 style=\"color:#e06c75;margin:0 0 12px 0;\">What's Missing</h3>\n<ul style=\"color:#e0e0e0;margin:0;padding-left:20px;line-height:1.8;\">\n<li><strong>CLI Provider Installation:</strong> How does Claude CLI, Codex CLI get installed?</li>\n<li><strong>Bundling Strategy:</strong> Bundle with gvAgent or separate install?</li>\n<li><strong>Version Management:</strong> How to update CLIs independently?</li>\n<li><strong>Provider Onboarding:</strong> First-run wizard for API keys, auth</li>\n<li><strong>Health Checks:</strong> Verify provider is working before use</li>\n<li><strong>Fallback Behavior:</strong> What if CLI isn't installed?</li>\n</ul>\n</div>\n\n<h3 style=\"color:#fff;margin:20px 0 12px 0;\">Current State in Document</h3>\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<p style=\"color:#7f848e;margin:0 0 8px 0;\">The document only mentions:</p>\n<pre style=\"background:#1a1a1a;padding:12px;border-radius:4px;color:#98c379;font-size:0.85rem;overflow-x:auto;margin:0;\">claude-cli:\n  binary: \"claude\"              # Path or command name\n  model: \"claude-sonnet-4-20250514\"</pre>\n<p style=\"color:#9ca3af;margin:8px 0 0 0;\">It assumes the CLI is already installed and in PATH. No installation guidance.</p>\n</div>\n\n<h3 style=\"color:#fff;margin:20px 0 12px 0;\">Proposed Section: Provider Installation & Onboarding</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;border-left:3px solid #98c379;\">\n<h4 style=\"color:#98c379;margin:0 0 12px 0;\">Option A: Separate Installation (Recommended)</h4>\n<p style=\"color:#e0e0e0;margin:0 0 12px 0;\">gvAgent does NOT bundle CLI providers. Users install them separately.</p>\n<table style=\"width:100%;color:#e0e0e0;font-size:0.85rem;border-collapse:collapse;\">\n<tr style=\"border-bottom:1px solid #3d3d3d;\"><th style=\"text-align:left;padding:8px 0;color:#7f848e;\">Provider</th><th style=\"text-align:left;padding:8px 0;color:#7f848e;\">Installation</th></tr>\n<tr style=\"border-bottom:1px solid #3d3d3d;\"><td style=\"padding:6px 0;\">Claude CLI</td><td style=\"padding:6px 0;\"><code>npm install -g @anthropic-ai/claude-code</code></td></tr>\n<tr style=\"border-bottom:1px solid #3d3d3d;\"><td style=\"padding:6px 0;\">Codex CLI</td><td style=\"padding:6px 0;\"><code>npm install -g @openai/codex</code></td></tr>\n<tr style=\"border-bottom:1px solid #3d3d3d;\"><td style=\"padding:6px 0;\">Ollama</td><td style=\"padding:6px 0;\"><code>curl -fsSL https://ollama.com/install.sh | sh</code></td></tr>\n<tr><td style=\"padding:6px 0;\">API-only</td><td style=\"padding:6px 0;\">No install needed (just API key)</td></tr>\n</table>\n<p style=\"color:#9ca3af;margin:12px 0 0 0;\"><strong>Pros:</strong> Simpler gvAgent, no licensing issues, users control versions<br/>\n<strong>Cons:</strong> Extra setup step, potential \"CLI not found\" errors</p>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;border-left:3px solid #61afef;\">\n<h4 style=\"color:#61afef;margin:0 0 12px 0;\">Option B: Bundled Installation</h4>\n<p style=\"color:#e0e0e0;margin:0 0 12px 0;\">gvAgent includes CLI providers as embedded binaries or downloads on first use.</p>\n<pre style=\"background:#1a1a1a;padding:12px;border-radius:4px;color:#61afef;font-size:0.85rem;overflow-x:auto;margin:0;\">gvAgent install claude-cli\ngvAgent install codex-cli\ngvAgent providers list</pre>\n<p style=\"color:#9ca3af;margin:12px 0 0 0;\"><strong>Pros:</strong> Zero friction, guaranteed compatibility, offline install<br/>\n<strong>Cons:</strong> Larger binary, licensing complexity, version coupling</p>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;border-left:3px solid #c678dd;\">\n<h4 style=\"color:#c678dd;margin:0 0 12px 0;\">Option C: Hybrid (Download on Demand)</h4>\n<p style=\"color:#e0e0e0;margin:0 0 12px 0;\">gvAgent downloads and manages CLI providers into its own directory.</p>\n<pre style=\"background:#1a1a1a;padding:12px;border-radius:4px;color:#c678dd;font-size:0.85rem;overflow-x:auto;margin:0;\">~/.local/share/gvagent/\n├── providers/\n│   ├── claude-cli/\n│   │   ├── v2.1.0/\n│   │   └── current -> v2.1.0/\n│   └── codex-cli/\n│       └── v1.0.0/</pre>\n<p style=\"color:#9ca3af;margin:12px 0 0 0;\"><strong>Pros:</strong> Best of both - managed but not bundled<br/>\n<strong>Cons:</strong> Download on first use, needs network</p>\n</div>\n\n<h3 style=\"color:#fff;margin:20px 0 12px 0;\">Proposed: Onboarding Flow</h3>\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<pre style=\"background:#1a1a1a;padding:12px;border-radius:4px;color:#e0e0e0;font-size:0.85rem;overflow-x:auto;margin:0;line-height:1.6;\">\n<span style=\"color:#98c379;\">$ gvagent init</span>\n\n<span style=\"color:#61afef;\">greatVibeAgent Setup</span>\n\n<span style=\"color:#e5c07b;\">Step 1: Hub Connection</span>\n  Hub URL: <span style=\"color:#98c379;\">wss://greatvibe.ai/agent</span>\n  ✔ Connected successfully\n\n<span style=\"color:#e5c07b;\">Step 2: Provider Setup</span>\n  Which providers do you want to use?\n  <span style=\"color:#98c379;\">●</span> Claude CLI (full tool access) - <span style=\"color:#7f848e;\">requires npm</span>\n  <span style=\"color:#98c379;\">●</span> Claude API (chat only)\n  <span style=\"color:#9ca3af;\">○</span> OpenAI API\n  <span style=\"color:#9ca3af;\">○</span> Local LLM (Ollama)\n\n<span style=\"color:#e5c07b;\">Step 3: Claude CLI Setup</span>\n  <span style=\"color:#7f848e;\">➜ Checking for Claude CLI...</span>\n  <span style=\"color:#e06c75;\">✗ Claude CLI not found</span>\n\n  Options:\n  1. Install now: <span style=\"color:#98c379;\">npm install -g @anthropic-ai/claude-code</span>\n  2. I'll install manually later\n  3. Skip this provider\n\n  <span style=\"color:#7f848e;\">➜ Installing Claude CLI...</span>\n  <span style=\"color:#98c379;\">✔ Claude CLI v2.1.0 installed</span>\n\n<span style=\"color:#e5c07b;\">Step 4: API Keys</span>\n  Claude API Key: <span style=\"color:#7f848e;\">sk-ant-***************</span>\n  <span style=\"color:#98c379;\">✔ API key validated</span>\n\n<span style=\"color:#e5c07b;\">Step 5: Workspace</span>\n  Working directory: <span style=\"color:#98c379;\">/home/user/projects</span>\n  ✔ Guardrails configured\n\n<span style=\"color:#98c379;\">✔ Setup complete!</span>\nRun <span style=\"color:#61afef;\">gvagent start</span> to connect to the hub.\n</pre>\n</div>\n\n<h3 style=\"color:#fff;margin:20px 0 12px 0;\">Proposed: Provider Health Checks</h3>\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<pre style=\"background:#1a1a1a;padding:12px;border-radius:4px;color:#e0e0e0;font-size:0.85rem;overflow-x:auto;margin:0;\">\n<span style=\"color:#98c379;\">$ gvagent providers status</span>\n\n<span style=\"color:#61afef;\">Provider Status</span>\n\n<span style=\"color:#98c379;\">●</span> claude-cli    v2.1.0   <span style=\"color:#98c379;\">healthy</span>   /usr/local/bin/claude\n<span style=\"color:#98c379;\">●</span> claude-api    -        <span style=\"color:#98c379;\">healthy</span>   API key valid\n<span style=\"color:#e5c07b;\">●</span> openai        -        <span style=\"color:#e5c07b;\">degraded</span>  Rate limited\n<span style=\"color:#e06c75;\">●</span> codex-cli     -        <span style=\"color:#e06c75;\">missing</span>   Not installed\n<span style=\"color:#7f848e;\">○</span> ollama        -        <span style=\"color:#7f848e;\">disabled</span>  Not configured\n</pre>\n</div>\n\n<h3 style=\"color:#fff;margin:20px 0 12px 0;\">Recommendation</h3>\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;border-left:3px solid #e5c07b;\">\n<p style=\"color:#e0e0e0;margin:0;\"><strong>Option C (Hybrid)</strong> provides the best UX:</p>\n<ul style=\"color:#9ca3af;margin:8px 0 0 0;padding-left:20px;line-height:1.8;\">\n<li>gvAgent manages provider installation in its own directory</li>\n<li>No system-wide npm/package manager dependency</li>\n<li>Version pinning per-provider</li>\n<li>Graceful fallback if download fails</li>\n<li>Still allows manual installation to override</li>\n</ul>\n<p style=\"color:#e5c07b;margin:12px 0 0 0;\">This should be added as <strong>Section 20: Provider Installation & Onboarding</strong></p>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-top:16px;\">\n<h4 style=\"margin:0 0 8px 0;color:#fff;\">What's Next?</h4>\n<p style=\"color:#9ca3af;margin:0;\">Choose how to proceed:</p>\n</div>\n</div>",
    "choices": [
      {
        "label": "Add Section 20",
        "value": "Add Section 20: Provider Installation & Onboarding to the gvAgentDesign.md document with the hybrid approach (Option C)",
        "primary": true
      },
      {
        "label": "Discuss options",
        "value": "Let's discuss the three options (Separate, Bundled, Hybrid) in more detail before deciding"
      },
      {
        "label": "Different approach",
        "value": "I have a different idea for how provider installation should work"
      }
    ],
    "turnTiming": {
      "totalMs": 371060,
      "ttfeMs": 4265,
      "thinkingMs": 361670,
      "toolExecutionMs": 5124,
      "toolCallCount": 19,
      "thinkingPct": 97,
      "toolsPct": 1,
      "ttfePct": 1
    }
  },
  "createdBy": "claude",
  "createdAt": "2026-01-05T08:41:58.166Z",
  "updatedAt": "2026-01-05T08:46:55.523Z",
  "requestId": "b53ce820-86a5-4636-9b7a-bde2e78a9e31",
  "scope": "vibetools",
  "tags": [
    "architecture",
    "greatvibe",
    "agent",
    "providers"
  ],
  "targetUser": "claude"
}