Introduce Provider Abstraction to Support Claude CLI and Other Local Providers

[0xNull-ops]

Summary
Currently, the SDK integrates with the Claude Code SDK using API keys only. This limits usage to API-based access and does not support users who already have active Claude CLI subscriptions installed locally.
This feature request proposes adding native Claude CLI support as a local provider, potentially via the Versal AI SDK (Universal Plugin system), allowing users to authenticate and run Claude through their locally installed CLI instead of requiring API keys.

🎯 Problem
At the moment:
The SDK only supports Claude via API key
Users with paid Claude CLI subscriptions cannot use their local authenticated CLI
API usage introduces:
Extra cost (double paying if user already has CLI subscription)
API key management overhead
Rate limit concerns
Network dependency
Many developers prefer using their locally authenticated Claude CLI, especially in dev environments.

💡 Proposed Solution
Add a Native Local Provider Layer
Introduce a local provider abstraction that allows the SDK to:
Detect installed Claude CLI and Other CLIs
Execute prompts through CLI subprocess calls
Stream responses back into the SDK
Fallback to API if CLI is unavailable
This could be implemented via:
Versal AI SDK (Universal Plugin approach)
OR
A provider abstraction layer inside this SDK

📌 Suggested Architecture
1️⃣ Introduce Provider Abstraction

interface AIProvider {
  sendPrompt(prompt: string, options?: ProviderOptions): Promise<AIResponse>
  streamPrompt?(prompt: string, options?: ProviderOptions): AsyncIterable<string>
}

Then support:
ClaudeAPIProvider
ClaudeCLIProvider
Future: OpenAI CLI, Gemini CLI, etc.

2️⃣ Claude CLI Provider (Example)
Implementation concept:

import { exec } from "child_process"

exec(`claude --json "${prompt}"`, (error, stdout) => {
  // Parse JSON response
})

Features:
Uses system-installed Claude CLI
Respects user’s local auth/session
No API key required
Optional streaming support
3️⃣ Optional: Use Versal AI SDK
If maintaining multiple provider integrations is out of scope, consider using:
Versal AI SDK (Universal Plugin)
Allows pluggable AI backends
Centralizes provider management
This would:
Standardize multi-provider support
Make future providers easier to add
Keep this SDK focused on React Native integration

✨ Benefits
✅ Enables users to use existing Claude CLI subscriptions
✅ Reduces API key dependency
✅ Improves developer experience
✅ Opens door to multi-provider architecture
✅ Future-proofs SDK
✅ Reduces vendor lock-in
🔄 Backwards Compatibility
This would be an additive feature.
Default behavior remains API-based unless user selects:
provider: "claude-cli"

📌 Edge Cases to Consider
CLI not installed
CLI not authenticated
Windows/macOS/Linux path differences
Streaming support
Sandboxed environments

📌 Example Usage

const client = createVibeClient({
  provider: "claude-cli",
})
Or:
const client = createVibeClient({
  provider: "claude-api",
  apiKey: process.env.CLAUDE_API_KEY
})

📌 Alternative Approaches Considered
Continue API-only model (limits user flexibility)
Require users to build their own CLI wrapper (poor DX)
External plugin (fragmented ecosystem)

📌 Why This Matters
As local-first AI workflows become more common, developers increasingly expect SDKs to support:
CLI-based AI tools
Local auth sessions
Pluggable providers
Adding native CLI support would make this SDK significantly more flexible and aligned with modern AI tooling workflows.

[geoman2]

+1 for this feature, Rofi any eta regarding it?

[bidah]

This makes sense. I am going to add claude code to the github repo to start playing with the LLM to come by their own on a solution to dive deeper into the proposal. My initial though though for going beyond claude agent sdk was to integrate opencode, which is another route but very flexible for using any code model in the end.

[bidah]

@claude implement this proposal, complement the plan, "think deeply" about the transport, we have been passing the stdout of the streaming of claude agent sdk in a sandbox, but this offer a new option besides this approach. This proposal aims to skip the sandboxing altogether, since it will use the local claude code setup, this is meant to be used with the system running locally so put into cosideration too that we need to modularize this new local setup so the app can be configured to be run with this setup vs, to be ran with the sandboxing + claude agent sdk. It refers to the --json flag but there is also the -p flag. use context7 mcp to grab all required docs you see fit.

