# Install
npm install -g routewise

# Set your API keys (use whichever providers you have)
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export VERTEX_PROJECT_ID="my-project"  # Optional: for Gemini models

# Run a workflow
routewise run "Fix the failing authentication test and update docs"

routewise — running workflow
Task: Fix the failing authentication test and update docs

step_001 [reasoning] Plan the debugging approach
  → claude-sonnet-4.6 (best-fit, confidence: 90%)
  ✓ passed ($0.0032, 2847ms)

step_002 [code-gen] Fix the authentication middleware
  → claude-sonnet-4.6 (user-preferred, confidence: 95%)
  ✓ passed ($0.0058, 3201ms)

step_003 [code-gen] Update test assertions
  → gpt-4.1 (fallback, confidence: 80%)
  ✓ passed ($0.0019, 1843ms)

step_004 [writing] Update authentication documentation
  → gemini-3.5-flash (best-fit, confidence: 90%)
  ✓ passed ($0.0002, 892ms)

✓ completed — 4 steps, 4 passed
Cost: $0.0111 │ Time: 8.8s
Trace: .routewise/runs/run_20260613_k7m2x1/

User Task (natural language)
     │
     ▼
┌─────────────┐
│  Decomposer │  Breaks task into ordered steps
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Classifier  │  Labels: reasoning | code-gen | summarization | writing | research | editing
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Router    │  Picks best model per step within constraints (cost, latency, quality)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Executor   │  Calls the selected model with step context
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Evaluator  │  Scores output quality with heuristics + human verdict
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Trace     │  Logs: model, reason, cost, latency, quality, verdict
└─────────────┘

{
  "mcpServers": {
    "routewise": {
      "command": "npx",
      "args": ["-y", "routewise", "serve"]
    }
  }
}

routewise run "Build an MVP for a todo app with auth"
routewise step "Summarize this PR" --type summarization
routewise trace --run run_20260613_k7m2x1
routewise models

# Fix a bug — needs reasoning + code + testing
routewise run "Fix the race condition in the checkout flow"

# Generate tests — needs code analysis + code generation
routewise run "Write comprehensive tests for the auth module"

# Create a design document — needs research + reasoning + writing
routewise run "Create an architecture design for the new payment system"

# Build an MVP — needs planning + code + docs + content
routewise run "Build an MVP for a URL shortener with analytics"

# Launch content — needs writing + editing + summarization
routewise run "Create launch post, demo script, and README for the new feature"

.routewise/runs/run_20260613_k7m2x1/
├── trace.json       # Run metadata (cost, time, status)
├── steps.jsonl      # Per-step decisions (one JSON per line)
└── artifacts/       # Step outputs

{
  "runId": "run_20260613_k7m2x1",
  "task": "Fix the failing authentication test",
  "status": "completed",
  "totalSteps": 4,
  "totalCostUsd": 0.0111,
  "totalLatencyMs": 8783,
  "constraints": { "maxCostPerRun": 0.50, "maxLatencyPerStep": 30000 }
}

{
  "stepId": "step_001",
  "type": "reasoning",
  "goal": "Plan debugging approach",
  "model": "claude-sonnet-4.6",
  "provider": "anthropic",
  "reason": "best-fit",
  "confidence": 0.9,
  "costUsd": 0.0032,
  "latencyMs": 2847,
  "evaluation": { "passed": true, "checks": ["ordered-items: OK", "min-length: OK"] }
}

import { defineConfig } from 'routewise';

export default defineConfig({
  providers: {
    anthropic: { apiKey: 'env:ANTHROPIC_API_KEY' },
    openai: { apiKey: 'env:OPENAI_API_KEY' },
    vertex: {
      projectId: 'env:VERTEX_PROJECT_ID',
      location: 'us-central1',
    },
  },
  constraints: {
    maxCostPerRun: 0.50,        // USD
    maxCostPer1kTokens: 0.02,   // USD
    maxLatencyPerStep: 30_000,  // ms
    preferredProviders: ['anthropic', 'openai', 'vertex'],
    privacyLevel: 'standard',
  },
  routing: {
    reasoning:      { prefer: 'claude-sonnet-4.6', fallback: 'gpt-4.1' },
    'code-gen':     { prefer: 'claude-sonnet-4.6', fallback: 'gpt-4.1' },
    summarization:  { prefer: 'gemini-3.1-flash-lite', fallback: 'claude-haiku-4.5' },
    writing:        { prefer: 'claude-sonnet-4.6', fallback: 'gpt-4.1' },
    research:       { prefer: 'gemini-3.1-pro', fallback: 'gpt-5.5' },
    editing:        { prefer: 'gemini-3.5-flash', fallback: 'claude-haiku-4.5' },
  },
  trace: {
    store: 'local',
    directory: '.routewise/runs',
  },
});

$ routewise models

routewise/
├── src/
│   ├── cli/        → CLI commands (run, step, trace, init, serve, models)
│   ├── core/       → Routing engine (classifier, selector, executor, evaluator, decomposer, router)
│   ├── config/     → Config schema, loader, defaults (Zod validation)
│   ├── providers/  → Model adapters (Anthropic, OpenAI, Vertex) + model catalog
│   ├── mcp/        → MCP server (4 tools for Claude Code, Cursor, any MCP client)
│   └── trace/      → Trace storage and rendering
├── tests/          → Unit tests (125 passing)
└── dist/           → Built CLI + library

{
  id: 'your-new-model',
  provider: 'openai',
  capabilities: ['reasoning', 'code-gen', 'writing'],
  costPer1kTokens: 0.004,
  p95LatencyMs: 2000,
  qualityScore: 0.93,
  contextWindow: 256000,
  supportsStructuredOutput: true,
  tags: ['new-feature'],
  metadata: { description: 'Your model description' },
}

interface Provider {
  name: string;
  complete(prompt: string, options?: ProviderCompleteOptions): Promise<ProviderResponse>;
  completeWithModel(model: string, prompt: string, options?: ProviderCompleteOptions): Promise<ProviderResponse>;
  isAvailable(): boolean;
  listModels(): string[];
}

git clone https://github.com/your-org/routewise.git
cd routewise
pnpm install
pnpm build        # Build CLI + library
pnpm test         # Run 125 tests
pnpm typecheck    # Type check (strict mode)
pnpm lint         # Lint with Biome