Codex Subagents

Use project-scoped files under .codex/agents/ for repo-specific Codex custom agents.

Intent

Keep custom-agent definitions concise, repo-reviewed, and versioned alongside the codebase in the location Codex reads directly.

Request Signals

  • codex subagent

  • custom agent

  • cuda-engineer

  • python-engineer

  • fresh set of eyes

  • repo-managed agent

Open First

  • docs/dev/subagents.md

  • .codex/agents/cuda-engineer.toml

  • .codex/agents/python-engineer.toml

  • AGENTS.md

Verify

  • uv run pytest tests/test_codex_subagents.py -q

  • uv run python scripts/check_docs.py --check

Risks

  • Letting agent instructions sprawl turns fresh eyes into prompt debt.

  • Project-local .codex trees are often globally gitignored; keep .codex/agents/*.toml explicitly tracked.

  • If a workstation overlays repo .codex with a separate mount, Codex may need an unsandboxed write to update the files.

Workflow

Edit the repo-managed source files under .codex/agents/:

uv run python scripts/intake.py "update cuda engineer subagent instructions"

Validate them locally:

uv run pytest tests/test_codex_subagents.py -q

That path is the source of truth Codex reads for project-scoped custom agents.