175+ Codex Subagents in One Clone-and-Copy Repo

Codex can call specialized subagents, but a subagent is only as good as its definition file — and writing a dozen of those by hand is a weekend nobody has. VoltAgent/awesome-codex-subagents, a 6k-star awesome-list from the VoltAgent team, ships 175+ ready-written subagent definitions across 13 categories, each one a single .toml file you copy into place.

Why This Skill Matters

The README positions the collection as "written specifically for Codex and aligned with the official docs" — these are Codex-native .toml agent files, not generic prompts. Every definition carries a name, an invocation description, a model assignment, a reasoning-effort level, and a sandbox mode, so the operational decisions (which model, what filesystem access) are already made per role.

The categories span core development (13 agents), language specialists (31), infrastructure (16), quality and security (20), data and AI (14), developer experience (14), specialized domains (14), business and product (17), meta and orchestration (12), research and analysis (12), AI governance and safety (4), platform engineering and IDP (4), and LLMOps, evals and observability (4). Backend help, a security audit, and a market-research pass are all covered by the same repository.

Installation

There is no installer. The README's flow is clone, copy, refresh:

mkdir -p ~/.codex/agents
cp categories/01-core-development/backend-developer.toml ~/.codex/agents/

~/.codex/agents/ holds global agents available in all projects; .codex/agents/ holds project-specific agents with higher precedence. When a name exists in both, the project-specific one wins. Restart or refresh your Codex session after copying, and keep agent configuration in .codex/config.toml under [agents], as the official docs describe.

One behavior to internalize: Codex does not auto-spawn custom subagents. You delegate explicitly in your prompt — name the agent, describe the work, and say what shape the result should take.

Real Workflow: A Parallel PR Review

The README's own example workflow delegates to two subagents in one prompt:

Review this branch with parallel subagents. Have reviewer look for correctness, security, and missing tests. Have docs_researcher verify the framework APIs this patch depends on. Wait for both and summarize the findings with file references.

The reviewer agent runs PR-style review with a read-only sandbox, while docs-researcher verifies framework API claims against documentation. Because the read-heavy agents report back before any writes happen, the main thread stays clean and the findings arrive with file references you can check.

Real Workflow: Trace-Then-Fix a Bug

A second README workflow chains exploration into a fix:

Investigate the broken settings flow. Have code_mapper trace the owning code paths, browser_debugger reproduce the bug in the browser, and frontend_developer propose the smallest fix after the failure is understood. Wait for the read-heavy agents first, then continue.

This is the collection's design philosophy in one prompt: the read-heavy agents (code-mapper, browser-debugger) establish facts first, and only then does the workspace-write agent (frontend-developer) touch files.

Tips

• Trust the model routing already baked into each file: gpt-6.1-sol handles complex coding, architecture, and security work (security-auditor, docker-expert), while gpt-6-luna covers bounded search, extraction, and drafting (search-specialist, docs-researcher).
• Check the sandbox_mode field before delegating: reviewers and auditors run read-only, developers and engineers run workspace-write.
• The agent-installer subagent browses and installs agents from this repository via GitHub, so you can add roles from inside a session.
• If you want a role the list doesn't have, the README accepts contributions by PR — the .toml format is short enough to write your own.
• The maintainers state plainly that subagents are contributed and not audited; review any definition before loading it.

When Not to Use This

These are Codex subagents in Codex's .toml format — the README documents Codex agent directories only, and packages nothing for other runtimes. If your work has no natural decomposition (single-file edits, quick questions), explicit delegation adds ceremony without payoff. And because delegation is always explicit, this collection will not make Codex feel "smarter" by itself; the value appears when you actually route tasks to the specialists.

See the leaderboard for more skills.