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

You configure custom agent tiers by editing docs/shared/agent-tiers.md to define cost and reasoning levels, then map specific roles and model families within 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 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): Control cost and reasoning depth through three levels—LOW (fast lookups), STANDARD (default implementation), and THOROUGH (architectural/security-sensitive work).
• Model Routing (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, 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 (lines 15-27). The matrix assigns default reasoning levels to specific agent roles:

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

- `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 (lines 77-79):

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:

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 (lines 103-108) maps task complexity to default model families:

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

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

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.

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 (lines 31-41):

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

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 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 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 (lines 15-27). This file contains the selection rules that map roles like executor, writer, and architect to their default reasoning levels. 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 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.

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