Configure AI provider models for Claude Octopus workflows
Configures AI model selection and phase routing for Claude Octopus workflows to optimize performance and cost.
/plugin marketplace add nyldn/claude-octopus/plugin install claude-octopus@nyldn-pluginscommands/Configure which AI models are used by Claude Octopus workflows. This allows you to:
# View current configuration (models + phase routing)
/octo:model-config
# Set codex model (persistent)
/octo:model-config codex gpt-5.3-codex
# Set to Spark for fast mode
/octo:model-config codex gpt-5.3-codex-spark
# Set gemini model (persistent)
/octo:model-config gemini gemini-3-pro-preview
# Set session-only override (doesn't modify config file)
/octo:model-config codex gpt-5.2 --session
# Configure phase routing (which model to use in which phase)
/octo:model-config phase deliver gpt-5.3-codex-spark
/octo:model-config phase develop gpt-5.3-codex
# Reset to defaults
/octo:model-config reset codex
/octo:model-config reset phases
/octo:model-config reset all
Models are selected using a 5-tier precedence system:
Environment variables (highest priority)
OCTOPUS_CODEX_MODEL - Override all codex model selectionOCTOPUS_GEMINI_MODEL - Override all gemini model selectionTask hints (contextual override from calling code)
fast / spark → GPT-5.3-Codex-Sparkdeep / security → GPT-5.3-Codexlarge-codebase → GPT-4.1reasoning → o3budget → GPT-5.1-Codex-MiniPhase routing config (per-phase model selection)
~/.claude-octopus/config/providers.json → phase_routingConfig file defaults / session overrides
~/.claude-octopus/config/providers.json → providers / overridesHard-coded defaults (lowest priority)
gpt-5.3-codexgpt-5.3-codex-sparko3gpt-4.1gemini-3-pro-preview| Model | Context | Speed | Best For | Cost |
|---|---|---|---|---|
gpt-5.3-codex | 400K | ~65 tok/s | Complex implementation, architecture | $1.75/$14.00 per MTok |
gpt-5.3-codex-spark | 128K | 1000+ tok/s | Fast reviews, iteration, prototyping | Pro-only |
gpt-5.2-codex | 400K | ~65 tok/s | Standard code generation | $1.75/$14.00 per MTok |
| Model | Context | Best For | Cost |
|---|---|---|---|
gpt-5.1-codex-mini | 400K | Budget tasks, ~1 credit/msg | ~$0.30/$1.25 per MTok |
gpt-5.1-codex-max | 400K | Long-horizon agentic tasks | $1.25/$10.00 per MTok |
gpt-5-codex | 400K | Legacy support | $1.25/$10.00 per MTok |
| Model | Context | Best For | Cost |
|---|---|---|---|
o3 | 200K | Deep reasoning, trade-off analysis | $2.00/$8.00 per MTok |
o4-mini | 200K | Cost-effective reasoning | $1.10/$4.40 per MTok |
| Model | Context | Best For | Cost |
|---|---|---|---|
gpt-4.1 | 1M | Large codebase analysis, dependency mapping | $2.00/$8.00 per MTok |
gpt-4.1-mini | 1M | Budget large-context tasks | $0.40/$1.60 per MTok |
| Agent Type | Model | Context | Best For | Cost |
|---|---|---|---|---|
openrouter-glm5 | z-ai/glm-5 | 203K | Code review (77.8% SWE-bench, lowest hallucination) | $0.80/$2.56 per MTok |
openrouter-kimi | moonshotai/kimi-k2.5 | 262K | Research, large context, multimodal | $0.45/$2.25 per MTok |
openrouter-deepseek | deepseek/deepseek-r1 | 164K | Deep reasoning (visible <think> traces) | $0.70/$2.50 per MTok |
Requires OPENROUTER_API_KEY to be set. These are automatically selected when OpenRouter is the chosen provider via get_tiered_agent_v2() task routing.
| Model | Best For | Cost |
|---|---|---|
gemini-3-pro-preview | Premium quality research | $2.50/$10.00 per MTok |
gemini-3-flash-preview | Fast, low-cost tasks | $0.25/$1.00 per MTok |
v8.9.0 introduces contextual phase routing - automatically selecting the best model for each workflow phase:
| Phase | Default Model | Rationale |
|---|---|---|
discover | gpt-5.3-codex | Deep research needs max reasoning |
define | gpt-5.3-codex | Requirements analysis needs precision |
develop | gpt-5.3-codex | Complex implementation |
deliver | gpt-5.3-codex-spark | Fast review feedback (15x faster) |
quick | gpt-5.3-codex-spark | Speed over depth |
debate | gpt-5.3-codex | Deep reasoning for arguments |
review | gpt-5.3-codex-spark | Rapid PR review feedback |
security | gpt-5.3-codex | Thorough security analysis |
research | gpt-5.3-codex | Deep multi-source research |
# Use Spark for develop phase (faster iteration)
/octo:model-config phase develop gpt-5.3-codex-spark
# Use full codex for all review phases (deeper analysis)
/octo:model-config phase deliver gpt-5.3-codex
/octo:model-config phase review gpt-5.3-codex
# Use budget model for discover phase (save costs on research)
/octo:model-config phase discover gpt-5.1-codex-mini
# Reset phase routing to defaults
/octo:model-config reset phases
# Switch everything to Spark for rapid iteration
export OCTOPUS_CODEX_MODEL="gpt-5.3-codex-spark"
/octo:develop user profile component
# NOTE: Spark has 128K context (vs 400K for full Codex)
# Use 1M context model for analyzing large repos
/octo:model-config codex gpt-4.1 --session
/octo:discover "analyze the entire authentication subsystem"
# Use budget models across the board
/octo:model-config codex gpt-5.1-codex-mini
/octo:model-config gemini gemini-3-flash-preview
/octo:embrace build a simple CRUD API
# Use premium models + reasoning for security
/octo:model-config phase security o3
/octo:security audit the payment processing module
# Default phase routing already does this, but to customize:
/octo:model-config phase develop gpt-5.3-codex
/octo:model-config phase deliver gpt-5.3-codex-spark
/octo:model-config phase review gpt-5.3-codex-spark
Location: ~/.claude-octopus/config/providers.json
{
"version": "2.0",
"providers": {
"codex": {
"model": "gpt-5.3-codex",
"fallback": "gpt-5.2-codex",
"spark_model": "gpt-5.3-codex-spark",
"mini_model": "gpt-5.1-codex-mini",
"reasoning_model": "o3",
"large_context_model": "gpt-4.1"
},
"gemini": {
"model": "gemini-3-pro-preview",
"fallback": "gemini-3-flash-preview"
}
},
"phase_routing": {
"discover": "gpt-5.3-codex",
"define": "gpt-5.3-codex",
"develop": "gpt-5.3-codex",
"deliver": "gpt-5.3-codex-spark",
"quick": "gpt-5.3-codex-spark",
"debate": "gpt-5.3-codex",
"review": "gpt-5.3-codex-spark",
"security": "gpt-5.3-codex",
"research": "gpt-5.3-codex"
},
"overrides": {}
}
| Factor | GPT-5.3-Codex | GPT-5.3-Codex-Spark |
|---|---|---|
| Speed | ~65 tok/s | 1000+ tok/s (15x) |
| Context | 400K tokens | 128K tokens |
| Terminal-Bench | 77.3% | 58.4% |
| Image input | Yes | No (text only) |
| Availability | All plans | Pro ($200/mo) only |
| Best for | Complex tasks, security, architecture | Reviews, iteration, quick tasks |
Rule of thumb: Use Spark when speed matters more than depth. Use full Codex when accuracy and context window matter.
jq - JSON processor (install: brew install jq or apt install jq)OCTOPUS_GEMINI_SANDBOX):
headless (default, v8.10.0) - Stdin-based prompt delivery with -p "", -o text, --approval-mode yolointeractive - Launch Gemini in interactive mode (for manual use)auto-accept - Legacy alias for headlessprompt-mode - Legacy alias for interactiveWhen the user invokes /octo:model-config, you MUST:
Parse arguments to determine action:
<provider> <model> → Set model (persistent)<provider> <model> --session → Set model (session only)phase <phase> <model> → Set phase-specific model routingreset <provider|phases|all> → Reset to defaultsView Configuration (no args):
# Check environment variables
env | grep OCTOPUS_
# Show config file contents
if [[ -f ~/.claude-octopus/config/providers.json ]]; then
cat ~/.claude-octopus/config/providers.json | jq '.'
else
echo "No configuration file found (using defaults)"
fi
Set Model (<provider> <model> or with --session):
# Call set_provider_model from orchestrate.sh
source "${CLAUDE_PLUGIN_ROOT}/scripts/orchestrate.sh"
set_provider_model <provider> <model> [--session]
# Show updated configuration
cat ~/.claude-octopus/config/providers.json | jq '.'
Set Phase Routing (phase <phase> <model>):
# Update phase_routing in config file
local config_file="${HOME}/.claude-octopus/config/providers.json"
jq ".phase_routing.${phase} = \"${model}\"" "$config_file" > "${config_file}.tmp" && mv "${config_file}.tmp" "$config_file"
echo "✓ Set phase routing: $phase → $model"
cat ~/.claude-octopus/config/providers.json | jq '.phase_routing'
Reset Model (reset <provider|phases|all>):
# Call reset_provider_model from orchestrate.sh
source "${CLAUDE_PLUGIN_ROOT}/scripts/orchestrate.sh"
reset_provider_model <provider>
# For phases: reset phase_routing to defaults
# For all: reset both providers and phase routing
# Show updated configuration
cat ~/.claude-octopus/config/providers.json | jq '.'
Provide guidance on: