📦

Awesome Codex Subagents

A collection of 130+ specialized Codex subagents covering a wide range of development use cases.

0 installs

Trust: 64 — Good

Blockchain

Ask AI about Awesome Codex Subagents

Powered by Claude · Grounded in docs

I know everything about Awesome Codex Subagents. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Documentation

The awesome collection of 136+ Codex subagents across 10 categories.

More awesome collections for developers

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:

~/.codex/agents/ for global agents (available in all projects)
.codex/agents/ for project-specific agents (higher precedence in that repo)

Clone this repository.
Copy the .toml agent files you want into one of the directories above.
Restart or refresh your Codex session if needed.
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.

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.3-codex-spark"
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.4`	Deep reasoning -- architecture reviews, security audits, financial logic	`security-auditor`, `architect-reviewer`, `fintech-engineer`
`gpt-5.3-codex-spark`	Fast scanning, synthesis, and lighter research tasks	`search-specialist`, `docs-researcher`, `agent-installer`

Sandbox Mode Philosophy

Each subagent's sandbox_mode field controls filesystem access:

Read-only agents (reviewers, auditors): sandbox_mode = "read-only" - analyze without modifying
Workspace-write agents (developers, engineers): sandbox_mode = "workspace-write" - create and modify files

Understanding Subagents

Subagents are specialized AI assistants that enhance Codex's capabilities by providing task-specific expertise. They act as dedicated helpers that Codex can call upon when encountering particular types of work.

What Makes Subagents Special?

Independent Context Windows Every subagent operates within its own isolated context space, preventing cross-contamination between different tasks and maintaining clarity in the primary conversation thread.

Domain-Specific Intelligence Subagents come equipped with carefully crafted instructions tailored to their area of expertise, resulting in superior performance on specialized tasks.

Shared Across Projects After creating a subagent, you can utilize it throughout various projects and distribute it among team members to ensure consistent development practices.

Explicit Delegation Codex does not spawn subagents automatically. Use explicit delegation prompts to specify which agents to spawn, how to divide the work, and what shape the result should take.

Core Advantages

Memory Efficiency: Isolated contexts prevent the main conversation from becoming cluttered with task-specific details
Enhanced Accuracy: Specialized prompts and configurations lead to better results in specific domains
Workflow Consistency: Team-wide subagent sharing ensures uniform approaches to common tasks
Codex-Native: Uses .toml agent files aligned with official Codex subagent docs

Example Workflows

PR review workflow:

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.

Bug investigation workflow:

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.

Repo exploration and planning workflow:

Use search_specialist to locate the code related to payment retries, knowledge_synthesizer to summarize the current design, and refactoring_specialist to propose a minimal refactor plan. Return a concrete action list.

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Submit new subagents via PR
Improve existing definitions
Report issues and bugs

License

MIT License - see LICENSE

This repository is a curated collection of subagent definitions contributed by both the maintainers and the community. All subagents are provided "as is" without warranty. We do not audit or guarantee the security or correctness of any subagent. Review before use, the maintainers accept no liability for any issues arising from their use.

If you find an issue with a listed subagent or want your contribution removed, please open an issue in this repository and we'll address it promptly.

Awesome Codex Subagents

Reviews

Documentation

Awesome Codex Subagents

Installation

Subagent Storage Locations

Subagent Structure

Smart Model Routing

Sandbox Mode Philosophy

Categories

01. Core Development

02. Language Specialists

03. Infrastructure

04. Quality & Security

05. Data & AI

06. Developer Experience

07. Specialized Domains

08. Business & Product

09. Meta & Orchestration

10. Research & Analysis

Understanding Subagents

What Makes Subagents Special?

Core Advantages

Example Workflows

Contributing

License

Security Checklist