aios-core/.aios-core/infrastructure/tools/cli/llm-routing.yaml

Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework

# LLM Routing Tool Definition
# Location: .aios-core/infrastructure/tools/cli/llm-routing.yaml
# Version: 1.0.0

tool:
  id: llm-routing
  name: LLM Routing
  version: 1.0.0
  category: cli
  description: |
    Cost-effective LLM routing for Claude Code.
    Provides two commands for different use cases:
    - claude-max: Uses Claude Max subscription via OAuth (~$15/M tokens)
    - claude-free: Uses DeepSeek API (~$0.14/M tokens)

capabilities:
  - Install claude-max and claude-free commands
  - Cross-platform support (Windows CMD, Unix bash)
  - Automatic .env file detection for API keys
  - Cost optimization for development workflows

installation:
  method: script
  script: .aios-core/infrastructure/scripts/llm-routing/install-llm-routing.js
  templates_dir: .aios-core/infrastructure/scripts/llm-routing/templates/

  # Files installed
  windows:
    - name: claude-free.cmd
      target: "%APPDATA%/npm/claude-free.cmd"
    - name: claude-max.cmd
      target: "%APPDATA%/npm/claude-max.cmd"

  unix:
    - name: claude-free.sh
      target: "/usr/local/bin/claude-free"
      permissions: "755"
    - name: claude-max.sh
      target: "/usr/local/bin/claude-max"
      permissions: "755"

usage:
  claude-max:
    description: "Premium Claude experience using Max subscription"
    command: "claude-max"
    authentication: OAuth (claude.ai login)
    cost: "Included in subscription (~$15/M tokens if API)"
    features:
      - Full Claude capabilities
      - No API key required
      - Uses existing Claude login

  claude-free:
    description: "Cost-effective development using DeepSeek"
    command: "claude-free"
    authentication: API Key (DEEPSEEK_API_KEY)
    cost: "~$0.14/M tokens"
    features:
      - Tool calling support
      - Compatible with Claude Code workflows
      - Project .env file support
    setup:
      - "Get API key at: https://platform.deepseek.com/api_keys"
      - "Add to .env: DEEPSEEK_API_KEY=sk-your-key"
      - "Or export: export DEEPSEEK_API_KEY=sk-your-key"

configuration:
  env_file: ".env"
  env_variables:
    DEEPSEEK_API_KEY:
      description: "DeepSeek API key for claude-free command"
      required: true
      format: "sk-*"
      obtain_at: "https://platform.deepseek.com/api_keys"

cost_comparison:
  claude_max:
    input: "$15.00/M tokens"
    output: "$75.00/M tokens"
    note: "Included in Max subscription"
  deepseek:
    input: "$0.07/M tokens"
    output: "$0.14/M tokens"
    note: "Native Anthropic-compatible endpoint with tool support"

integration:
  wizard_step: true
  wizard_order: 5
  required: false
  recommended: true
  message: |
    Would you like to install LLM routing commands?
    - claude-max: Uses your Claude Max subscription
    - claude-free: Uses DeepSeek (~99% cost reduction)

health_check:
  windows:
    - "where claude-free.cmd"
    - "where claude-max.cmd"
  unix:
    - "which claude-free"
    - "which claude-max"

troubleshooting:
  command_not_found:
    cause: "Commands not in PATH"
    solution: |
      Windows: Ensure %APPDATA%/npm is in PATH
      Unix: Ensure /usr/local/bin or ~/bin is in PATH

  api_key_error:
    cause: "DEEPSEEK_API_KEY not set"
    solution: |
      1. Create .env file in project root
      2. Add: DEEPSEEK_API_KEY=sk-your-key
      3. Get key at: https://platform.deepseek.com/api_keys

related_docs:
  - docs/guides/llm-routing.md
  - .aios-core/development/tasks/setup-llm-routing.md

metadata:
  created: "2025-12-14"
  updated: "2025-12-14"
  author: "AIOS Framework"
  story: "6.7"