{"id":485967,"date":"2026-07-02T14:41:51","date_gmt":"2026-07-02T14:41:51","guid":{"rendered":"https:\/\/savepearlharbor.com\/?p=485967"},"modified":"-0001-11-30T00:00:00","modified_gmt":"-0001-11-29T21:00:00","slug":"","status":"publish","type":"post","link":"https:\/\/savepearlharbor.com\/?p=485967","title":{"rendered":"Codex Subagents Explained: Build Your AI Coding Team"},"content":{"rendered":"<div xmlns=\"http:\/\/www.w3.org\/1999\/xhtml\">\n<figure class=\"\"><img decoding=\"async\" src=\"https:\/\/habrastorage.org\/r\/w1560\/getpro\/habr\/\/post_images\/f88\/94e\/86d\/f8894e86df21797db1952f3e6cea3d94.png\" alt=\"Codex Subagents Explained: Build Your AI Coding Team\" sizes=\"(max-width: 780px) 100vw, 50vw\" srcset=\"https:\/\/habrastorage.org\/r\/w780\/getpro\/habr\/\/post_images\/f88\/94e\/86d\/f8894e86df21797db1952f3e6cea3d94.png 780w,&#10;       https:\/\/habrastorage.org\/r\/w1560\/getpro\/habr\/\/post_images\/f88\/94e\/86d\/f8894e86df21797db1952f3e6cea3d94.png 781w\" loading=\"lazy\" decode=\"async\"\/><\/p>\n<div><figcaption>Codex Subagents Explained: Build Your AI Coding Team<\/figcaption><\/div>\n<\/figure>\n<p>Hey devs! When you use Codex, putting too many tasks into a single conversation makes the model slow, confused, and unreliable. To solve this problem, I highly recommend using\u00a0<strong>subagents<\/strong>\u00a0(or Custom Agents).<\/p>\n<p>Think of it like this: instead of forcing one agent to do everything, you act as the manager running a team. You can have one subagent write front-end code, another write back-end code, and another review the code-all working in parallel at the exact same time. And this is what we cover in today\u2019s article ;).<\/p>\n<h3>What Are Codex Subagents?<\/h3>\n<p>A subagent is a separate Codex agent thread that the parent Codex session can spawn for a focused task. Subagents are useful when a job can be split into independent or specialized work: code review, security audit, documentation research, frontend debugging, test generation, or implementation planning.<\/p>\n<p>Codex includes built-in agents such as <code>**default**<\/code>, <code>**worker**<\/code>, and <code>**explorer**<\/code>.<\/p>\n<figure class=\"\"><img decoding=\"async\" src=\"https:\/\/habrastorage.org\/r\/w1560\/getpro\/habr\/\/post_images\/c9d\/58b\/a89\/c9d58ba893af70fb3cb99680cae5ffd7.png\" alt=\"Codex includes built-in agents\" sizes=\"(max-width: 780px) 100vw, 50vw\" srcset=\"https:\/\/habrastorage.org\/r\/w780\/getpro\/habr\/\/post_images\/c9d\/58b\/a89\/c9d58ba893af70fb3cb99680cae5ffd7.png 780w,&#10;       https:\/\/habrastorage.org\/r\/w1560\/getpro\/habr\/\/post_images\/c9d\/58b\/a89\/c9d58ba893af70fb3cb99680cae5ffd7.png 781w\" loading=\"lazy\" decode=\"async\"\/><\/p>\n<div><figcaption>Codex includes built-in agents<\/figcaption><\/div>\n<\/figure>\n<h4>The Built-in Agents I Use<\/h4>\n<p>Codex already comes with a few basic agents built right in:<\/p>\n<ul>\n<li>\n<p><strong>Default Agent:<\/strong>\u00a0This is your general fallback agent.<\/p>\n<\/li>\n<li>\n<p><strong>Worker Agent:<\/strong>\u00a0Focuses strictly on implementation and bug fixes.<\/p>\n<\/li>\n<li>\n<p><strong>Explorer Agent:<\/strong>\u00a0Best for reading, searching, and understanding your existing codebase.<\/p>\n<\/li>\n<\/ul>\n<p>You can also define custom agents as TOML files. Each custom agent has its own name, description, instructions, and optional model, reasoning, sandbox, MCP, and skill settings.<\/p>\n<p>Subagents are not spawned automatically just because files exist. In normal use, ask Codex explicitly:<\/p>\n<pre><code class=\"bash\">Spawn security_auditor to review this authentication change for OWASP risks.  Spawn python_expert to refactor this module with type hints and pytest tests.  Spawn orchestrator to plan this full-stack feature and recommend specialist handoffs.<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:87px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<h3>Why I Use subagents (And Why You Should Too)<\/h3>\n<p>Using sub-agents gives you three massive advantages:<\/p>\n<ol>\n<li>\n<p><strong>No Context Overload:<\/strong>\u00a0Even large context window LLMs have limits. Sub-agents keep your chat clean because each agent only looks at its specific task.<\/p>\n<\/li>\n<li>\n<p><strong>Speed:<\/strong>\u00a0Because multiple agents work in parallel, your tasks get done much faster.<\/p>\n<\/li>\n<li>\n<p><strong>Specialization:<\/strong>\u00a0Different tasks need different thinking. With sub-agents, you can assign different models, unique instructions, and specific tools to each job.<\/p>\n<\/li>\n<\/ol>\n<h3>Where Custom Agents Live<\/h3>\n<p>Codex supports two common install locations:<\/p>\n<figure class=\"\"><img decoding=\"async\" src=\"https:\/\/habrastorage.org\/r\/w1560\/getpro\/habr\/\/post_images\/917\/9eb\/841\/9179eb841e05dd25d247c682b4511d9c.png\" alt=\"Where Custom Agents Live\" sizes=\"(max-width: 780px) 100vw, 50vw\" srcset=\"https:\/\/habrastorage.org\/r\/w780\/getpro\/habr\/\/post_images\/917\/9eb\/841\/9179eb841e05dd25d247c682b4511d9c.png 780w,&#10;       https:\/\/habrastorage.org\/r\/w1560\/getpro\/habr\/\/post_images\/917\/9eb\/841\/9179eb841e05dd25d247c682b4511d9c.png 781w\" loading=\"lazy\" decode=\"async\"\/><\/p>\n<div><figcaption>Where Custom Agents Live<\/figcaption><\/div>\n<\/figure>\n<p>For public libraries and team repos, use project-scoped agents so they clone with the repository:<\/p>\n<pre><code class=\"bash\">.codex\/    config.toml    agents\/      python_expert.toml      security_auditor.toml      orchestrator.toml<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>Dot directories are hidden in many file explorers. If you do not see\u00a0<code>.codex<\/code>, use:<\/p>\n<pre><code class=\"bash\">ls -la  ls -la .codex\/agents<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<h3>How to Set Up Your Custom Sub-agents<\/h3>\n<p>When you find yourself repeating the same workflow many times, it\u2019s time to build a\u00a0<strong>Custom Agent<\/strong>. You can set these up directly inside your terminal, VS Code, or whatever IDE you prefer.<\/p>\n<h4>Step 1: Create the Folder Structure<\/h4>\n<p>Go to your project folder and create a directory structure that looks exactly like this:<\/p>\n<pre><code class=\"bash\">your-project\/  \u2502  \u2514\u2500\u2500 .codex\/      \u251c\u2500\u2500 config.toml      \u2514\u2500\u2500 agents\/          \u251c\u2500\u2500 backend_developer.toml          \u2514\u2500\u2500 code_reviewer.toml<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p><em>(Tip: If you want these agents to be accessible across your entire computer for all projects, place them in your home directory at<\/em>\u00a0<code>_~\/.codex\/agents\/_<\/code>\u00a0<em>instead).<\/em><\/p>\n<h4>Step 2: Configure Global Settings (config.toml)<\/h4>\n<p>Open your\u00a0<code>config.toml<\/code>\u00a0file to set up the global boundaries for your team. Here is the configuration I recommend:<\/p>\n<pre><code class=\"bash\">[agents]  max_threads = 6  max_depth = 1<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p><code>max_threads<\/code>\u00a0controls how many agent threads can be open concurrently.\u00a0<code>max_depth = 1<\/code>\u00a0is a good default because it allows direct child agents but prevents recursive fan-out that can become expensive and hard to reason about.<\/p>\n<h4>Step 3: Write Your Custom Agent Files<\/h4>\n<p>Inside your\u00a0<code>.codex\/agents\/<\/code>\u00a0folder, create files using readable, clear names. We will use these exact file names to call the agents in our prompts later.<\/p>\n<h4>Important fields explained<\/h4>\n<p><strong>name<\/strong><\/p>\n<p>The identifier Codex uses when spawning the agent. Keep it stable and easy to type. This library uses lowercase\u00a0<code>underscore_case<\/code>:<\/p>\n<pre><code class=\"bash\">python_expert  security_auditor  frontend_developer<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p><strong>description<\/strong><\/p>\n<p>Tells humans and Codex when this agent should be used. Make it specific. A weak description says:<\/p>\n<p>Helps with code.<\/p>\n<p>A stronger description says:<\/p>\n<p>Use when you need read-only pull request review focused on correctness,<br \/> regressions, security risks, and missing tests.<\/p>\n<p><strong>developer_instructions<\/strong><\/p>\n<p>The agent\u2019s core behavior. Include:<\/p>\n<ul>\n<li>\n<p>Role and specialty.<\/p>\n<\/li>\n<li>\n<p>What to prioritize, and what to avoid.<\/p>\n<\/li>\n<li>\n<p>How to report results.<\/p>\n<\/li>\n<li>\n<p>Whether it should edit files or stay read-only.<\/p>\n<\/li>\n<li>\n<p>How it should handle missing context or validation.<\/p>\n<\/li>\n<\/ul>\n<p><strong>model &amp; model_reasoning_effort<\/strong><\/p>\n<p>Use stronger models and higher reasoning for review, security, architecture, orchestration, and difficult debugging. Use smaller or faster models for routine implementation, documentation, and focused exploration. If you omit model fields, the agent inherits the parent Codex session settings.<\/p>\n<p><strong>sandbox_mode<\/strong><\/p>\n<p>Use\u00a0<code>read-only<\/code>\u00a0for agents that inspect and report without changing files; use\u00a0<code>workspace-write<\/code>\u00a0for agents that implement code or documentation changes.<\/p>\n<pre><code class=\"bash\">sandbox_mode = \"read-only\"sandbox_mode = \"workspace-write\"<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>Subagents still inherit the parent session\u2019s approval policy and live runtime overrides, so the parent session remains the final control point.<\/p>\n<p><strong>nickname_candidates<\/strong><\/p>\n<p>Display labels for spawned agent threads. They do not change the real agent\u2019s name. Use simple ASCII names with letters, digits, spaces, hyphens, or underscores.<\/p>\n<p>nickname_candidates = [\u201cAtlas\u201d, \u201cDelta\u201d, \u201cEcho\u201d]<\/p>\n<p><strong>Example 1:<\/strong>\u00a0<code>**security_auditor.toml**<\/code>\u00a0Open the file and define the properties. The most important parts to include are the name, description, and developer instructions:<\/p>\n<pre><code class=\"bash\">name = \"security_auditor\"  description = \"Use when you need read-only security review, OWASP risk analysis, dependency risk triage, or credential-handling review.\"  model = \"gpt-5.4\"  model_reasoning_effort = \"high\"  sandbox_mode = \"read-only\"  nickname_candidates = [\"Security Auditor\"]  developer_instructions = \"\"\"  You are the Codex custom subagent `security_auditor`.    Review code like a security owner. Stay read-only. Prioritize exploitable vulnerabilities, auth and access-control flaws, injection risks, data exposure, insecure secrets handling, and dependency risk.    Lead with concrete findings ordered by severity. Include affected files or symbols, impact, and remediation. Avoid style-only comments.  \"\"\"<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p><strong>Example 2:<\/strong>\u00a0<code>**python_expert.toml**<\/code><\/p>\n<pre><code class=\"bash\">name = \"python_expert\"  description = \"Use when you need modern Python implementation, refactoring, type hints, pytest tests, or framework-specific Python guidance.\"  developer_instructions = \"\"\"  You are the Codex custom subagent `python_expert`.    Focus on modern Python. Prefer type hints, explicit error handling, pathlib, small functions, and pytest coverage. Follow the parent Codex session's repository instructions and approval policy.    When editing code, keep changes scoped to the Python task. When you cannot run validation, state the exact command the parent should run.  \"\"\"<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<blockquote>\n<p><strong><em>My Pro-Tip on Budgeting:<\/em><\/strong>\u00a0<em>If you are on a pay-as-you-go plan, defining the<\/em>\u00a0<code>_model_<\/code>\u00a0<em>property is incredibly useful. You can set up a cheaper model for low-effort tasks and save expensive, high-reasoning models for complex tasks!<\/em><\/p>\n<\/blockquote>\n<h3>Shortcut: The Codex Agents Library<\/h3>\n<figure class=\"\"><img decoding=\"async\" src=\"https:\/\/habrastorage.org\/r\/w1560\/getpro\/habr\/\/post_images\/15b\/932\/4c3\/15b9324c39963edb7e257d872fdad2a5.png\" alt=\"Shortcut: The Codex Agents Library\" sizes=\"(max-width: 780px) 100vw, 50vw\" srcset=\"https:\/\/habrastorage.org\/r\/w780\/getpro\/habr\/\/post_images\/15b\/932\/4c3\/15b9324c39963edb7e257d872fdad2a5.png 780w,&#10;       https:\/\/habrastorage.org\/r\/w1560\/getpro\/habr\/\/post_images\/15b\/932\/4c3\/15b9324c39963edb7e257d872fdad2a5.png 781w\" loading=\"lazy\" decode=\"async\"\/><\/p>\n<div><figcaption>Shortcut: The Codex Agents Library<\/figcaption><\/div>\n<\/figure>\n<p>If you don\u2019t want to create these from scratch, you don\u2019t have to. I have a library containing around 36 different pre-made agents. You can simply download a file-like the\u00a0<code>front_end_developer<\/code>\u00a0agent-and drop it straight into your project\u2019s\u00a0<code>agents<\/code>\u00a0folder using VS Code.<\/p>\n<p>Codex Agents Library:\u00a0<a href=\"https:\/\/github.com\/proflead\/codex-agents-library\" rel=\"noopener noreferrer nofollow\">https:\/\/github.com\/proflead\/codex-agents-library<\/a><\/p>\n<h3>How to Run Subagents in the Terminal<\/h3>\n<p>Now that everything is configured, let\u2019s launch Codex and look at how to control your new team.<\/p>\n<h4>1. Calling a Single Agent<\/h4>\n<p>To spawn a custom agent, you must explicitly call it by its name inside your prompt:<\/p>\n<pre><code class=\"bash\">Spawn code_reviewer to review this branch against main for correctness,   regressions, and missing tests. Report findings only.<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>Codex will analyze your folder, find the front-end agent, and successfully assign the task to it.<\/p>\n<h4>2. Running Agents in Parallel<\/h4>\n<p>Because we allowed up to 6 concurrent threads in our config, you can call multiple agents at once to handle separate tasks simultaneously:<\/p>\n<pre><code class=\"bash\">Review this PR with parallel subagents. Spawn code_reviewer for correctness,   security_auditor for exploitable risks, test_generator for coverage gaps,   and performance_optimizer for latency or memory issues. Wait for all results   and summarize findings by severity.<\/code><div class=\"code-explainer\"><a href=\"https:\/\/sourcecraft.dev\/\" class=\"tm-button code-explainer__link\" style=\"visibility: hidden;\"><img style=\"width:14px;height:14px;object-fit:cover;object-position:left;\"\/><\/a><\/div><\/pre>\n<p>You will see both agents trigger and start working side-by-side in real-time.<\/p>\n<h4>3. Managing the Session<\/h4>\n<ul>\n<li>\n<p><strong>Check Status:<\/strong>\u00a0Type the\u00a0<code>**\/agent**<\/code>\u00a0command in your session terminal. This lists every active sub-agent currently running.<\/p>\n<\/li>\n<li>\n<p><strong>Granular Control:<\/strong>\u00a0You can actually step inside the thread of a single active agent to give it specific, isolated instructions without confusing the other agents.<\/p>\n<\/li>\n<\/ul>\n<blockquote>\n<p><strong><em>Watch out for Git Branches:<\/em><\/strong>\u00a0<em>By default, sub-agents do not create separate working branches; they will dump all changes straight onto your<\/em>\u00a0<code>_main_<\/code>\u00a0<em>branch. If you want to keep things clean, explicitly tell them in your prompt:<\/em>\u00a0\u201ccreate a separate branch before you start the job.\u201d<\/p>\n<\/blockquote>\n<h3>5 Critical Mistakes I Want You to Avoid<\/h3>\n<p>As you start experimenting with sub-agents, please keep these five classic beginner traps in mind:<\/p>\n<ul>\n<li>\n<p><strong>Using Agents Without a Clear Plan:<\/strong>\u00a0If you just say\u00a0<em>\u201cuse sub-agents to fix my app,\u201d<\/em>\u00a0your manager agent has to guess too much. Be highly specific about who does what.<\/p>\n<\/li>\n<li>\n<p><strong>Spawning Too Many Agents:<\/strong>\u00a0More agents do not mean better output. Spawning too many just increases your API costs, adds background noise, and creates general confusion.<\/p>\n<\/li>\n<li>\n<p><strong>Letting Multiple Agents Edit Related Files at the Same Time:<\/strong>\u00a0This is a major trap. It can create\u00a0<strong>semantic conflicts<\/strong>-meaning your code breaks logically even if Git doesn\u2019t show a traditional merge conflict.<\/p>\n<\/li>\n<li>\n<p><strong>Trusting AI-Generated Tests Too Much:<\/strong>\u00a0AI-written tests sometimes test the\u00a0<em>implementation<\/em>\u00a0rather than the\u00a0<em>behavior<\/em>. Always review the tests yourself.<\/p>\n<\/li>\n<li>\n<p><strong>Giving Agents Early Access to Sensitive Areas:<\/strong>\u00a0Never let a sub-agent handle production secrets, deployment scripts, database migrations, or infrastructure changes without a human reviewing it first.<\/p>\n<\/li>\n<\/ul>\n<p>At the end of the day, subagents are incredibly powerful tools to speed up your development, but you are still completely responsible for the final code!<\/p>\n<h3>Codex Subagents: Video Tutorial<\/h3>\n<p>Watch my full step-by-step tutorial about Codex agents on YouTube:<\/p>\n<div class=\"tm-iframe_temp\" data-src=\"https:\/\/embedd.srv.habr.com\/iframe\/6a4678afa269d5af8402a064\" data-style=\"\" id=\"6a4678afa269d5af8402a064\" width=\"\" data-habr-games=\"\"><\/div>\n<p><strong><em>Watch on YouTube:<\/em><\/strong>\u00a0<a href=\"https:\/\/youtu.be\/xItvCoWNPVo\" rel=\"noopener noreferrer nofollow\"><strong><em>Codex Subagents<\/em><\/strong><\/a><\/p>\n<p>Cheers, proflead! \ud83d\ude09<\/p>\n<\/div>\n<p>\u0441\u0441\u044b\u043b\u043a\u0430 \u043d\u0430 \u043e\u0440\u0438\u0433\u0438\u043d\u0430\u043b \u0441\u0442\u0430\u0442\u044c\u0438 <a href=\"https:\/\/habr.com\/ru\/articles\/1054956\/\">https:\/\/habr.com\/ru\/articles\/1054956\/<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Codex Subagents Explained: Build Your AI Coding TeamHey devs! When you use Codex, putting too many tasks into a single conversation makes the model slow, confused, and unreliable. To solve this problem, I highly recommend using\u00a0subagents\u00a0(or Custom Agents).Think of it like this: instead of forcing one agent to do everything, you act as the manager running a team. You can have one subagent write front-end code, another write back-end code, and another review the code-all working in parallel at the exact same time. And this is what we cover in today\u2019s article ;).What Are Codex Subagents?A subagent is a separate Codex agent thread that the parent Codex session can spawn for a focused task. Subagents are useful when a job can be split into independent or specialized work: code review, security audit, documentation research, frontend debugging, test generation, or implementation planning.Codex includes built-in agents such as **default**, **worker**, and **explorer**.Codex includes built-in agentsThe Built-in Agents I UseCodex already comes with a few basic agents built right in:Default Agent:\u00a0This is your general fallback agent.Worker Agent:\u00a0Focuses strictly on implementation and bug fixes.Explorer Agent:\u00a0Best for reading, searching, and understanding your existing codebase.You can also define custom agents as TOML files. Each custom agent has its own name, description, instructions, and optional model, reasoning, sandbox, MCP, and skill settings.Subagents are not spawned automatically just because files exist. In normal use, ask Codex explicitly:Spawn security_auditor to review this authentication change for OWASP risks.  Spawn python_expert to refactor this module with type hints and pytest tests.  Spawn orchestrator to plan this full-stack feature and recommend specialist handoffs.Why I Use subagents (And Why You Should Too)Using sub-agents gives you three massive advantages:No Context Overload:\u00a0Even large context window LLMs have limits. Sub-agents keep your chat clean because each agent only looks at its specific task.Speed:\u00a0Because multiple agents work in parallel, your tasks get done much faster.Specialization:\u00a0Different tasks need different thinking. With sub-agents, you can assign different models, unique instructions, and specific tools to each job.Where Custom Agents LiveCodex supports two common install locations:Where Custom Agents LiveFor public libraries and team repos, use project-scoped agents so they clone with the repository:.codex\/    config.toml    agents\/      python_expert.toml      security_auditor.toml      orchestrator.tomlDot directories are hidden in many file explorers. If you do not see\u00a0.codex, use:ls -la  ls -la .codex\/agentsHow to Set Up Your Custom Sub-agentsWhen you find yourself repeating the same workflow many times, it\u2019s time to build a\u00a0Custom Agent. You can set these up directly inside your terminal, VS Code, or whatever IDE you prefer.Step 1: Create the Folder StructureGo to your project folder and create a directory structure that looks exactly like this:your-project\/  \u2502  \u2514\u2500\u2500 .codex\/      \u251c\u2500\u2500 config.toml      \u2514\u2500\u2500 agents\/          \u251c\u2500\u2500 backend_developer.toml          \u2514\u2500\u2500 code_reviewer.toml(Tip: If you want these agents to be accessible across your entire computer for all projects, place them in your home directory at\u00a0_~\/.codex\/agents\/_\u00a0instead).Step 2: Configure Global Settings (config.toml)Open your\u00a0config.toml\u00a0file to set up the global boundaries for your team. Here is the configuration I recommend:[agents]  max_threads = 6  max_depth = 1max_threads\u00a0controls how many agent threads can be open concurrently.\u00a0max_depth = 1\u00a0is a good default because it allows direct child agents but prevents recursive fan-out that can become expensive and hard to reason about.Step 3: Write Your Custom Agent FilesInside your\u00a0.codex\/agents\/\u00a0folder, create files using readable, clear names. We will use these exact file names to call the agents in our prompts later.Important fields explainednameThe identifier Codex uses when spawning the agent. Keep it stable and easy to type. This library uses lowercase\u00a0underscore_case:python_expert  security_auditor  frontend_developerdescriptionTells humans and Codex when this agent should be used. Make it specific. A weak description says:Helps with code.A stronger description says:Use when you need read-only pull request review focused on correctness, regressions, security risks, and missing tests.developer_instructionsThe agent\u2019s core behavior. Include:Role and specialty.What to prioritize, and what to avoid.How to report results.Whether it should edit files or stay read-only.How it should handle missing context or validation.model &amp; model_reasoning_effortUse stronger models and higher reasoning for review, security, architecture, orchestration, and difficult debugging. Use smaller or faster models for routine implementation, documentation, and focused exploration. If you omit model fields, the agent inherits the parent Codex session settings.sandbox_modeUse\u00a0read-only\u00a0for agents that inspect and report without changing files; use\u00a0workspace-write\u00a0for agents that implement code or documentation changes.sandbox_mode = &#171;read-only&#187;sandbox_mode = &#171;workspace-write&#187;Subagents still inherit the parent session\u2019s approval policy and live runtime overrides, so the parent session remains the final control point.nickname_candidatesDisplay labels for spawned agent threads. They do not change the real agent\u2019s name. Use simple ASCII names with letters, digits, spaces, hyphens, or underscores.nickname_candidates = [\u201cAtlas\u201d, \u201cDelta\u201d, \u201cEcho\u201d]Example 1:\u00a0**security_auditor.toml**\u00a0Open the file and define the properties. The most important parts to include are the name, description, and developer instructions:name = &#171;security_auditor&#187;  description = &#171;Use when you need read-only security review, OWASP risk analysis, dependency risk triage, or credential-handling review.&#187;  model = &#171;gpt-5.4&#187;  model_reasoning_effort = &#171;high&#187;  sandbox_mode = &#171;read-only&#187;  nickname_candidates = [&#171;Security Auditor&#187;]  developer_instructions = &#171;&#187;&#187;  You are the Codex custom subagent `security_auditor`.    Review code like a security owner. Stay read-only. Prioritize exploitable vulnerabilities, auth and access-control flaws, injection risks, data exposure, insecure secrets handling, and dependency risk.    Lead with concrete findings ordered by severity. Include affected files or symbols, impact, and remediation. Avoid style-only comments.  &#171;&#187;&#187;Example 2:\u00a0**python_expert.toml**name = &#171;python_expert&#187;  description = &#171;Use when you need modern Python implementation, refactoring, type hints, pytest tests, or framework-specific Python guidance.&#187;  developer_instructions = &#171;&#187;&#187;  You are the Codex custom subagent `python_expert`.    Focus on modern Python. Prefer type hints, explicit error handling, pathlib, small functions, and pytest coverage. Follow the parent Codex session&#8217;s repository instructions and approval policy.    When editing code, keep changes scoped to the Python task. When you cannot run validation, state the exact command the parent should run.  &#171;&#187;&#187;My Pro-Tip on Budgeting:\u00a0If you are on a pay-as-you-go plan, defining the\u00a0_model_\u00a0property is incredibly useful. You can set up a cheaper model for low-effort tasks and save expensive, high-reasoning models for complex tasks!Shortcut: The Codex Agents LibraryShortcut: The Codex Agents LibraryIf you don\u2019t want to create these from scratch, you don\u2019t have to. I have a library containing around 36 different pre-made agents. You can simply download a file-like the\u00a0front_end_developer\u00a0agent-and drop it straight into your project\u2019s\u00a0agents\u00a0folder using VS Code.Codex Agents Library:\u00a0https:\/\/github.com\/proflead\/codex-agents-libraryHow to Run Subagents in the TerminalNow that everything is configured, let\u2019s launch Codex and look at how to control your new team.1. Calling a Single AgentTo spawn a custom agent, you must explicitly call it by its name inside your prompt:Spawn code_reviewer to review this branch against main for correctness,   regressions, and missing tests. Report findings only.Codex will analyze your folder, find the front-end agent, and successfully assign the task to it.2. Running Agents in ParallelBecause we allowed up to 6 concurrent threads in our config, you can call multiple agents at once to handle separate tasks simultaneously:Review this PR with parallel subagents. Spawn code_reviewer for correctness,   security_auditor for exploitable risks, test_generator for coverage gaps,   and performance_optimizer for latency or memory issues. Wait for all results   and summarize findings by severity.You will see both agents trigger and start working side-by-side in real-time.3. Managing the SessionCheck Status:\u00a0Type the\u00a0**\/agent**\u00a0command in your session terminal. This lists every active sub-agent currently running.Granular Control:\u00a0You can actually step inside the thread of a single active agent to give it specific, isolated instructions without confusing the other agents.Watch out for Git Branches:\u00a0By default, sub-agents do not create separate working branches; they will dump all changes straight onto your\u00a0_main_\u00a0branch. If you want to keep things clean, explicitly tell them in your prompt:\u00a0\u201ccreate a separate branch before you start the job.\u201d5 Critical Mistakes I Want You to AvoidAs you start experimenting with sub-agents, please keep these five classic beginner traps in mind:Using Agents Without a Clear Plan:\u00a0If you just say\u00a0\u201cuse sub-agents to fix my app,\u201d\u00a0your manager agent has to guess too much. Be highly specific about who does what.Spawning Too Many Agents:\u00a0More agents do not mean better output. Spawning too many just increases your API costs, adds background noise, and creates general confusion.Letting Multiple Agents Edit Related Files at the Same Time:\u00a0This is a major trap. It can create\u00a0semantic conflicts-meaning your code breaks logically even if Git doesn\u2019t show a traditional merge conflict.Trusting AI-Generated Tests Too&#8230;<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[],"tags":[],"class_list":["post-485967","post","type-post","status-publish","format-standard","hentry"],"_links":{"self":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/posts\/485967","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=485967"}],"version-history":[{"count":0,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=\/wp\/v2\/posts\/485967\/revisions"}],"wp:attachment":[{"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=485967"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=485967"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/savepearlharbor.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=485967"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}