When we ask Codex to complete a task, we usually think of it as a single agent. But if some tasks are complex enough and involve several distinct types of work, Codex will try to divide the problem into smaller tasks and spawn separate agents to work on them. These delegated agents are called subagents. Each subagent works in its own thread and focuses on only one part of the original task. At the same time, the main agent coordinates their work and produces the final response by aggregating the subagents' results. As practitioners, this naturally leads to this question: How can we use subagents deliberately for our own problems? In this post, we'll explore Codex subagents through a hands-on case study. Along the way, we'll see how to define and delegate work to specialist agents, inspect their individual threads, and let the main agent combine their findings into a final result.

Here, we consider a travel planning task. Suppose we want to plan a four-day solo trip from Zurich. We have a total budget of 1,200 Swiss Francs. Our potential destinations include Lisbon, Prague, and Copenhagen, and we care about convenient travel, museums, and local food. For this task, we prepare three specialist agents: Travel logistics agent, Budget analyst, and Experience researcher. Each specialist will evaluate all three destinations from its own perspective. The main agent will then collect their findings, compare the tradeoffs, and recommend one final destination.

Codex allows us to define custom agents for a specific project. We can do this by adding TOML files under .codex/agents/: Each agent definition requires three fields: name, description, and developer_instructions. A custom agent can also specify its own model, reasoning effort, sandbox configuration, tools, and skills. If we do not override those settings here, the three specialists will inherit them from the main Codex session. Additionally, we add a small project-level configuration in .codex/config.toml to allow up to three subagent threads to run concurrently.

In the prompt, we explicitly asked the main agent to use our defined specialist agents when solving the task. We started Codex from the project directory with web search enabled, noting that we only need to enable web search for the main session. The three subagents inherit this capability when Codex spawns them. We saw that Codex started the three specialist agents in parallel. We can inspect their progress directly from the CLI using the agent-thread view, as each specialist has its own context, tool activity, and eventual result. Once all three agents finish, their findings are returned to the main agent for synthesis. We can then check what they produced, and each subagent returned a recommendation from its own perspective.