# How to Configure Custom Agent Tiers and Model Routing in oh-my-codex AGENTS.md

> Learn to configure custom agent tiers and model routing in oh-my-codex. Define cost and reasoning levels and map models using AGENTS.md for efficient AI agent management.

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

---

**You configure custom agent tiers by editing [`docs/shared/agent-tiers.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/shared/agent-tiers.md) to define cost and reasoning levels, then map specific roles and model families within [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) using the `<model_routing>` block, environment variables, or per-delegation `model=` overrides.**

The `oh-my-codex` repository implements an omni-agent orchestration layer (OMX) that separates **how much** reasoning power a task consumes from **which** underlying LLM executes it. By mastering the relationship between [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) and the tier matrix, you can precisely control agent behavior across lightweight lookups and complex architectural reviews.

## Understanding the Tier and Routing Architecture

The framework operates through two orthogonal mechanisms defined in separate files:

- **Agent Tiers** ([`docs/shared/agent-tiers.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/shared/agent-tiers.md)): Control cost and reasoning depth through three levels—`LOW` (fast lookups), `STANDARD` (default implementation), and `THOROUGH` (architectural/security-sensitive work).
- **Model Routing** ([`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md)): Determines which LLM family (frontier, spark, etc.) handles tasks for each tier or role.

When you configure custom agent tiers and model routing in oh-my-codex [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md), you create a mapping that resolves first through explicit delegation parameters, then role overrides, then global defaults.

## Customizing Agent Tiers in docs/shared/agent-tiers.md

The canonical tier definitions live in **[`docs/shared/agent-tiers.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/shared/agent-tiers.md)** (lines 15-27). The matrix assigns default reasoning levels to specific agent roles:

```markdown

## Tiers

- `LOW`: Fast look‑ups, style checks, lightweight doc edits.
  Typical roles: `explore`, `style‑reviewer`, `writer`.
- `STANDARD`: Default tier for implementation, debugging, normal verification.
  Typical roles: `executor`, `debugger`, `test‑engineer`, `quality‑reviewer`.
- `THOROUGH`: Architectural, security‑sensitive, high‑impact multi‑file work.
  Typical roles: `architect`, `critic`, `security‑reviewer`, `executor`.

```

To customize the matrix, edit the **Selection Rules** or **Typical roles** sections. For example, to promote heavy documentation work to `STANDARD` reasoning:

```markdown
- `STANDARD`:
  …
  Typical roles: `executor`, `debugger`, `test-engineer`, `quality-reviewer`, **`writer`**

```

Once committed, every subsequent delegation that omits an explicit `tier=` parameter inherits the updated default according to the role.

## Declaring Tiers in Delegation Calls

Individual skill files override the matrix through inline delegation syntax. The general form appears in **[`skills/ultrawork/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/skills/ultrawork/SKILL.md)** (lines 77-79):

```yaml
delegate(role="executor", tier="LOW", task="Add missing type export for Config interface")

```

To force maximum reasoning depth for a critical refactor, specify the `THOROUGH` tier explicitly:

```yaml
delegate(role="architect", tier="THOROUGH", task="Design migration path for DB schema")

```

This per-delegation declaration takes precedence over the global tier matrix but still respects the model routing rules unless you also supply a `model=` override.

## Configuring Model Routing in AGENTS.md

The **`<model_routing>`** block in [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) (lines 103-108) maps task complexity to default model families:

```markdown
<model_routing>
Match role to task shape:
- Low complexity: `explore`, `style‑reviewer`, `writer`
- Standard: `executor`, `debugger`, `test‑engineer`
- High complexity: `architect`, `executor`, `critic`
</model_routing>

```

To override the default model for a specific delegation, pass the `model=` attribute with either a literal model name or an environment variable expansion:

```yaml
delegate(
  role="security-reviewer",
  tier="THOROUGH",
  model="${OMX_DEFAULT_FRONTIER_MODEL}",
  task="Audit authentication flow"
)

```

The `${...}` syntax keeps configurations DRY by referencing central environment definitions.

## Setting Global Model Defaults via Environment Variables

The framework checks three environment variables to establish base model selections. Define these in a repository root `.env` file (already `.gitignore`d) to avoid committing secrets:

| Variable | Purpose |
|----------|---------|
| `OMX_DEFAULT_FRONTIER_MODEL` | Default frontier-orchestrator model (e.g., `gpt-5.4`) |
| `OMX_DEFAULT_SPARK_MODEL` | Default spark (fast-lane) model |
| `OMX_TEAM_WORKER_LAUNCH_ARGS` | Per-worker model overrides for team mode |

Example configuration:

```dotenv
OMX_DEFAULT_FRONTIER_MODEL=gpt-5.4
OMX_DEFAULT_SPARK_MODEL=gpt-4o-mini

```

When a delegation specifies a tier but omits the `model=` parameter, the OMX engine resolves the tier to these environment variables according to the fallback logic defined in [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md).

## Complete Configuration Example

The following skill file demonstrates a progressive tier strategy with explicit model routing, following the pattern established in **[`skills/ultrawork/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/skills/ultrawork/SKILL.md)** (lines 31-41):

```yaml

# skills/custom-doc-update/SKILL.md

---
title: "Update Project Documentation"
---

# Step 1 – Gather current docs (LOW tier, fast model)

delegate(role="explore", tier="LOW", task="Search ./docs for existing API reference sections")

# Step 2 – Write new section (STANDARD tier)

delegate(role="writer", tier="STANDARD", task="Add detailed usage examples for the new CLI command")

# Step 3 – Review for consistency (THOROUGH tier, explicit frontier model)

delegate(
  role="architect",
  tier="THOROUGH",
  model="${OMX_DEFAULT_FRONTIER_MODEL}",
  task="Audit the whole docs set for cross‑reference integrity"
)

```

For security-critical reviews, bypass environment defaults with a literal model assignment:

```yaml
delegate(
  role="security-reviewer",
  tier="THOROUGH",
  model="gpt-5.4",
  task="Run static analysis on the new OAuth2 implementation"
)

```

## Summary

- Edit **[`docs/shared/agent-tiers.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/shared/agent-tiers.md)** to establish custom tier policies and role mappings.
- Use the **`tier="..."`** parameter in delegation calls to override defaults for specific tasks.
- Configure global model defaults via **`OMX_DEFAULT_FRONTIER_MODEL`** and **`OMX_DEFAULT_SPARK_MODEL`** in `.env`.
- Override per-delegation routing with the **`model="..."`** attribute, supporting environment variable expansion.
- Document project-specific mappings directly in **[`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md)** to maintain clarity across team workflows.

## Frequently Asked Questions

### What is the difference between agent tiers and model routing in oh-my-codex?

Agent tiers define **how much** reasoning depth a task receives (`LOW`, `STANDARD`, or `THOROUGH`), primarily affecting cost and latency. Model routing determines **which** LLM family (frontier vs. spark) executes the task. According to the source code, these operate orthogonally: a `THOROUGH` tier task could run on a spark model if explicitly configured, though it typically maps to frontier models.

### How do I force a specific LLM model for a single delegation task?

Pass the `model=` attribute in the delegate call with either a literal string or environment variable syntax. For example: `model="gpt-5.4"` or `model="${OMX_DEFAULT_FRONTIER_MODEL}"`. This override takes precedence over both the tier matrix and global environment defaults.

### Where are the default tier definitions stored?

The canonical tier definitions reside in **[`docs/shared/agent-tiers.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/shared/agent-tiers.md)** (lines 15-27). This file contains the selection rules that map roles like `executor`, `writer`, and `architect` to their default reasoning levels. [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) then references these tiers when resolving delegation calls.

### Can I customize tier assignments for specific roles without changing skill files?

Yes. Modify the **Typical roles** lists in [`docs/shared/agent-tiers.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/shared/agent-tiers.md) to reassign roles to different tiers globally. For example, moving `writer` from `LOW` to `STANDARD` ensures all future `delegate(role="writer")` calls without explicit tier parameters automatically use the higher reasoning level.