Model Selection

zo provides intelligent fuzzy model selection with access to 50+ AI models through OpenRouter.

Quick Reference

Built-in Model Shortcuts

Short Name	Full Model ID	Best For	Speed	Cost
`sonnet`	anthropic/claude-sonnet-4.5	Complex reasoning, code analysis	Medium	Medium
`sonnet3`	anthropic/claude-3.5-sonnet	Previous Claude version	Medium	Medium
`opus`	anthropic/claude-opus-4.5	Highest quality Claude	Slow	High
`haiku`	anthropic/claude-3-haiku	Fast, simple tasks	Fast	Low
`flash`	google/gemini-2.5-flash	Default - Balanced performance	Fast	Low
`geminipro`	google/gemini-3-pro-preview	Google's most capable	Medium	Medium
`gpt4`	openai/gpt-4-turbo	Latest GPT-4	Medium	High
`gpt4o`	openai/gpt-4o	GPT-4 Optimized	Medium	Medium
`gpt4omini`	openai/gpt-4o-mini	Fast, cheap GPT-4	Fast	Low
`o1`	openai/o1	Reasoning-focused GPT	Slow	Very High
`o1mini`	openai/o1-mini	Lighter reasoning model	Medium	High
`grok`	x-ai/grok-4	X.AI's latest	Medium	Medium

Using Models

Slash Command

Most common method - use / followed by model name:

zo /sonnet 'Explain async/await in Rust'
zo /gpt4 'Write a poem about programming'
zo /flash 'Quick question: what is TCP?'

CLI Flag

Override any model selection:

zo --model opus 'Complex reasoning task'
zo --model haiku 'Simple question'

Config Default

Set in ~/.config/zo/config.toml:

default_model = "sonnet"

Now zo 'question' uses Sonnet instead of Flash.

Priority Order

Model selection priority (highest to lowest):

CLI --model flag (highest priority)
Slash command in prompt (/sonnet)
default_model from config file
Hardcoded fallback: flash (lowest priority)

Example:

# Uses opus (CLI flag wins)
zo --model opus /sonnet 'test'
 
# Uses sonnet (slash command)
zo /sonnet 'test'
 
# Uses config default (if set)
zo 'test'
 
# Uses flash (fallback)
zo 'test'  # With no config default

Fuzzy Matching

zo uses intelligent 3-stage matching to find models:

Stage 1: Exact Match (case-insensitive)

zo /sonnet "test"  # Exact match
zo /SONNET "test"  # Also matches (case-insensitive)

Stage 2: Substring Match

Input contained in model name:

zo /son "test"     # Matches 'sonnet' (son ⊂ sonnet)
zo /pro "test"     # Matches 'geminipro' (pro ⊂ geminipro)
zo /mini "test"    # Matches 'gpt4omini' or 'o1mini'

Stage 3: Fuzzy Match

Uses SkimMatcherV2 algorithm (minimum score: 50):

zo /sonet "test"   # Typo - fuzzy matches 'sonnet'
zo /gpt "test"     # Matches 'gpt4'
zo /claud "test"   # Matches 'claude' models

Did You Mean?

When model not found, zo suggests alternatives:

zo /sonnett "test"
# Error: Model 'sonnett' not found.
# 
# Did you mean:
#   sonnet -> anthropic/claude-sonnet-4.5 (score: 92)
#   sonnet3 -> anthropic/claude-3.5-sonnet (score: 85)
# 
# Available models:
#   sonnet, opus, haiku, flash, ...

Model Characteristics

Anthropic Claude Models

Claude Sonnet 4.5 (/sonnet)

Best for: Code, analysis, technical writing
Strengths: Reasoning, instruction following, code quality
Speed: Medium
Context: 200K tokens

Claude 3 Opus (/opus)

Best for: Complex tasks, highest quality
Strengths: Deep analysis, nuanced understanding
Speed: Slower
Context: 200K tokens

Claude 3 Haiku (/haiku)

Best for: Quick tasks, high volume
Strengths: Speed, cost efficiency
Speed: Fast
Context: 200K tokens

Google Gemini Models

Gemini 2.5 Flash (/flash) - Default

Best for: General use, balanced performance
Strengths: Speed, cost, quality balance
Speed: Very fast
Context: 1M tokens

Gemini 2.5 Pro (/geminipro)

Best for: Complex reasoning, large context
Strengths: Long context, multimodal
Speed: Medium
Context: 2M tokens

OpenAI Models

GPT-4 Turbo (/gpt4)

Best for: General intelligence tasks
Strengths: Versatility, knowledge
Speed: Medium
Context: 128K tokens

GPT-4o (/gpt4o)

Best for: Multimodal, optimized performance
Strengths: Speed, quality
Speed: Medium-fast
Context: 128K tokens

GPT-4o Mini (/gpt4omini)

Best for: Cost-effective GPT-4 access
Strengths: Speed, low cost
Speed: Fast
Context: 128K tokens

o1 (/o1)

Best for: Complex reasoning, math, coding
Strengths: Deep reasoning, problem solving
Speed: Slow
Cost: Very high
Context: 200K tokens

o1-mini (/o1mini)

Best for: Coding, STEM tasks
Strengths: Fast reasoning
Speed: Medium
Cost: High

X.AI Models

Grok 3 (/grok)

Best for: Real-time information
Strengths: Up-to-date knowledge
Speed: Medium
Context: 128K tokens

Model Selection Strategy

By Task Type

Code Review & Analysis:

