subagents.md Codex Docs, 2026-03-17 00:33 UTC → 2026-05-14 07:00 UTC

97Global subagent settings still live under `[agents]` in your [configuration](https://developers.openai.com/codex/config-basic#configuration-precedence).97Global subagent settings still live under `[agents]` in your [configuration](https://developers.openai.com/codex/config-basic#configuration-precedence).

98 98 

99| Field | Type | Required | Purpose |99| Field | Type | Required | Purpose |

100| --- | --- | --- | --- |100| -------------------------------- | ------ | :------: | ---------------------------------------------------------- |

101| `agents.max_threads` | number | No | Concurrent open agent thread cap. |101| `agents.max_threads` | number | No | Concurrent open agent thread cap. |

102| `agents.max_depth` | number | No | Spawned agent nesting depth (root session starts at 0). |102| `agents.max_depth` | number | No | Spawned agent nesting depth (root session starts at 0). |

103| `agents.job_max_runtime_seconds` | number | No | Default timeout per worker for `spawn_agents_on_csv` jobs. |103| `agents.job_max_runtime_seconds` | number | No | Default timeout per worker for `spawn_agents_on_csv` jobs. |

105**Notes:**105**Notes:**

106 106 

107- `agents.max_threads` defaults to `6` when you leave it unset.107- `agents.max_threads` defaults to `6` when you leave it unset.

108- `agents.max_depth` defaults to `1`, which allows a direct child agent to spawn but prevents deeper nesting.108- `agents.max_depth` defaults to `1`, which allows a direct child agent to spawn but prevents deeper nesting. Keep the default unless you specifically need recursive delegation. Raising this value can turn broad delegation instructions into repeated fan-out, which increases token usage, latency, and local resource consumption. `agents.max_threads` still caps concurrent open threads, but it doesn't remove the cost and predictability risks of deeper recursion.

109- `agents.job_max_runtime_seconds` is optional. When you leave it unset, `spawn_agents_on_csv` falls back to its per-call default timeout of 1800 seconds per worker.109- `agents.job_max_runtime_seconds` is optional. When you leave it unset, `spawn_agents_on_csv` falls back to its per-call default timeout of 1800 seconds per worker.

110- If a custom agent name matches a built-in agent such as `explorer`, your custom agent takes precedence.110- If a custom agent name matches a built-in agent such as `explorer`, your custom agent takes precedence.

111 111 

112### Custom agent file schema112### Custom agent file schema

113 113 

114| Field | Type | Required | Purpose |114| Field | Type | Required | Purpose |

115| --- | --- | --- | --- |115| ------------------------ | -------- | :------: | --------------------------------------------------------------- |

116| `name` | string | Yes | Agent name Codex uses when spawning or referring to this agent. |116| `name` | string | Yes | Agent name Codex uses when spawning or referring to this agent. |

117| `description` | string | Yes | Human-facing guidance for when Codex should use this agent. |117| `description` | string | Yes | Human-facing guidance for when Codex should use this agent. |

118| `developer_instructions` | string | Yes | Core instructions that define the agent's behavior. |118| `developer_instructions` | string | Yes | Core instructions that define the agent's behavior. |

210```toml210```toml

211name = "docs_researcher"211name = "docs_researcher"

212description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."212description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."

213model = "gpt-5.3-codex-spark"213model = "gpt-5.4-mini"

214model_reasoning_effort = "medium"214model_reasoning_effort = "medium"

215sandbox_mode = "read-only"215sandbox_mode = "read-only"

216developer_instructions = """216developer_instructions = """

288```toml288```toml

289name = "code_mapper"289name = "code_mapper"

290description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."290description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."

291model = "gpt-5.3-codex-spark"291model = "gpt-5.4-mini"

292model_reasoning_effort = "medium"292model_reasoning_effort = "medium"

293sandbox_mode = "read-only"293sandbox_mode = "read-only"

294developer_instructions = """294developer_instructions = """