When we ask Codex to complete a task, we typically envision it as a single agent. However, for complex tasks involving distinct types of work, Codex intelligently decomposes the problem, spawning multiple agents to handle subtasks in parallel. These delegated agents are known as subagents.
Each subagent operates within its own thread, focusing exclusively on a specific portion of the original task. Meanwhile, the main agent orchestrates their efforts, synthesizing subagent outputs into a cohesive final response. This raises a key question for practitioners: How can we intentionally leverage subagents to solve our own problems?
In this guide, we'll explore Codex subagents through a hands-on case study. You'll learn how to define specialist agents, delegate work to them, inspect their individual threads, and enable the main agent to aggregate their findings into an actionable conclusion.
1. Case Study: Planning a Trip with Specialist Agents
Consider a travel planning scenario: a four-day solo trip from Zurich with a budget of 1,200 Swiss Francs. Potential destinations include Lisbon, Prague, and Copenhagen, with priorities around convenient travel, museums, and local cuisine.
To tackle this, we'll create three specialist agents:
- Travel Logistics Agent β evaluates transportation and connectivity.
- Budget Analyst β assesses costs and financial feasibility.
- Experience Researcher β explores cultural and culinary highlights.
Each specialist independently evaluates all three destinations from its unique perspective. The main agent then collects these findings, compares trade-offs, and recommends a final destination.
1.1 Defining the Specialist Agents
Codex allows you to define custom agents for a specific project by adding TOML configuration files under .codex/agents/. Here's an example structure:
# .codex/agents/travel-logistics.tomlname = "Travel Logistics Agent"
description = "Analyzes transportation options, travel times, and convenience for each destination."
[system_prompt]
template = "You are an expert in travel logistics. Evaluate each destination based on flight or train availability, duration, and overall ease of travel from Zurich."
# .codex/agents/budget-analyst.tomlname = "Budget Analyst"
description = "Estimates total trip costs, including accommodation, transportation, meals, and activities."
[system_prompt]
template = "You are a meticulous budget analyst. For each destination, estimate daily costs and total expenses within a 1,200 CHF budget, noting any overruns or savings."
# .codex/agents/experience-researcher.tomlname = "Experience Researcher"
description = "Researches museums, local food scenes, and unique cultural experiences."
[system_prompt]
template = "You are a cultural connoisseur. Highlight the best museums, signature dishes, and must-see experiences for each destination, ranked by traveler interest."
After defining these agents, you can invoke them in the Codex CLI by passing the --subagent flag or by referencing them in your main task prompt. The main agent will delegate subtasks automatically based on your instructions.
1.2 Coordinating Subagent Work
To coordinate, you'd issue a command like:
codex --subagent travel-logistics --subagent budget-analyst --subagent experience-researcher "Plan a 4-day trip from Zurich to Lisbon, Prague, or Copenhagen, budget 1,200 CHF, focusing on travel convenience, museums, and food."The main agent orchestrates the process: each subagent runs in its own thread, and the main agent collects results. You can inspect individual threads using codex threads list and codex threads show <thread-id> to review each subagent's analysis.
1.3 Aggregating Results
Once all subagents report, the main agent synthesizes their evaluations into a comparative summary. For example, it might present a table ranking each destination across three dimensions, highlighting trade-offs, and delivering a final recommendation based on weighted priorities.
Pro Tip: In 2026, Codex's subagent orchestration has become more granular, allowing dynamic delegation based on intermediate results. Practitioners can now define subagent dependencies, enabling sequential or parallel execution. This enhances efficiency for complex workflows.
2. Best Practices for Using Subagents
- Clearly define roles: Each subagent should have a distinct, non-overlapping mandate to avoid redundant work.
- Provide rich system prompts: Specific instructions yield more focused results, reducing post-processing effort.
- Monitor threads: Use thread inspection to debug and refine prompts in real-time.
- Manage aggregation: Explicitly instruct the main agent on how to combine results (e.g., weighted scoring, pros/cons lists).
3. Conclusion
Codex subagents transform a single-agent mindset into a team-based approach, enabling parallelized, specialized analysis for complex problems. By defining specialist agents and coordinating their work, you can harness AI's full potential for nuanced decision-making. As 2026 unfolds, expect even tighter integration and smarter delegation, making multi-agent workflows a staple in AI-assisted planning.
Original content by Shuai Guo. Published August 28, 2026, in Agentic AI.