Waiting list

Guide

Build an agent team with Claude Code and Codex subagents

A single agent can do a lot, but it looks at everything from the same angle. A team of specialised subagents works better: one plans, one reviews, one writes tests. Claude Code and Codex both support this, and setting it up is simpler than it sounds.

What a subagent is

A subagent is a separate agent with its own task, its own instructions and, if you like, restricted permissions. The main agent hands it a subtask; the subagent works in its own context and returns its result. This has two advantages: the main agent stays focused, and a reviewer that may only read cannot break anything.

Subagents in Claude Code

Claude Code reads subagents from Markdown files:

  • ~/.claude/agents/ applies to all projects on the machine.
  • .claude/agents/ in the repository applies only to that project and travels with the code.

A file looks like this:

---
name: reviewer
description: "Reviews changes for bugs, missing tests and security issues. Use proactively before committing."
tools: Read, Grep, Glob, Bash
model: inherit
---

You are the reviewer on the team. You do not change any files …

The description is what matters: Claude Code picks subagents on its own based on this description. Phrases like “Use proactively when …” help with that. You can also give a subagent a job directly: “Have the reviewer check the latest changes.” Use /agents to manage them in Claude Code.

Subagents in Codex

Codex uses TOML files, following the same pattern:

  • ~/.codex/agents/ for all projects,
  • .codex/agents/ in the repository.
name = "reviewer"
description = "Reviews changes for bugs, missing tests and security issues."
sandbox_mode = "read-only"
developer_instructions = '''
You are the reviewer on the team. You do not change any files …
'''

With sandbox_mode = "read-only", the agent may only read. Unlike Claude Code, Codex usually uses subagents only when you or an instruction ask for it. That is why a short list of the team belongs in AGENTS.md, for example: “reviewer: have it review code changes before every commit.” Codex runs subagents in parallel and summarises their results.

A sensible starter team

  • planer (planner): reads the code and delivers a plan in small steps before larger tasks (read-only).
  • reviewer: reviews changes before the commit (read-only).
  • tester: writes tests and runs the suite.
  • sicherheit (security): looks for vulnerabilities in login, payments, uploads and user input (read-only).
  • debugger: finds the root cause of bugs and backs up the fix with a test.
  • doku (docs): keeps the README and guides in line with the code.

This team is already set up on every euhost Box, for Claude Code and Codex. You will find the files in ~/.claude/agents/ and ~/.codex/agents/ and can adapt or delete them.

Practical tips

  • Project-specific agents belong in the repository (.claude/agents/, .codex/agents/). Then your whole team has the same agents, and changes go through Git.
  • Keep descriptions specific. “Reviews code” is too vague; “before every commit, focusing on missing tests and error handling” hits the mark.
  • Keep permissions minimal. An agent that only reviews gets read access only.
  • Parallel agents cost tokens. Every subagent uses up quota from your Claude or OpenAI subscription. For small changes, the main agent alone is enough.