How Model Routing Matches Roles to Task Complexity in oh-my-codex

oh-my-codex uses a three-tier complexity system to automatically route tasks to appropriate LLM models based on whether the role is explore, executor, or architect.

The model routing system in oh-my-codex optimizes both cost and performance by mapping specific agent roles to task complexity levels. This alignment ensures lightweight file operations run on fast, inexpensive models while architectural deep-dives receive maximum reasoning capability.

The Complexity-to-Role Mapping

The routing logic is defined in AGENTS.md within the <model_routing> section (lines 100-109). The system categorizes every child-agent into one of three complexity tiers based on its assigned role:

Low Complexity

• Roles: explore, style-reviewer, writer
• Typical workload: File-system walks, quick look-ups, superficial text-style checks
• Model tier: Cheaper, faster models (e.g., gpt-3.5-turbo)

Standard Complexity

• Roles: executor, debugger, test-engineer
• Typical workload: Code edits, bug fixes, test authoring, moderate reasoning
• Model tier: Repository-default models (typically gpt-4-turbo)

High Complexity

• Roles: architect, executor, critic
• Typical workload: Deep design analysis, architectural trade-offs, extensive critique
• Model tier: High-capability models with larger context windows

According to the source code, the system defaults to inheriting repository-wide model settings unless a caller explicitly overrides the assignment.

How Model Routing Works Internally

The orchestration layer follows a five-step pipeline to match tasks to models:

1. Skill invocation: The user triggers a role via skill keywords like $explore, $executor, or $architect followed by a natural language prompt.

2. Leader parsing: The leader agent parses the command and identifies the target role from the skill directive.

3. Table lookup: The role name is matched against the <model_routing> table in AGENTS.md to determine the complexity tier.

4. Model assignment: The child-agent launches with the default model for that tier. Native Codex agents inherit the repository default unless explicitly overridden.

5. Execution and return: The agent executes its specialized task and returns evidence-rich output for leader verification.

Practical Routing Examples

Low Complexity: File Exploration

Use the explore role for inexpensive, high-speed file system operations:

# Runs on the low-tier model for cost efficiency

omx explore --prompt "List every *.md file in the repository"

Or via inline skill syntax:

$explore "list all *.ts files in src/components"

This routes to fast models defined in prompts/explore.md, optimized for breadth-first searches rather than deep analysis.

Standard Complexity: Code Execution

The executor role handles modifications requiring reliable reasoning but not architectural overhaul:

# Applies refactoring using the standard model tier

$executor "Rename variable `cnt` to `count` in src/utils.ts"

As defined in prompts/executor.md, this role receives the repository-default model configuration, balancing accuracy with cost for routine development tasks.

High Complexity: Architectural Analysis

Reserve the architect role for tasks requiring extensive context comprehension and design evaluation:

# Consumes high-tier model resources for deep analysis

$architect "Assess the scalability of the current event-bus implementation"

According to prompts/architect.md, this role performs read-only analysis with file-line citations and trade-off documentation, justified by the larger context windows available to high-complexity models.

Key Configuration Files

The routing system depends on these specific files:

• AGENTS.md (lines 100-109): Contains the central <model_routing> contract that maps roles to complexity tiers
• prompts/explore.md: Defines the low-complexity exploration role and its system prompts
• prompts/executor.md: Specifies the standard-complexity execution role responsibilities
• prompts/architect.md: Details the high-complexity architectural analysis workflow

Summary

• oh-my-codex matches model selection to task complexity through a three-tier routing system defined in AGENTS.md.
• Low-complexity roles (explore, style-reviewer) run on economical models for file system operations.
• Standard-complexity roles (executor, debugger) use repository-default models for code modifications.
• High-complexity roles (architect, critic) receive premium models with extended context for design analysis.
• The system automatically selects appropriate tiers when users invoke skills via $role syntax, requiring no manual model configuration.

Frequently Asked Questions

What determines which model tier an agent receives?

The role name invoked by the user determines the tier. When you prefix a command with $explore, $executor, or $architect, the orchestration layer looks up that role in the <model_routing> table of AGENTS.md and assigns the corresponding low, standard, or high complexity model configuration.

Can I override the automatic model selection for a specific role?

Yes. While the system defaults to the repository-wide model settings or the tier-appropriate default, callers can explicitly override the model assignment when spawning child-agents. However, native Codex agents typically inherit the default unless specifically configured otherwise in the execution context.

Why is the executor role listed under both standard and high complexity?

The executor role appears in both tiers because task complexity can vary based on context. Simple refactors may use standard models, while extensive multi-file edits or complex bug fixes may be classified as high-complexity executions requiring larger context windows and more sophisticated reasoning capabilities.

How does model routing improve cost efficiency?

By routing superficial tasks like file listing (explore) to cheaper models (e.g., gpt-3.5-turbo) while reserving expensive high-capability models (e.g., gpt-4-turbo) for architectural analysis (architect), oh-my-codex minimizes token costs for routine operations without sacrificing intelligence where it matters most.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}