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

> Discover how oh-my-codex model routing matches roles explore executor architect to task complexity. Learn to optimize LLM model selection for your coding needs.

- Repository: [Bellman/oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
- Tags: architecture
- Published: 2026-04-03

---

**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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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:

```bash

# 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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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:

```bash

# Applies refactoring using the standard model tier

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

```

As defined in [`prompts/executor.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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:

```bash

# Consumes high-tier model resources for deep analysis

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

```

According to [`prompts/architect.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md)** (lines 100-109): Contains the central `<model_routing>` contract that maps roles to complexity tiers
- **[`prompts/explore.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/prompts/explore.md)**: Defines the low-complexity exploration role and its system prompts
- **[`prompts/executor.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/prompts/executor.md)**: Specifies the standard-complexity execution role responsibilities
- **[`prompts/architect.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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.