Kenhuang Academy
  • English

      • Subagents

      Subagents let Codex delegate subtasks to smaller-context, tool-focused agents—avoiding one long session that both implements code and reviews it, or mixes frontend edits with production log queries.

      Why subagents?

      Problems with a single long agent session:

      • Context bloat: after exploring a large repo, constraints get pushed out
      • Role confusion: implementer and reviewer are the same “person,” missing bugs
      • Tool overload: test, log, and browser MCP on one agent increases misuse risk

      Subagents divide labor to mitigate these issues.

      Common patterns

      1. Explore subagent

      • Role: glob/grep, read structure, summarize architecture
      • No patches or read-only sandbox
      • Output: file lists, call chains, suggested change points

      The main agent edits only after a summary—less blind file reading.

      2. Review subagent (code review)

      Codex CLI supports a dedicated review agent for local changes before commit / push.

      Characteristics:

      • Does not inherit “I already fixed it” from the main session
      • Focuses on diff, test gaps, security risks

      See official docs: Run local code review

      3. MCP-specialized subagent

      Examples:

      • Subagent A: test MCP only (specific pytest config)
      • Subagent B: logs MCP only (staging errors)

      Main agent orchestrates: B finds stack trace → A verifies the fix.

      Parallel vs. serial

      StrategyWhen
      ParallelIndependent exploration (frontend routes + backend APIs separately)
      SerialDependencies (root cause first, then code change)

      CLI subagent features emphasize parallelizing complex tasks—useful for multi-package monorepo scans.

      Design principles

      1. Narrow tool set: do not attach MCP the subagent does not need
      2. Structured output: require JSON or a Markdown template for the main agent to parse
      3. Read-only first: explore and review subagents default to read-only sandbox
      4. Limits: cap steps and timeouts to prevent infinite loops

      Relation to Cloud @codex

      @codex review or @codex fix on GitHub PRs is cloud-orchestrated specialized work, similar to local subagents but in a remote environment. Put review rules in AGENTS.md so Cloud and CLI share them.

      Next steps