awesome-codex-subagents README

The project's README from github.com/VoltAgent/awesome-codex-subagents. As one markdown file: README.md.

codex

The awesome collection of 172+ Codex subagents across 13 categories.

Awesome Subagent Count Last Update Discord


Awesome Codex Subagents

This repository serves as the definitive collection of Codex Subagents, specialized AI assistants designed for specific development tasks. Written specifically for Codex and aligned with the official docs.

Installation

Use Codex custom agent directories exactly as documented:

  1. Clone this repository.
  2. Copy the .toml agent files you want into one of the directories above.
  3. Restart or refresh your Codex session if needed.
  4. Delegate explicitly in prompts (Codex does not auto-spawn custom subagents).

Examples:

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

If you use agent configuration in Codex, keep it in .codex/config.toml under [agents] as described in the official docs.

Sponsors

Crawlbase Crawlbase is web data infrastructure trusted by 70,000+ developers. Its Crawling API, MCP server, and integrations give AI agents live access to any webpage — with JavaScript rendering, proxy rotation, and anti-bot protection.
SerpApi SerpApi is a Web Search API for your AI apps. Available in Markdown and JSON for any integration.

👉 You can feature your product here and reach developers using AI coding agents like Claude Code, Codex, Gemini, and more.

Become a Sponsor

Subagent Storage Locations

Type Path Availability Precedence
Project Subagents .codex/agents/ Current project only Higher
Global Subagents ~/.codex/agents/ All projects Lower

Note: When naming conflicts occur, project-specific subagents override global ones.

Subagent Structure

Each subagent uses a Codex-native .toml format:

name = "subagent-name"
description = "When this agent should be invoked"
model = "gpt-5.6-luna"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"

[instructions]
text = """
You are a [role description and expertise areas]...

[Agent-specific checklists, patterns, and guidelines]...
"""

Smart Model Routing

Each subagent includes a model field that automatically routes it to the right model -- balancing quality and cost:

Model When It's Used Examples
gpt-5.6-sol Deep reasoning -- architecture reviews, security audits, financial logic security-auditor, architect-reviewer, fintech-engineer
gpt-5.6-terra Implementation, diagnostics, evaluation, and multi-step professional analysis docker-expert, test-automator, scientific-literature-researcher
gpt-5.6-luna Bounded search, extraction, routing, drafting, and lightweight synthesis search-specialist, docs-researcher, agent-installer

Sandbox Mode Philosophy

Each subagent's sandbox_mode field controls filesystem access:

Categories

01. Core Development

Essential development subagents for everyday coding tasks.

02. Language Specialists

Language-specific experts with deep framework knowledge.

03. Infrastructure

DevOps, cloud, and deployment specialists.

04. Quality & Security — Testing, security, and code quality experts (19 agents)

04. Quality & Security

05. Data & AI — Data engineering, ML, and AI specialists (14 agents)

05. Data & AI

06. Developer Experience — Tooling and developer productivity experts (14 agents)

06. Developer Experience

awesome-codex-subagents (VoltAgent/awesome-codex-subagents)

Searching Database…

What is this?A curated collection of 170+ specialized subagent definitions for OpenAI Codex, covering development tasks like coding, infrastructure, security, data/AI, and developer experience.
Is this a tool or just a set of config files?It is a set of .toml configuration files, not an app or script you run; each file defines a subagent that Codex loads from its agent directories.
How do I install and use these subagents?Clone the repo, copy the .toml files you want into ~/.codex/agents/ (global) or .codex/agents/ (project-specific), then restart or refresh your Codex session and explicitly delegate to the subagent in your prompt.
Do I need anything besides Codex itself to use these?You just need an existing Codex setup; agent routing configuration can optionally be added under [agents] in .codex/config.toml.
Will Codex automatically pick the right subagent for me?No, Codex does not auto-spawn custom subagents, so you must explicitly reference the subagent you want in your prompt.
Does project/global precedence affect which subagent runs?Yes, when a project-level and global subagent share the same name, the project-specific one takes precedence.
How does model routing work for each subagent?Each .toml file has a model field that routes it to one of three tiers: gpt-5.6-sol for deep reasoning (e.g. security-auditor, architect-reviewer), gpt-5.6-terra for implementation and diagnostics (e.g. docker-expert, test-automator), and gpt-5.6-luna for lightweight search/extraction tasks (e.g. search-specialist, agent-installer).
How are subagents organized?They are grouped into 13 categories such as Core Development, Language Specialists, Infrastructure, Quality & Security, Data & AI, and Developer Experience, each with its own themed set of agents.
What is sandboxmode and why does it matter?Each subagent sets a sandboxmode field controlling filesystem access: read-only for reviewers and auditors that only analyze, and workspace-write for developers/engineers who need to create or modify files.
Can I pick which subagents are available per project vs globally?Yes, you can store agents in .codex/agents/ for project-only use or in ~/.codex/agents/ to make them available across all projects, with project agents taking precedence on name conflicts.
Creator
VoltAgent
Size
0.1 MB
Stars
6.3K
Updated
CommitOct 05
Age
7mo
Commits · 90 Days