How to Set Up Subagents with Codex Mini

Mar 23, 2026

Why I Started Using Subagents

When I first started working with Codex, I treated every task the same way—delegating everything to the most powerful model available. This worked fine for small projects, but as my codebase grew and my tasks multiplied, I noticed the costs climbing and the response times slowing down. I needed a better approach.

That’s when I discovered subagents. The idea is simple: instead of using a single agent for everything, you create specialized agents for different types of work. Mini handles the volume, while the full model handles complexity. The result? I reduced my costs by 60-80% compared to using full models for everything.

What Are Codex Subagents?

Subagents are specialized AI workers that operate under the control of a main orchestrator agent. Each subagent is configured with a specific role, model, and set of allowed tools. The orchestrator analyzes incoming tasks and routes them to the most appropriate subagent.

The beauty of this architecture lies in its flexibility. You can create subagents for almost any purpose—code exploration, research, testing, feature implementation, or even domain-specific work like frontend development.

I found that the most effective setups include these agent types:

Agent Type	Model	Role	Tools
worker-mini	codex-mini	Simple tasks, boilerplate, tests	Write, Edit, Read
worker-high	codex-5.4	Complex features, debugging	All tools
explorer	codex-mini/spark	Codebase exploration	Read, Glob, Grep
researcher	codex-5.4	Research with MCP tools	WebFetch, WebSearch

The worker-mini is my workhorse. I only use it as a subagent, and it’s great for the tasks it does—generating boilerplate code, writing simple tests, and handling repetitive edits. For anything requiring deeper reasoning or complex decision-making, I rely on worker-high.

Configuring Your Subagents

The configuration process is straightforward. You can let Codex auto-configure by pointing it to the official documentation, or you can set up the files yourself for more control.

Option 1: Auto-Configuration

Point Codex to the official subagent documentation:

https://developers.openai.com/codex/subagents

When it’s done, restart Codex. The orchestrator will automatically detect and load your subagent configurations.

Option 2: Manual Configuration

For more control, I prefer creating the configuration files myself. Here’s a sample configuration that covers most use cases:

subagents:
  - name: worker-mini
    model: codex-mini
    role: |
      You are a fast, efficient worker for simple tasks.
      Focus on boilerplate, tests, and straightforward edits.
      Always report back with clear summaries.
    tools:
      - Write
      - Edit
      - Read
      - Glob
      - Grep

  - name: worker-high
    model: codex-5.4
    role: |
      You are a senior engineer for complex tasks.
      Handle feature implementation, debugging, and architectural decisions.
      Think through problems carefully before acting.
    tools:
      - Write
      - Edit
      - Read
      - Bash
      - Glob
      - Grep
      - WebFetch
      - WebSearch

  - name: explorer
    model: codex-spark
    role: |
      You are a read-only codebase explorer.
      Analyze code structure, find patterns, and report findings.
      Never modify any files.
    tools:
      - Read
      - Glob
      - Grep

  - name: researcher
    model: codex-5.4
    role: |
      You are a research specialist.
      Use web tools to gather information and synthesize findings.
      Provide comprehensive research reports.
    tools:
      - WebFetch
      - WebSearch
      - Read

How Subagents Work in Practice

When I ask Codex to explore how a feature works, the orchestrator spawns an agent with mini-xhigh to handle that task. The routing happens automatically based on the nature of my request.

Here’s what makes this architecture effective:

Clear Role Separation. Each subagent knows its job. The explorer reads code but never writes. The worker-mini handles volume but defers complex decisions. This prevents confusion and ensures the right tool for each job.

Tool Access Control. Mini shouldn’t have destructive tools. By limiting what each subagent can do, I reduce the risk of unintended changes. My explorers are read-only, which means they can analyze my codebase without ever risking a modification.

Flexible Specialization. You can create domain-specific workers. For frontend work, I could set up a worker with frontend skills and configure it to automatically use the appropriate skill for UI tasks.

Cost Optimization. Mini handles volume while the full model handles complexity. This is the key to the 60-80% cost reduction. Simple tasks that used to consume expensive model capacity now flow through the much cheaper mini model.

Common Mistakes to Avoid

Through trial and error, I learned to avoid these pitfalls:

Giving Mini too much autonomy. I always require review for Mini output. It’s fast and cheap, but it can make mistakes. A quick human review catches issues before they compound.

Overlapping agent roles. Clear separation prevents confusion. Each subagent should have a distinct purpose. When roles blur, the orchestrator struggles to route tasks correctly.

Not configuring tool access. Mini shouldn’t have destructive tools. I learned this the hard way when an over-privileged mini agent made changes I didn’t expect.

Ignoring the orchestrator’s routing. Trust but verify the delegation logic. Sometimes the orchestrator makes surprising choices. When I notice this, I review my role descriptions and adjust for clarity.

Summary

Setting up subagents with Codex Mini transformed my workflow. Instead of one expensive agent handling everything, I now have a team of specialists working in parallel. The mini model handles the high-volume, low-complexity work, while the full model tackles the hard problems.

The configuration is simple—you can let Codex auto-configure or create your own files for more control. The key is defining clear roles, appropriate tool access, and reviewing the output, especially from the mini agents.

If you’re spending too much on model costs or waiting too long for simple tasks, subagents might be the solution. Start with the basic setup I outlined here, then customize based on your specific needs.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Reddit Discussion: Codex Subagent Setup
👨‍💻 OpenAI Codex Subagents Documentation

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!