[claude]

Claude finished @bidah's task in 9m 41s —— View job • claude/issue-1-20260221-1329 • Create PR ➔

---

Implementing Provider Abstraction for Claude CLI & Local Providers

Tasks:

• Explore codebase architecture (chat API, sandbox, streaming)
• Research Claude CLI flags (-p, --output-format stream-json) and streaming protocols
• Design provider abstraction & transport layer
• Implement AIProvider interface & types (lib/providers/types.ts)
• Implement LocalCLIProvider — subprocess transport with stream-json parsing (lib/providers/local-cli-provider.ts)
• Implement SandboxedClaudeProvider wrapper (lib/providers/sandboxed-provider.ts)
• Implement provider factory with env-based mode selection (lib/providers/factory.ts)
• Add local-cli handler, skips E2B entirely (lib/providers/local-cli-handler.ts)
• Wire provider routing into claude-code-handler.ts
• Update .env.example with CLAUDE_PROVIDER and LOCAL_PROJECTS_PATH
• Commit and push (e7b62d8)

---

What was implemented

New files in apps/web/lib/providers/

File	Purpose
types.ts	AIProvider interface, ProviderMode, request/callback/result types
local-cli-provider.ts	Spawns claude -p "..." --output-format stream-json as a Node.js subprocess
sandboxed-provider.ts	Typed wrapper for the existing E2B approach
factory.ts	createProvider() / isLocalCLIMode() driven by CLAUDE_PROVIDER env var
local-cli-handler.ts	handleLocalCLIGeneration() — the local-mode counterpart to handleClaudeCodeGeneration()
index.ts	Clean public exports

Modified files

• claude-code-handler.ts — handleClaudeCodeGeneration() now checks isLocalCLIMode() at the top and delegates to the local handler when CLAUDE_PROVIDER=local-cli. The existing sandboxed path is completely unchanged.
• .env.example — documents CLAUDE_PROVIDER and LOCAL_PROJECTS_PATH

---

Transport design (deep dive)

Existing sandboxed transport

Chat API route
  └─ handleClaudeCodeGeneration()
       └─ ClaudeCodeService.generateAppStreaming()
            └─ E2B: sandbox.commands.run(background=true)
                 └─ claude-executor.ts (@anthropic-ai/claude-agent-sdk)
                      └─ query() → async message stream
                           stdout: "Streaming: {json}" lines
                                ← onStdout callback
                                ← onMessage callback
                                ← text-delta stream chunks

New local-cli transport

Chat API route
  └─ handleClaudeCodeGeneration()
       └─ [if CLAUDE_PROVIDER=local-cli]
            └─ handleLocalCLIGeneration()
                 └─ LocalCLIProvider.generate()
                      └─ spawn('claude', ['-p', prompt,
                               '--output-format', 'stream-json',
                               '--allowedTools', 'all',
                               '--system-prompt-file', path,
                               '--model', model,
                               '--resume', sessionId])
                           stdout: newline-delimited JSON
                             {"type":"system","session_id":"..."}
                             {"type":"assistant","message":{...}}
                             {"type":"result","result":"..."}
                                ← onMessage callback
                                ← text-delta stream chunks

No E2B. No API key. Uses ~/.claude/ auth from claude login.

---

How to use local-cli mode

# 1. Install Claude CLI (https://claude.ai/download)
# 2. Authenticate
claude login

# 3. Add to your .env.local
CLAUDE_PROVIDER=local-cli
LOCAL_PROJECTS_PATH=/path/to/local/projects  # optional, defaults to ~/local-projects

# 4. Start the dev server
pnpm run dev:3210

Projects are stored at $LOCAL_PROJECTS_PATH/<projectId>. Skills are written to .claude/skills/ inside the project directory. Multi-turn conversations resume via --resume <session-id> (session ID persisted in the DB, same field as sandboxed mode).

---

What's left for future PRs

• UI toggle to switch provider mode per-project (rather than env var only)
• Local Expo dev server integration (auto-launch Metro bundler for local projects)
• Bundle building for local mode (currently skipped)
• Support for other local CLIs (opencode, Gemini CLI) via additional ProviderMode values — the abstraction is ready for this
  ·