zo /sonnet @code.rs "Review this code"

Quick Questions:

zo /flash "What is TCP?"
zo /haiku "Explain in one sentence"

Complex Reasoning:

zo /opus "Design a distributed system"
zo /o1 "Solve this algorithm problem"

Writing & Documentation:

zo /gpt4o @api.rs "Generate documentation"

Cost-Sensitive:

zo /flash "question"       # Cheapest, very good
zo /haiku "question"       # Cheap, fast
zo /gpt4omini "question"   # Cheap GPT-4

Quality-Critical:

zo /opus "important task"    # Highest quality Claude
zo /o1 "complex reasoning"   # Best reasoning

By Speed Need

Immediate (under 2 seconds):

/flash, /haiku, /gpt4omini

Balanced (2 to 5 seconds):

/sonnet, /gpt4o, /geminipro

Thorough (5 to 15 seconds):

/opus, /o1

By Context Size

Large Documents:

# Gemini has largest context
cat large_file.txt | zo /geminipro "Analyze"
cat huge_file.txt | zo /flash "Summarize"  # 1M context

Normal Use:

zo /sonnet @file.rs "Review"  # 200K context
zo /gpt4 @doc.md "Explain"    # 128K context

Custom Models

Define your own models with system prompts.

Configuration

# ~/.config/zo/config.toml
 
[[custom_models]]
name = "coder"
model = "anthropic/claude-sonnet-4.5"
system_prompt = "You are an expert programmer. Provide concise, well-commented code with error handling."
 
[[custom_models]]
name = "reviewer"
model = "anthropic/claude-sonnet-4.5"
system_prompt = "You are a senior code reviewer. Focus on bugs, performance, security, and best practices."
 
[[custom_models]]
name = "fast"
model = "google/gemini-3-flash-preview"
# No system prompt - just an alias

Using Custom Models

# Use just like built-in models
zo /coder "Implement a binary tree"
zo /reviewer @code.rs "Review this"
zo /fast "Quick question"

Custom Model Precedence

Custom models take precedence over built-in models at each matching stage:

# Override built-in 'pro'
[[custom_models]]
name = "pro"
model = "anthropic/claude-opus-4.5"

zo /pro "test"
# Uses your custom 'pro' (Opus), not built-in 'geminipro'

Listing Models

Show All Models

zo +list-models

Output:

Built-in models:
  sonnet -> anthropic/claude-sonnet-4.5
  opus -> anthropic/claude-opus-4.5
  haiku -> anthropic/claude-3-haiku
  flash -> google/gemini-2.5-flash
  ...
 
Custom models:
  coder -> anthropic/claude-sonnet-4.5
  reviewer -> anthropic/claude-sonnet-4.5
  fast -> google/gemini-2.5-flash

Filter Models

zo +list-models | grep claude
zo +list-models | grep google
zo +list-models | grep custom

Debug Mode

Verify model selection before sending request:

zo --debug /sonnet "test"

Output:

Model: sonnet (anthropic/claude-sonnet-4.5)
Prompt: test
Send request? [y/N]

With custom model:

zo --debug /coder "test"

Output:

Model: coder (anthropic/claude-sonnet-4.5)
System Prompt: You are an expert programmer...
Prompt: test
Send request? [y/N]

Best Practices

Start Fast, Scale Up

# Try with fast model first
zo /flash "question"
 
# If insufficient, use smarter model
zo /sonnet "question"
 
# For critical tasks, use best
zo /opus "question"

Match Model to Task

# ❌ Overkill
zo /opus "What is 2+2?"
 
# ✅ Appropriate
zo /flash "What is 2+2?"
 
# ❌ Underpowered
zo /haiku "Design a complex distributed system"
 
# ✅ Appropriate
zo /opus "Design a complex distributed system"

Use Chat for Iteration

# Start with good model
zo --chat /sonnet "Let's build a feature"
> Refine the approach
> Add error handling
> exit

Create Task-Specific Models

[[custom_models]]
name = "security"
model = "anthropic/claude-opus-4.5"
system_prompt = "Security expert. Analyze for vulnerabilities, attack vectors, and provide mitigation strategies."
 
[[custom_models]]
name = "perf"
model = "anthropic/claude-sonnet-4.5"
system_prompt = "Performance expert. Focus on optimization, profiling, and benchmarking."

Troubleshooting

Model Not Found

# Check available models
zo +list-models
 
# Use exact name from list
zo /sonnet "test"
 
# Or use fuzzy matching
zo /son "test"

Wrong Model Selected

# Use CLI flag to override
zo --model opus "test"
 
# Or be more specific
zo /claude-opus "test"

Verify Selection

# Always use debug mode when unsure
zo --debug /model "test"

Quick Reference

Built-in Model Shortcuts

Using Models

Slash Command

CLI Flag

Config Default

Priority Order

Fuzzy Matching

Stage 1: Exact Match (case-insensitive)

Stage 2: Substring Match

Stage 3: Fuzzy Match

Did You Mean?

Model Characteristics

Anthropic Claude Models

Google Gemini Models

OpenAI Models

X.AI Models

Model Selection Strategy

By Task Type

By Speed Need

By Context Size

Custom Models

Configuration

Using Custom Models

Custom Model Precedence

Listing Models

Show All Models

Filter Models

Debug Mode

Best Practices

Start Fast, Scale Up

Match Model to Task

Use Chat for Iteration

Create Task-Specific Models

Troubleshooting

Model Not Found

Wrong Model Selected

Verify Selection

Next Steps