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

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)

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 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 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.

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:

• 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

Categories

01. Core Development

Essential development subagents for everyday coding tasks.

• api-designer - REST and GraphQL API architect
• backend-developer - Server-side expert for scalable APIs
• code-mapper - Code path mapping and ownership boundary analysis
• design-bridge - Translates DESIGN.md specs into implementation-ready UI instructions
• electron-pro - Desktop application expert
• frontend-developer - UI/UX specialist for React, Vue, and Angular
• fullstack-developer - End-to-end feature development
• graphql-architect - GraphQL schema and federation expert
• [microservices-architect](categories/01-core-development/microservices-arch