# How the Tiered Agent System Routes Haiku, Sonnet, and Opus Based on Task Complexity in Oh-My-ClaudeCode

> Explore how Oh-My-ClaudeCode's tiered agent system uses Haiku Sonnet and Opus to route tasks by complexity Learn how complexity tiers automatically select the right model for your coding needs

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

---

**Oh-My-ClaudeCode routes every task through Haiku, Sonnet, or Opus by classifying requests into LOW, MEDIUM, or HIGH complexity tiers defined in [`docs/shared/agent-tiers.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/docs/shared/agent-tiers.md), automatically selecting the appropriate model when spawning sub-agents if the caller omits the `model` field.**

The **tiered agent system** in Oh-My-ClaudeCode (omc) optimizes cost and performance by matching computational intensity to the specific Claude model best suited for the job. Instead of defaulting to the most powerful model for every operation, the orchestration layer analyzes task requirements and assigns complexity tiers that map directly to Haiku for quick lookups, Sonnet for standard development work, and Opus for architectural overhauls.

## The Three-Tier Complexity Classification

The routing logic centers on a strict three-tier classification system documented in **[`docs/shared/agent-tiers.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/docs/shared/agent-tiers.md)**. Each tier corresponds to a specific model and typical workload:

| Complexity | Tier | Model | Typical Use Case |
|------------|------|-------|------------------|
| Simple lookups, quick fixes, single-symbol questions | **LOW** | **haiku** | One-line answers, tiny edits, symbol look-ups |
| Standard feature work, normal debugging, moderate refactors | **MEDIUM** | **sonnet** | Full-stack implementation, typical reasoning tasks |
| Architectural decisions, deep refactoring, multi-module changes | **HIGH** | **opus** | Large-scale design, complex system-wide changes |

This mapping is consulted by every operational mode—autopilot, team, ralph, and others—when creating sub-agents. The **Model Routing Guide** table in [`docs/shared/agent-tiers.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/docs/shared/agent-tiers.md) (lines 27-31) serves as the single source of truth for agent instantiation across the entire codebase.

## How the Routing Flow Works

When the orchestration layer receives a request, it executes a four-step routing flow to determine the appropriate model:

1. **Determine task complexity** – The planner or mode-selection guide evaluates the request based on prompt length, required reasoning depth, and number of files involved.
2. **Select tier** – Based on this evaluation, the system assigns **LOW**, **MEDIUM**, or **HIGH**.
3. **Choose model** – The tier translates directly to **haiku**, **sonnet**, or **opus** using the routing table.
4. **Instantiate the agent** – The `Task` constructor receives the `subagent_type`, explicit or inferred `model`, and the prompt.

If a caller instantiates a `Task` without specifying the `model` parameter, the orchestrator inspects the prompt characteristics and the agent's default tier to select the appropriate model automatically.

## Key Configuration Files

The tiered routing system is decentralized across several documentation files that define behavior for different agent types:

- **[`docs/shared/agent-tiers.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/docs/shared/agent-tiers.md)** – Contains the central tier matrix, model routing guide, and the canonical mapping between complexity levels and Claude models.
- **[`docs/TIERED_AGENTS_V2.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/docs/TIERED_AGENTS_V2.md)** – Provides a high-level overview of how the tier system integrates with the broader Oh-My-ClaudeCode architecture.
- **[`docs/shared/mode-selection-guide.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/docs/shared/mode-selection-guide.md)** – Explains how complexity tiers influence mode decisions (autopilot vs. team vs. ralph).
- **`agents/*.md`** (e.g., [`executor.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/executor.md), [`architect.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/architect.md)) – Each agent's documentation references the tier table to justify its default model selection.

According to the Oh-My-ClaudeCode source, all agents including explore, executor, and architect reference this centralized table, ensuring consistent routing logic throughout the system.

## Implementation Examples

The `Task` constructor accepts a `model` parameter that enforces tier selection. Below are concrete examples from the codebase showing how different complexity levels map to specific models.

### Simple Lookup (Low-Tier / Haiku)

For trivial lookups requiring minimal reasoning, explicitly specify `haiku` or rely on the default low-tier classification:

```ts
Task(
  subagent_type="oh-my-claudecode:explore",
  model="haiku",                 // explicitly selected for simple look-ups
  prompt="What does the function `sum` return for input [1,2,3]?"
)

```

### Feature Implementation (Medium-Tier / Sonnet)

Standard development work requiring moderate reasoning uses the `sonnet` model:

```ts
Task(
  subagent_type="oh-my-claudecode:executor",
  model="sonnet",                // standard tier for feature work
  prompt="""
    Implement a new endpoint `/api/users` that returns a paginated list of users.
    Add validation for the `page` query parameter.
  """
)

```

### Complex Refactor (High-Tier / Opus)

Large-scale architectural changes requiring deep reasoning instantiate the `opus` model:

```ts
Task(
  subagent_type="oh-my-claudecode:executor-high",
  model="opus",                  // high tier for large-scale refactoring
  prompt="""
    Refactor the authentication module to use JWTs, migrate all stored sessions,
    and update every consumer of the auth API accordingly.
  """
)

```

### Automatic Model Selection

When the `model` field is omitted, the orchestrator applies the routing logic automatically based on the agent's default tier. An architect agent defaults to MEDIUM (Sonnet):

```ts
Task(
  subagent_type="oh-my-claudecode:architect",   // tier = MEDIUM → sonnet
  prompt="Design a micro-service architecture for a chat app."
)

```

## Summary

- Oh-My-ClaudeCode uses a **three-tier complexity system** (LOW, MEDIUM, HIGH) defined in [`docs/shared/agent-tiers.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/docs/shared/agent-tiers.md) to route tasks efficiently.
- **Haiku** handles LOW complexity (simple lookups), **Sonnet** handles MEDIUM (standard features), and **Opus** handles HIGH (architectural refactors).
- The **routing flow** evaluates task characteristics, selects a tier, maps it to a model, and instantiates the agent via the `Task` constructor.
- Callers can **explicitly set** the `model` parameter or leave it empty to let the orchestrator choose based on the agent's default tier.
- All operational modes and agent types reference the centralized tier matrix to maintain consistent routing behavior.

## Frequently Asked Questions

### How does Oh-My-ClaudeCode decide which complexity tier to assign?

The orchestration layer evaluates prompt length, required reasoning depth, and the number of files affected by the change. Simple questions with single-file scope default to LOW, standard feature work across multiple files defaults to MEDIUM, and system-wide architectural changes default to HIGH.

### Can I override the automatic model selection?

Yes. When creating a `Task`, explicitly set the `model` parameter to `"haiku"`, `"sonnet"`, or `"opus"` to bypass automatic tier detection. If the parameter is omitted, the system inspects the `subagent_type` and prompt characteristics to apply the default tier mapping from [`docs/shared/agent-tiers.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/docs/shared/agent-tiers.md).

### Where is the source of truth for the tier-to-model mapping?

The canonical mapping resides in **[`docs/shared/agent-tiers.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/docs/shared/agent-tiers.md)** at lines 27-31. This file defines the Model Routing Guide table used by all agent types (explore, executor, architect) and operational modes (autopilot, team, ralph) to ensure consistent model selection across the codebase.

### What happens if I use a high-tier agent for a simple task?

While functionally possible, instantiating an `executor-high` agent (defaulting to Opus) for trivial lookups wastes computational resources and increases latency. The tiered system is designed to optimize both performance and cost by matching model capability to actual task requirements as defined in the routing configuration.