Skip to content

feat: Support Claude Code CLI as alternative backend for AI supervision #6

@johnx25bd

Description

@johnx25bd

Summary

Allow VC to use Claude Code CLI (claude -p) instead of the Anthropic API SDK for AI supervision tasks, enabling users to run VC entirely through their existing Claude subscription without requiring a separate API key.

Motivation

The Problem

VC currently requires two separate billing relationships with Anthropic:

Layer Billing Model Used For
Coding Agent Claude subscription (Pro/Max) Code execution via claude CLI
AI Supervision Anthropic API (pay-per-token) Assessment, analysis, deduplication

This creates friction:

  • Users must obtain and manage an ANTHROPIC_API_KEY
  • API costs are in addition to subscription fees
  • Variable billing makes costs unpredictable

The Opportunity

Claude Code's print mode (-p) now supports structured JSON output with schema validation:

claude -p \
  --output-format json \
  --json-schema '{"type":"object","properties":{...}}' \
  --tools "" \
  --model sonnet \
  "Your prompt here"

This provides everything VC's supervision layer needs, meaning all AI usage could flow through the user's existing subscription.

User Impact

Scenario Current Proposed
Max subscriber ($100/mo) Pays subscription + API overage All usage included
Pro subscriber ($20/mo) Pays subscription + API overage All usage included
Setup complexity Requires API key configuration Just claude login
Cost predictability Variable (token-based) Fixed monthly

Proposed Solution

Architecture

Introduce a pluggable AIBackend interface:

type AIBackend interface {
    Complete(ctx context.Context, prompt string, opts CompletionOptions) (string, error)
}

With two implementations:

  1. AnthropicSDKBackend - existing behavior (API key)
  2. ClaudeCodeBackend - new option (subscription)

Configuration

# Use Claude Code CLI (subscription billing)
vc execute --use-claude-code

# Use API key (current default)
vc execute

Or via environment:

export VC_AI_BACKEND=claude-code

Acceptance Criteria

  • New AIBackend interface abstracts AI completion calls
  • ClaudeCodeBackend implementation shells out to claude -p
  • --use-claude-code flag added to vc execute
  • VC runs without ANTHROPIC_API_KEY when using CLI backend
  • All supervision operations work: assessment, analysis, deduplication, loop detection
  • Graceful error handling when claude CLI unavailable
  • Documentation updated with new configuration options

Trade-offs & Considerations

Advantages

  • No API key required for subscribers
  • Predictable monthly billing
  • Simpler onboarding experience
  • Single billing relationship

Limitations

  • Subscription rate limits apply (Pro is limited; Max is generous)
  • No token-level cost tracking (CLI doesn't expose usage)
  • Slightly higher latency (process spawn vs HTTP connection reuse)
  • Requires Claude Code CLI to be installed and authenticated

Mitigations

  • Keep API backend as default for backwards compatibility
  • Document rate limit considerations for Pro users
  • Add clear error messages for CLI authentication issues

Additional Context

References

Files Likely Affected

  • internal/ai/backend.go (new)
  • internal/ai/supervisor.go
  • internal/ai/assessment.go
  • internal/ai/analysis.go
  • internal/ai/deduplication.go
  • cmd/vc/execute.go

Estimated Scope

Medium (~450 LOC, 2-3 days)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions