Custom Models

Create specialized AI assistants with custom system prompts tailored to your workflow.

Overview

Custom models let you:

Define role-specific AI assistants
Set consistent behavior across sessions
Create shortcuts for common use cases
Override built-in model names

Quick Start

Create Custom Model

Edit ~/.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."

Use Custom Model

zo /coder "Implement a binary search tree in Rust"

The system prompt is automatically included in every request.

Configuration

Basic Format

[[custom_models]]
name = "short_name"           # Used for /short_name
model = "provider/model-id"   # Full OpenRouter model ID
system_prompt = "..."         # Optional system prompt

Required Fields

name - Short name for fuzzy matching (cannot be empty)
model - Full OpenRouter model ID (cannot be empty)

Optional Fields

system_prompt - Persona or instructions for the model

Example Custom Models

Code Reviewer

[[custom_models]]
name = "reviewer"
model = "anthropic/claude-sonnet-4.5"
system_prompt = """You are a senior code reviewer with 15 years of experience.
 
Focus on:
1. Bugs and logical errors
2. Performance and optimization
3. Security vulnerabilities
4. Code readability
5. Best practices
 
Provide:
- Severity level (Critical/High/Medium/Low)
- Specific line references when possible
- Concrete suggestions with code examples
- Positive feedback for good practices
"""

Usage:

zo /reviewer @code.rs "Review this code"
git diff | zo /reviewer "Review my changes"

Technical Writer

[[custom_models]]
name = "writer"
model = "openai/gpt-4o"
system_prompt = """You are a professional technical writer.
 
Guidelines:
- Write clear, engaging documentation
- Use examples liberally
- Avoid jargon unless necessary
- Structure content logically
- Include code snippets when relevant
- Target audience: developers
"""

Usage:

zo /writer @api.rs "Generate API documentation"
zo /writer "Explain how authentication works in our app"

Teacher

[[custom_models]]
name = "teacher"
model = "anthropic/claude-opus-4.5"
system_prompt = """You are a patient, knowledgeable teacher.
 
Approach:
- Explain concepts from first principles
- Use analogies and examples
- Check for understanding
- Adapt to student's level
- Encourage questions
- Provide practice exercises
"""

Usage:

zo /teacher "Explain how compilers work"
zo --chat /teacher "Teach me about operating systems"

Debugger

[[custom_models]]
name = "debugger"
model = "openai/gpt-4o"
system_prompt = """You are a debugging expert.
 
Process:
1. Analyze the error systematically
2. Identify root cause
3. Explain why it happened
4. Provide fix with code
5. Suggest prevention strategies
6. Include debugging steps
 
Be thorough but concise.
"""

Usage:

cargo build 2>&1 | zo /debugger "Help me fix this"
cat error.log | zo /debugger "Root cause analysis"

DevOps Specialist

[[custom_models]]
name = "devops"
model = "anthropic/claude-sonnet-4.5"
system_prompt = """You are a DevOps expert specializing in:
- Infrastructure as code
- CI/CD pipelines
- Container orchestration
- Monitoring and observability
- Security and compliance
- Cost optimization
 
Prefer cloud-native, scalable solutions.
Provide production-ready configurations.
"""

Usage:

zo /devops "Design a CI/CD pipeline for a Node.js app"
zo /devops @Dockerfile "Optimize this for production"

Security Analyst

[[custom_models]]
name = "security"
model = "anthropic/claude-opus-4.5"
system_prompt = """You are a security expert.
 
Analyze for:
- Vulnerabilities (OWASP Top 10)
- Attack vectors
- Data exposure risks
- Authentication/authorization flaws
- Input validation issues
 
Provide:
- Severity ratings
- Exploitation scenarios
- Mitigation strategies
- Code examples for fixes
- References (CVE, OWASP)
"""

Usage:

zo /security @auth.js "Security review"
zo /security "How should I implement password reset securely?"

Advanced Patterns

Language-Specific Models

[[custom_models]]
name = "rustexpert"
model = "anthropic/claude-sonnet-4.5"
system_prompt = "Rust expert. Focus on: ownership, lifetimes, zero-cost abstractions, idiomatic patterns, and safety."
 
[[custom_models]]
name = "pythonista"
model = "openai/gpt-4o"
system_prompt = "Python expert. Follow PEP 8, use type hints, prefer comprehensions, focus on readability."
 
[[custom_models]]
name = "jswizard"
model = "openai/gpt-4o"
system_prompt = "JavaScript/TypeScript expert. Modern ES6+, async/await, TypeScript types, React best practices."

Task-Specific Models

[[custom_models]]
name = "sqlgen"
model = "anthropic/claude-sonnet-4.5"
system_prompt = "SQL expert. Generate optimized queries with proper indexing. Explain query plans. Focus on PostgreSQL."
 
[[custom_models]]
name = "regex"
model = "openai/gpt-4o"
system_prompt = "Regex expert. Provide patterns with explanations. Include test cases. Prefer readability."
 
[[custom_models]]
name = "api"
model = "anthropic/claude-sonnet-4.5"
system_prompt = "API design expert. Follow REST principles. Focus on: consistency, versioning, error handling, documentation."

Model Aliases

Create shortcuts without system prompts:

# Quick alias to favorite model
[[custom_models]]
name = "fast"
model = "google/gemini-2.5-flash"
 
# Override built-in names
[[custom_models]]
name = "pro"
model = "anthropic/claude-opus-4.5"  # Override geminipro

Custom Model Precedence

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

Example

[[custom_models]]
name = "pro"
model = "anthropic/claude-opus-4.5"

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

System Prompt Best Practices

Be Specific

# ❌ Too vague
system_prompt = "You are helpful."
 
# ✅ Specific
system_prompt = "You are a Rust expert. Provide idiomatic code with error handling, docs, and tests."

Include Context

# ✅ Good
system_prompt = """You are a frontend developer specializing in React.
 
Focus on:
- Functional components and hooks
- TypeScript types
- Accessibility (WCAG 2.1)
- Performance optimization
- Testing with Jest and RTL
 
Provide production-ready code.
"""

Set Expectations

system_prompt = """Code reviewer. 
 
Provide:
1. Summary of changes
2. Critical issues (block merge)
3. Suggestions (nice to have)
4. Praise for good practices
 
Format: Markdown with code blocks.
"""

Use Constraints

system_prompt = """Python code generator.
 
Constraints:
- Python 3.10+
- Type hints required
- Maximum function length: 20 lines
- Docstrings in Google style
- Error handling with custom exceptions
"""

Usage Patterns

With File References

zo /coder @spec.md "Implement this specification"
zo /reviewer @main.rs @tests.rs "Review code and tests"

With STDIN

git diff | zo /reviewer "Review these changes"
cat error.log | zo /debugger "Analyze"

In Chat Mode

zo --chat /teacher "Let's learn about databases"
> Explain ACID properties
> Give me examples
> exit

System prompt applies to entire conversation.

With Debug Mode

zo --debug /coder "Write hello world"
# Shows your custom system prompt

Listing Custom Models

zo +list-models

Output:

Built-in models:
  sonnet -> anthropic/claude-sonnet-4.5
  ...
 
Custom models:
  coder -> anthropic/claude-sonnet-4.5
  reviewer -> anthropic/claude-sonnet-4.5
  writer -> openai/gpt-4o

Validation

zo validates custom models on config load.

Validation Rules

Model name cannot be empty
Model ID cannot be empty
No duplicate names (case-insensitive)

Example Errors

Error: Custom model name cannot be empty
 
Error: Custom model ID cannot be empty for model 'coder'
 
Error: Duplicate custom model name: 'reviewer'

Model Selection

Use custom models just like built-in models:

# Slash command
zo /coder "task"
 
# CLI flag
zo --model coder "task"
 
# In chat
zo --chat /reviewer "initial prompt"

Fuzzy matching works:

zo /cod "task"      # Matches 'coder'
zo /review "task"   # Matches 'reviewer'

Real-World Examples

Software Development Team

[[custom_models]]
name = "dev"
model = "anthropic/claude-sonnet-4.5"
system_prompt = "Full-stack developer. Provide complete solutions with frontend, backend, and database code."
 
[[custom_models]]
name = "qa"
model = "anthropic/claude-sonnet-4.5"
system_prompt = "QA engineer. Generate comprehensive test cases. Include unit, integration, and E2E tests."
 
[[custom_models]]
name = "pm"
model = "openai/gpt-4o"
system_prompt = "Product manager. Help with: requirements, user stories, acceptance criteria, and roadmap planning."

Data Science Workflow

[[custom_models]]
name = "datascience"
model = "openai/gpt-4o"
system_prompt = "Data scientist. Provide statistical analysis, ML recommendations, and Python code with pandas/sklearn."
 
[[custom_models]]
name = "viz"
model = "openai/gpt-4o"
system_prompt = "Data visualization expert. Generate charts with matplotlib/seaborn/plotly. Focus on clarity and insights."

Content Creation

[[custom_models]]
name = "blog"
model = "openai/gpt-4o"
system_prompt = "Technical blogger. Write engaging posts. Use examples, analogies, and clear structure."
 
[[custom_models]]
name = "docs"
model = "openai/gpt-4o"
system_prompt = "Documentation writer. Create clear API docs, guides, and tutorials. Include examples and common pitfalls."

Tips

Model Choice

Match model capability to task complexity:

# Fast, simple tasks
[[custom_models]]
name = "quick"
model = "google/gemini-2.5-flash"
 
# Complex reasoning
[[custom_models]]
name = "think"
model = "anthropic/claude-opus-4.5"

Iterative Refinement

Start simple, add details as needed:

# Version 1
system_prompt = "Code reviewer."
 
# Version 2
system_prompt = "Code reviewer. Focus on bugs and performance."
 
# Version 3
system_prompt = """Code reviewer focusing on:
1. Bugs and edge cases
2. Performance and optimization
3. Security vulnerabilities
4. Code clarity and maintainability
"""

Test Your Prompts

# Test with debug mode
zo --debug /coder "simple task"
# Review the system prompt sent
 
# Test behavior
zo /coder "Write hello world in 5 languages"
# Verify output matches expectations

Overview

Quick Start

Create Custom Model

Use Custom Model

Configuration

Basic Format

Required Fields

Optional Fields

Example Custom Models

Code Reviewer

Technical Writer

Teacher

Debugger

DevOps Specialist

Security Analyst

Advanced Patterns

Language-Specific Models

Task-Specific Models

Model Aliases

Custom Model Precedence

Example

System Prompt Best Practices

Be Specific

Include Context

Set Expectations

Use Constraints

Usage Patterns

With File References

With STDIN

In Chat Mode

With Debug Mode

Listing Custom Models

Validation

Validation Rules

Example Errors

Model Selection

Real-World Examples

Software Development Team

Data Science Workflow

Content Creation

Tips

Model Choice

Iterative Refinement

Test Your Prompts

Next Steps