Awesome Codex Subagents

---
name: awesome-codex-subagents
description: Collection of 136+ specialized Codex subagents in TOML format covering core development, language specialists, infrastructure, quality/security, and more categories.
triggers:
  - set up codex subagents
  - add a codex subagent
  - install codex agent
  - create custom codex subagent
  - configure codex agents directory
  - use specialized ai subagents with codex
  - add backend developer subagent
  - delegate tasks to codex subagents
---

# Awesome Codex Subagents

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

A curated collection of 136+ ready-to-use Codex subagents in `.toml` format. Each subagent is a specialized AI assistant scoped to a specific development role — from backend developer to Kubernetes specialist to security auditor. Install them globally or per-project and delegate tasks to them explicitly in your Codex prompts.

---

## What This Project Does

- Provides pre-built `.toml` subagent definitions for Codex
- Each agent has a focused role, tuned model, sandbox permissions, and detailed instructions
- Covers 10 categories: Core Development, Language Specialists, Infrastructure, Quality & Security, AI/ML, Data Engineering, Documentation, Specialized Domains, Workflow, and Research
- Agents are composable — you can use multiple subagents in a single session

---

## Installation

### Prerequisites

- [OpenAI Codex CLI](https://github.com/openai/codex) installed
- A valid Codex session/API access

### Clone the Repository

```bash
git clone https://github.com/VoltAgent/awesome-codex-subagents.git
cd awesome-codex-subagents

Install Global Agents (available in all projects)

mkdir -p ~/.codex/agents

# Install a single agent
cp categories/01-core-development/backend-developer.toml ~/.codex/agents/

# Install an entire category
cp categories/01-core-development/*.toml ~/.codex/agents/

# Install all agents
cp categories/**/*.toml ~/.codex/agents/

Install Project-Specific Agents (higher precedence)

mkdir -p .codex/agents

cp categories/04-quality-security/reviewer.toml .codex/agents/
cp categories/04-quality-security/security-auditor.toml .codex/agents/

Note: Project-level agents (.codex/agents/) override global agents (~/.codex/agents/) when names conflict.

---

Directory Structure

awesome-codex-subagents/
├── categories/
│   ├── 01-core-development/
│   │   ├── backend-developer.toml
│   │   ├── frontend-developer.toml
│   │   ├── api-designer.toml
│   │   └── ...
│   ├── 02-language-specialists/
│   │   ├── python-pro.toml
│   │   ├── typescript-pro.toml
│   │   ├── rust-engineer.toml
│   │   └── ...
│   ├── 03-infrastructure/
│   │   ├── devops-engineer.toml
│   │   ├── kubernetes-specialist.toml
│   │   ├── terraform-engineer.toml
│   │   └── ...
│   ├── 04-quality-security/
│   │   ├── code-reviewer.toml
│   │   ├── security-auditor.toml
│   │   ├── qa-expert.toml
│   │   └── ...
│   └── ...

---

Subagent TOML Format

Each subagent is a .toml file with this structure:

name = "backend-developer"
description = "When to invoke: building APIs, server logic, database models, authentication, or any server-side feature"
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"

[instructions]
text = """
You are a senior backend engineer specializing in scalable server-side architecture...

## Core Responsibilities
- Design and implement RESTful and GraphQL APIs
- Write performant database queries and ORM models
- Implement authentication and authorization patterns
- ...
"""

Key Fields

Field	Description
name	Unique identifier used to delegate tasks
description	When Codex should use this agent
model	Which model powers this agent
model_reasoning_effort	low, medium, or high
sandbox_mode	read-only or workspace-write
[instructions].text	The full system prompt for the agent

---

Model Routing Reference

Model	Best For	Example Agents
gpt-5.4	Deep reasoning, architecture, security audits	security-auditor, architect-reviewer
gpt-5.3-codex-spark	Fast scanning, synthesis, lighter tasks	search-specialist, docs-researcher

---

Sandbox Mode Reference

Mode	File Access	Best For
read-only	Can read, cannot write	Reviewers, auditors, analyzers
workspace-write	Full read/write	Developers, engineers, builders

---

Using Subagents in Codex

Codex does not auto-spawn custom subagents — you must delegate explicitly in your prompt.

Basic Delegation

Ask the backend-developer subagent to add a POST /api/users endpoint with email validation and bcrypt password hashing.

Use the typescript-pro subagent to refactor src/utils/date.js to TypeScript with strict types.

Have the code-reviewer subagent review the changes in src/auth/ for security issues and best practices.

Multi-Agent Workflow

1. Use the api-designer subagent to design the schema for a payments API
2. Then have the backend-developer subagent implement it
3. Finally, use the security-auditor subagent to review the implementation

With Specific Files

Ask the python-pro subagent to optimize the database queries in app/models/user.py — focus on N+1 query elimination.

---

Creating a Custom Subagent

You can write your own .toml agent and drop it in the agents directory:

# .codex/agents/stripe-integration-expert.toml

name = "stripe-integration-expert"
description = "When working with Stripe payments, webhooks, subscriptions, or billing logic"
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"

[instructions]
text = """
You are a Stripe integration specialist with deep knowledge of:
- Stripe Checkout and Payment Intents API
- Subscription and billing lifecycle management
- Webhook signature verification and event handling
- SCA/3DS compliance
- Stripe CLI for local webhook testing

## Key Patterns

### Always verify webhook signatures
```python
import stripe
from django.http import HttpResponse

def stripe_webhook(request):
    payload = request.body
    sig_header = request.META.get('HTTP_STRIPE_SIGNATURE')
    
    try:
        event = stripe.Webhook.construct_event(
            payload, sig_header, os.environ['STRIPE_WEBHOOK_SECRET']
        )
    except stripe.error.SignatureVerificationError:
        return HttpResponse(status=400)

Use idempotency keys for payment creation

Handle all relevant webhook event types

Never log or expose raw card data

"""

---

## Category Quick Reference

### Core Development (`01-core-development`)

```bash
cp categories/01-core-development/backend-developer.toml ~/.codex/agents/
cp categories/01-core-development/frontend-developer.toml ~/.codex/agents/
cp categories/01-core-development/api-designer.toml ~/.codex/agents/
cp categories/01-core-development/fullstack-developer.toml ~/.codex/agents/
cp categories/01-core-development/ui-fixer.toml ~/.codex/agents/

Language Specialists (02-language-specialists)

# Install just the languages you use
cp categories/02-language-specialists/python-pro.toml ~/.codex/agents/
cp categories/02-language-specialists/typescript-pro.toml ~/.codex/agents/
cp categories/02-language-specialists/golang-pro.toml ~/.codex/agents/
cp categories/02-language-specialists/rust-engineer.toml ~/.codex/agents/
cp categories/02-language-specialists/nextjs-developer.toml ~/.codex/agents/

Infrastructure (03-infrastructure)

cp categories/03-infrastructure/devops-engineer.toml ~/.codex/agents/
cp categories/03-infrastructure/terraform-engineer.toml ~/.codex/agents/
cp categories/03-infrastructure/kubernetes-specialist.toml ~/.codex/agents/
cp categories/03-infrastructure/docker-expert.toml ~/.codex/agents/

Quality & Security (04-quality-security)

cp categories/04-quality-security/code-reviewer.toml ~/.codex/agents/
cp categories/04-quality-security/security-auditor.toml ~/.codex/agents/
cp categories/04-quality-security/qa-expert.toml ~/.codex/agents/
cp categories/04-quality-security/debugger.toml ~/.codex/agents/
cp categories/04-quality-security/performance-engineer.toml ~/.codex/agents/

---

Codex Config Integration

You can also reference agents in .codex/config.toml:

# .codex/config.toml

[agents]
default = "fullstack-developer"

[agents.overrides]
"**/*.test.ts" = "qa-expert"
"**/infra/**" = "terraform-engineer"
"**/*.sql" = "sql-pro"

---

Common Patterns

PR Review Workflow

Use the reviewer subagent to do a PR-style review of all files changed in the last commit. 
Check for correctness, security issues, and potential regressions.

Debugging Workflow

The login endpoint returns 500 for users with special characters in their email.
Ask the debugger subagent to trace through src/auth/login.ts and identify the root cause.

Infrastructure Review

Use the terraform-engineer subagent to review infra/aws/ for security misconfigurations 
and suggest improvements for least-privilege IAM policies.

Tech Stack Specific

Ask the nextjs-developer subagent to migrate pages/dashboard.js to the App Router 
pattern using React Server Components and the new Next.js 14 data fetching conventions.

---

Troubleshooting

Agent Not Found

Error: No agent named 'backend-developer' found

Fix: Ensure the .toml file is in ~/.codex/agents/ or .codex/agents/ and the name field in the TOML matches what you're referencing.

ls ~/.codex/agents/
# Verify the file exists and check the name field:
grep '^name' ~/.codex/agents/backend-developer.toml

Project Agent Not Taking Precedence

Ensure your project-level .codex/agents/ directory is at the repo root (same level as .git/):

ls -la .codex/agents/

Agent Using Wrong Model

Check the model field in the .toml file. Override it for your needs:

# Change from spark to full model for complex tasks
model = "gpt-5.4"
model_reasoning_effort = "high"

Sandbox Permission Errors

If an agent can't write files, check sandbox_mode:

# Change read-only to workspace-write if the agent needs to create files
sandbox_mode = "workspace-write"

---

Bulk Install Script

#!/bin/bash
# install-codex-agents.sh
# Install a curated subset of agents for a typical web project

AGENTS_DIR="${1:-$HOME/.codex/agents}"
REPO_DIR="$(pwd)"

mkdir -p "$AGENTS_DIR"

AGENTS=(
  "categories/01-core-development/backend-developer.toml"
  "categories/01-core-development/frontend-developer.toml"
  "categories/01-core-development/api-designer.toml"
  "categories/02-language-specialists/typescript-pro.toml"
  "categories/02-language-specialists/python-pro.toml"
  "categories/03-infrastructure/devops-engineer.toml"
  "categories/03-infrastructure/docker-expert.toml"
  "categories/04-quality-security/code-reviewer.toml"
  "categories/04-quality-security/debugger.toml"
  "categories/04-quality-security/security-auditor.toml"
)

for agent in "${AGENTS[@]}"; do
  if [ -f "$REPO_DIR/$agent" ]; then
    cp "$REPO_DIR/$agent" "$AGENTS_DIR/"
    echo "✓ Installed $(basename $agent)"
  else
    echo "✗ Not found: $agent"
  fi
done

echo ""
echo "Installed agents to: $AGENTS_DIR"
ls "$AGENTS_DIR"

chmod +x install-codex-agents.sh
./install-codex-agents.sh                        # installs to ~/.codex/agents/
./install-codex-agents.sh .codex/agents/         # installs to project-level

---

Resources

• GitHub Repository
• OpenAI Codex Subagents Docs
• VoltAgent Discord