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

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, 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. 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 (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 – Contains the central tier matrix, model routing guide, and the canonical mapping between complexity levels and Claude models.
• 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 – Explains how complexity tiers influence mode decisions (autopilot vs. team vs. ralph).
• agents/*.md (e.g., executor.md, 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:

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:

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:

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):

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 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.

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

The canonical mapping resides in 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.

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