# Multi-Provider Architecture Reference > **Version:** 5.25.0 | **Status:** Production | **Last Updated:** 2026-05-22 Loki Mode supports four AI CLI providers with a unified abstraction layer. This document provides detailed technical reference for the multi-provider system. --- ## Provider Overview | Provider | CLI | Status | Features | |----------|-----|--------|----------| | **Claude Code** | `claude` | Full | Subagents, Parallel, Task Tool, MCP | | **OpenAI Codex** | `codex` | Degraded | Sequential, Effort Parameter, MCP (basic) | | **Cline CLI** | `cline` | Near-Full (Tier 2) | Subagents, MCP, 12+ providers | | **Aider** | `aider` | Degraded | Sequential, 18+ providers | --- ## Provider Configuration Files Located in `providers/` directory: ``` providers/ claude.sh # Full-featured provider codex.sh # Degraded mode, effort parameter cline.sh # Near-full mode, 12+ providers (Tier 2) aider.sh # Degraded mode, 18+ providers loader.sh # Provider loader utility ``` ### Configuration Variables Each provider config exports these variables: #### Identity Variables ```bash PROVIDER_NAME="claude" # Internal identifier PROVIDER_DISPLAY_NAME="Claude Code" # Human-readable name PROVIDER_CLI="claude" # CLI binary name ``` #### CLI Invocation Variables ```bash PROVIDER_AUTONOMOUS_FLAG="--dangerously-skip-permissions" PROVIDER_PROMPT_FLAG="-p" # Empty for positional prompt PROVIDER_PROMPT_POSITIONAL=false # true if prompt is positional arg ``` #### Capability Flags ```bash PROVIDER_HAS_SUBAGENTS=true # Can spawn Task tool subagents PROVIDER_HAS_PARALLEL=true # Supports parallel execution PROVIDER_HAS_TASK_TOOL=true # Has Task tool for agent spawning PROVIDER_HAS_MCP=true # Supports MCP server integration (Codex also has basic MCP) PROVIDER_MAX_PARALLEL=10 # Maximum concurrent agents ``` #### Model Configuration ```bash PROVIDER_MODEL_PLANNING="claude-opus-4-7" PROVIDER_MODEL_DEVELOPMENT="claude-sonnet-4-6" PROVIDER_MODEL_FAST="claude-haiku-4-5-20251001" ``` #### Rate Limiting ```bash PROVIDER_RATE_LIMIT_RPM=50 # Requests per minute PROVIDER_CONTEXT_WINDOW=1000000 # Max context tokens (Opus 4.7: 1M at standard pricing) PROVIDER_MAX_OUTPUT_TOKENS=128000 ``` #### Degraded Mode ```bash PROVIDER_DEGRADED=false # true for Codex/Aider PROVIDER_DEGRADED_REASONS=() # Array of limitation descriptions ``` --- ## Abstract Model Tiers Loki Mode uses abstract tiers that map to provider-specific configurations: | Abstract Tier | Purpose | Claude | Codex | |---------------|---------|--------|-------| | `planning` | Architecture, PRD analysis | opus | xhigh effort | | `development` | Implementation, tests | sonnet | high effort | | `fast` | Simple tasks, docs | haiku | low effort | ### Tier Selection by RARV Phase ``` RARV Phase -> Abstract Tier -> Provider-Specific ----------------------------------------------------- REASON -> planning -> opus/xhigh ACT -> development -> sonnet/high REFLECT -> development -> sonnet/high VERIFY -> fast -> haiku/low ``` --- ## Provider Loader API ### Functions ```bash # Load a provider configuration load_provider "claude" # Returns 0 on success, 1 on failure # Check if provider is valid validate_provider "codex" # Returns 0 if valid # Check if provider CLI is installed check_provider_installed "cline" # Returns 0 if installed # Auto-detect first available provider auto_detect_provider # Echoes provider name or returns 1 # Print provider info print_provider_info # Displays loaded provider details # Print capability matrix print_capability_matrix # Shows all providers comparison ``` ### Usage Example ```bash source providers/loader.sh # Load specific provider if load_provider "codex"; then echo "Loaded: $PROVIDER_DISPLAY_NAME" echo "CLI: $PROVIDER_CLI" echo "Degraded: $PROVIDER_DEGRADED" fi # Auto-detect if provider=$(auto_detect_provider); then load_provider "$provider" fi ``` --- ## Provider Invocation Functions Each provider exports these functions: ```bash # Check if CLI is installed provider_detect() # Returns 0 if installed # Get CLI version provider_version() # Echoes version string # Invoke with prompt (autonomous mode) provider_invoke "Your prompt here" # Invoke with tier-specific configuration provider_invoke_with_tier "planning" "Your prompt here" # Get tier parameter value provider_get_tier_param "development" # Returns: opus/sonnet/haiku or xhigh/high/low ``` --- ## Degraded Mode Behavior When running with Codex or Aider: 1. **RARV Cycle executes sequentially** - No parallel agents 2. **Task tool calls are skipped** - Main thread handles all work 3. **Model tier maps to provider configuration:** - Codex: `CODEX_MODEL_REASONING_EFFORT` environment variable 4. **Quality gates run sequentially** - No 3-reviewer parallel review 5. **Git worktree parallelism disabled** - `--parallel` flag has no effect ### Degraded Mode Detection ```bash if [ "$PROVIDER_DEGRADED" = "true" ]; then echo "Running in degraded mode" echo "Limitations:" for reason in "${PROVIDER_DEGRADED_REASONS[@]}"; do echo " - $reason" done fi ``` --- ## Rate Limit Detection The rate limiting system is provider-agnostic: ### Detection Patterns ```bash # Generic patterns (all providers) - HTTP 429 status code - "rate limit" / "rate-limit" / "ratelimit" (case insensitive) - "too many requests" - "quota exceeded" - "request limit" - "retry-after" header # Claude-specific - "resets Xam/pm" format ``` ### Fallback Chain ``` 1. Provider-specific parsing (Claude's reset time) | v (if no result) 2. Generic Retry-After header parsing | v (if no result) 3. Calculated backoff based on PROVIDER_RATE_LIMIT_RPM ``` ### Rate Limit Functions ```bash # Check if output contains rate limit indicators is_rate_limited "$log_file" # Returns 0 if rate limited # Get wait time from rate limit response detect_rate_limit "$log_file" # Echoes seconds to wait # Parse Retry-After header parse_retry_after "$log_file" # Echoes seconds # Calculate default backoff calculate_rate_limit_backoff # Uses PROVIDER_RATE_LIMIT_RPM ``` --- ## CLI Integration ### Provider Selection ```bash # Via CLI flag ./autonomy/run.sh --provider codex ./prd.md loki start --provider cline ./prd.md # Via environment variable export LOKI_PROVIDER=codex ./autonomy/run.sh ./prd.md # Precedence: flag > env > default (claude) ``` ### Help Output ``` $ loki start --help Provider Options: --provider PROVIDER Select AI provider (claude, codex, cline, aider) Default: claude (auto-detect if not installed) Provider Capability Matrix: Provider Features Parallel Task Tool MCP -------------------------------------------------- claude Full Yes (10) Yes Yes codex Degraded No No Basic cline Near-Full No Yes Yes aider Degraded No No No ``` --- ## Verified CLI Flags All CLI flags have been verified against actual CLI help output: | Provider | Flag | Verified Version | Notes | |----------|------|------------------|-------| | Claude | `--dangerously-skip-permissions` | v2.1.34 | Autonomous mode | | Codex | `--sandbox workspace-write` | v0.132.0 | Recommended (--full-auto deprecated 0.125+); legacy: `exec --dangerously-bypass-approvals-and-sandbox` | | Cline | `--auto-approve` | latest | Autonomous mode | | Aider | `--yes-always` | latest | Autonomous mode | --- ## Test Coverage The multi-provider system has 180 tests across 5 test suites: | Test Suite | Tests | Coverage | |------------|-------|----------| | `test-provider-loader.sh` | 12 | Provider loading, validation | | `test-provider-invocation.sh` | 24 | Invoke functions, tier params | | `test-provider-degraded-mode.sh` | 19 | Degraded flags, capabilities | | `test-cli-provider-flag.sh` | 39 | CLI flag parsing, precedence | | `test-rate-limiting.sh` | 27 | Rate limit detection, backoff | Run tests: ```bash for test in tests/test-provider-*.sh tests/test-cli-provider-flag.sh tests/test-rate-limiting.sh; do bash "$test" done ``` --- ## Adding New Providers To add a new provider: 1. Create `providers/.sh` with all required variables 2. Implement the four provider functions: - `provider_detect()` - `provider_version()` - `provider_invoke()` - `provider_invoke_with_tier()` - `provider_get_tier_param()` 3. Add to `SUPPORTED_PROVIDERS` array in `loader.sh` 4. Update `validate_provider()` regex 5. Add provider case in `run.sh` invocation switch 6. Add tests for new provider ### Provider Template ```bash #!/bin/bash # CLI Provider Configuration # Provider Identity PROVIDER_NAME="" PROVIDER_DISPLAY_NAME="" PROVIDER_CLI="" # CLI Invocation PROVIDER_AUTONOMOUS_FLAG="" PROVIDER_PROMPT_FLAG="" # or "-p" etc PROVIDER_PROMPT_POSITIONAL=true # Capability Flags PROVIDER_HAS_SUBAGENTS=false PROVIDER_HAS_PARALLEL=false PROVIDER_HAS_TASK_TOOL=false PROVIDER_HAS_MCP=false PROVIDER_MAX_PARALLEL=1 # Model Configuration PROVIDER_MODEL_PLANNING="" PROVIDER_MODEL_DEVELOPMENT="" PROVIDER_MODEL_FAST="" # Context and Limits PROVIDER_CONTEXT_WINDOW=128000 PROVIDER_MAX_OUTPUT_TOKENS=32000 PROVIDER_RATE_LIMIT_RPM=60 # Degraded Mode PROVIDER_DEGRADED=true PROVIDER_DEGRADED_REASONS=( "Reason 1" "Reason 2" ) # Provider Functions provider_detect() { command -v >/dev/null 2>&1 } provider_version() { --version 2>/dev/null | head -1 } provider_invoke() { local prompt="$1" shift "$prompt" "$@" } provider_get_tier_param() { local tier="$1" case "$tier" in planning) echo "" ;; development) echo "" ;; fast) echo "" ;; *) echo "" ;; esac } provider_invoke_with_tier() { local tier="$1" local prompt="$2" shift 2 local param=$(provider_get_tier_param "$tier") # Provider-specific tier invocation "$prompt" "$@" } ``` --- ## Related Documentation - `skills/providers.md` - User-facing provider guide - `skills/model-selection.md` - Model tier selection patterns - `references/core-workflow.md` - RARV cycle documentation - `docs/INSTALLATION.md` - Installation instructions per provider