awesome-codex-subagents

v2026.09.25
reason-machines/codex-skills00

A curated collection of 136+ specialized Codex subagents for development tasks across 10 categories

GitHub
Install command
npx skhub add reason-machines/awesome-codex-subagents
Markdown
SKILL.md

awesome-codex-subagents

Skill by ara.so — Codex Skills collection.

A definitive collection of 136+ specialized Codex subagents covering development, infrastructure, quality assurance, and domain-specific tasks. Each subagent is a .toml configuration file that extends Codex with focused expertise for specific development scenarios.

What This Project Does

This repository provides pre-configured Codex subagents that you can install to delegate specialized tasks to AI assistants with domain expertise. Instead of asking a general-purpose agent to handle everything, you can explicitly invoke subagents optimized for:

  • Core Development: API design, frontend/backend development, fullstack work
  • Language Specialists: Python, TypeScript, Go, Rust, Java, and 20+ more languages
  • Infrastructure: DevOps, Kubernetes, Terraform, cloud architecture
  • Quality & Security: Testing, security audits, accessibility, code review
  • Data & Analytics: Data engineering, ML pipelines, analytics
  • Content & Documentation: Technical writing, API docs, localization
  • Domain-Specific: Fintech, healthcare, gaming, embedded systems
  • Emerging Tech: Blockchain, AI/ML infrastructure, quantum computing
  • Research & Tools: Web search, academic research, benchmarking

Installation

Global Installation (Available in All Projects)

# Clone the repository
git clone https://github.com/VoltAgent/awesome-codex-subagents.git
cd awesome-codex-subagents

# Create global agents directory
mkdir -p ~/.codex/agents

# Install specific subagents (examples)
cp categories/01-core-development/backend-developer.toml ~/.codex/agents/
cp categories/02-language-specialists/python-pro.toml ~/.codex/agents/
cp categories/03-infrastructure/kubernetes-specialist.toml ~/.codex/agents/

Project-Specific Installation (Higher Precedence)

# In your project root
mkdir -p .codex/agents

# Install project-specific agents
cp path/to/awesome-codex-subagents/categories/04-quality-security/reviewer.toml .codex/agents/
cp path/to/awesome-codex-subagents/categories/02-language-specialists/typescript-pro.toml .codex/agents/

Install All Subagents in a Category

# Install all language specialists globally
mkdir -p ~/.codex/agents
cp categories/02-language-specialists/*.toml ~/.codex/agents/

# Install all infrastructure agents for current project
mkdir -p .codex/agents
cp categories/03-infrastructure/*.toml .codex/agents/

Subagent Structure

Each subagent is a .toml file with this structure:

name = "python-pro"
description = "Python ecosystem master for development, testing, and packaging"
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"

[instructions]
text = """
You are a Python development expert specializing in modern Python 3.10+...

Core Responsibilities:
- Write idiomatic, type-hinted Python code
- Use virtual environments and modern packaging tools
- Implement comprehensive testing with pytest
...
"""

Key Configuration Fields

  • name: Unique identifier for the subagent
  • description: When to invoke this subagent (used by Codex for routing)
  • model: Which GPT model to use (gpt-5.4 for deep reasoning, gpt-5.3-codex-spark for fast tasks)
  • sandbox_mode: Filesystem access (read-only, workspace-write, or full)
  • instructions.text: The system prompt defining the subagent's expertise and behavior

Using Subagents

Explicit Delegation in Prompts

Codex does not auto-spawn custom subagents. You must explicitly delegate:

# Invoke the backend developer subagent
"@backend-developer create a REST API for user management with FastAPI"

# Use the security auditor to review code
"@security-auditor review the authentication module for vulnerabilities"

# Get the Python specialist to refactor code
"@python-pro refactor this script to use type hints and dataclasses"

Multiple Subagents in Sequence

# Design API first, then implement
"@api-designer design a RESTful API for a blog system"
# After reviewing the design:
"@backend-developer implement the blog API using the design from api-designer"

Project-Specific Overrides

If both global and project-specific agents exist with the same name, the project-specific one takes precedence:

# Global agent at ~/.codex/agents/reviewer.toml
# Project agent at .codex/agents/reviewer.toml
# The project version will be used when you invoke @reviewer

Common Patterns

Backend Development Workflow

# 1. Design the API
mkdir -p .codex/agents
cp categories/01-core-development/api-designer.toml .codex/agents/

# 2. Install language-specific agent
cp categories/02-language-specialists/python-pro.toml .codex/agents/

# 3. Add security review
cp categories/04-quality-security/security-auditor.toml .codex/agents/

# Usage:
"@api-designer design a REST API for inventory management"
"@python-pro implement the inventory API with FastAPI and SQLAlchemy"
"@security-auditor review the authentication and authorization logic"

Infrastructure Setup

# Install infrastructure agents
mkdir -p ~/.codex/agents
cp categories/03-infrastructure/terraform-engineer.toml ~/.codex/agents/
cp categories/03-infrastructure/kubernetes-specialist.toml ~/.codex/agents/
cp categories/03-infrastructure/cloud-architect.toml ~/.codex/agents/

# Usage:
"@cloud-architect design AWS infrastructure for a multi-region web app"
"@terraform-engineer write Terraform modules for the AWS design"
"@kubernetes-specialist create Kubernetes manifests for the application"

Full-Stack Feature Development

# Install full-stack agents
cp categories/02-language-specialists/react-specialist.toml .codex/agents/
cp categories/02-language-specialists/nodejs-expert.toml .codex/agents/
cp categories/04-quality-security/e2e-tester.toml .codex/agents/

# Usage:
"@react-specialist build a product listing page with filtering and pagination"
"@nodejs-expert create Express API endpoints for product data"
"@e2e-tester write Playwright tests for the product listing flow"

Code Quality Pipeline

# Install quality agents
cp categories/04-quality-security/reviewer.toml .codex/agents/
cp categories/04-quality-security/test-engineer.toml .codex/agents/
cp categories/04-quality-security/accessibility-tester.toml .codex/agents/

# Usage:
"@reviewer analyze the new payment module for design issues"
"@test-engineer add unit and integration tests for the payment module"
"@accessibility-tester audit the checkout page for WCAG 2.1 AA compliance"

Configuration

Custom Subagent Configuration

Create .codex/config.toml in your project:

[agents]
# Override default models for specific agents
python-pro.model = "gpt-5.4"  # Use more powerful model
reviewer.sandbox_mode = "read-only"  # Restrict to read-only

# Set default reasoning effort
*.model_reasoning_effort = "high"

Creating Custom Subagents

Create a new .toml file in .codex/agents/:

name = "my-custom-agent"
description = "Specialized agent for my team's specific needs"
model = "gpt-5.3-codex-spark"
sandbox_mode = "workspace-write"

[instructions]
text = """
You are a custom development agent for [YOUR TEAM/PROJECT].

Your primary responsibilities:
1. Follow our team's coding standards (link to internal docs)
2. Use our specific tech stack: [list technologies]
3. Implement features according to our architecture patterns

Code Style:
- Use [specific linter/formatter]
- Follow [naming conventions]
- Include [specific testing patterns]

Always:
- Check our internal documentation at [URL]
- Reference our API patterns in [repo location]
- Use our shared component library [package name]
"""

Category Overview

Core Development (12 agents)

  • api-designer - REST and GraphQL API design
  • backend-developer - Server-side development
  • frontend-developer - UI/UX implementation
  • fullstack-developer - End-to-end features
  • mobile-developer - Cross-platform mobile apps

Language Specialists (28 agents)

  • python-pro - Python ecosystem expert
  • typescript-pro - TypeScript development
  • rust-engineer - Systems programming
  • golang-pro - Go concurrency and services
  • react-specialist - React 18+ patterns
  • nextjs-developer - Next.js 14+ full-stack
  • vue-expert - Vue 3 Composition API
  • angular-architect - Angular 15+ enterprise

Infrastructure (16 agents)

  • devops-engineer - CI/CD pipelines
  • kubernetes-specialist - K8s orchestration
  • terraform-engineer - Infrastructure as Code
  • cloud-architect - AWS/GCP/Azure design
  • sre-engineer - Site reliability
  • docker-expert - Container optimization

Quality & Security (16 agents)

  • security-auditor - Vulnerability assessment
  • test-engineer - Testing strategy
  • reviewer - Code review specialist
  • accessibility-tester - WCAG compliance
  • performance-optimizer - Performance tuning

Troubleshooting

Subagent Not Found

# Check if subagent is installed
ls -la ~/.codex/agents/
ls -la .codex/agents/

# Verify the name matches the file
cat .codex/agents/python-pro.toml | grep "^name"

# Restart Codex session
# (Implementation-specific, usually closing and reopening)

Wrong Subagent Responding

# Check for name conflicts
find ~/.codex/agents .codex/agents -name "*.toml" -exec grep "^name" {} \; -print

# Project-specific agents override global ones
# Remove the duplicate or rename one:
mv .codex/agents/python-pro.toml .codex/agents/python-pro-custom.toml

Subagent Not Following Instructions

# Review the instruction text
cat .codex/agents/your-agent.toml

# Ensure description clearly states when to invoke
# Update the instructions section to be more specific:
nano .codex/agents/your-agent.toml

# Be explicit in your delegation:
"@your-agent [very specific task description]"

Performance Issues

# Check model configuration
cat .codex/agents/slow-agent.toml | grep "^model"

# Switch to faster model for simple tasks:
# Change model = "gpt-5.4" to model = "gpt-5.3-codex-spark"

# Reduce reasoning effort in config:
[agents]
slow-agent.model_reasoning_effort = "low"

Sandbox Restrictions

# If agent can't modify files:
# Check sandbox_mode in the .toml file
cat .codex/agents/your-agent.toml | grep "sandbox_mode"

# Update to allow writes:
sandbox_mode = "workspace-write"

# Or for full system access (use cautiously):
sandbox_mode = "full"

Real-World Examples

Example 1: Building a REST API with Python

# Install agents
cp categories/02-language-specialists/python-pro.toml .codex/agents/
cp categories/01-core-development/api-designer.toml .codex/agents/

# Step 1: Design
"@api-designer design a REST API for a task management system with users, projects, and tasks"

# Step 2: Implement
"@python-pro implement the task management API using FastAPI with:
- JWT authentication
- SQLAlchemy models
- Pydantic schemas
- CRUD endpoints for users, projects, and tasks
- PostgreSQL database"

# Step 3: Test
"@python-pro add pytest tests for all endpoints with fixtures and mocks"

Example 2: Infrastructure with Terraform

# Install agents
cp categories/03-infrastructure/terraform-engineer.toml .codex/agents/
cp categories/03-infrastructure/cloud-architect.toml .codex/agents/

# Design infrastructure
"@cloud-architect design AWS infrastructure for a containerized web application with:
- ECS Fargate for compute
- RDS PostgreSQL for database
- ElastiCache Redis for sessions
- ALB for load balancing
- S3 for static assets
- CloudFront for CDN"

# Implement with Terraform
"@terraform-engineer create Terraform modules for the AWS infrastructure design:
- Use remote state in S3
- Separate modules for VPC, ECS, RDS, Redis, ALB
- Variables for environment-specific config
- Outputs for endpoints and connection strings"

Example 3: Frontend Development with React

# Install agents
cp categories/02-language-specialists/react-specialist.toml .codex/agents/
cp categories/02-language-specialists/typescript-pro.toml .codex/agents/

# Build UI component
"@react-specialist create a DataTable component with:
- TypeScript types
- Column sorting
- Pagination
- Row selection
- Filtering
- Virtualized scrolling for large datasets
- Tailwind CSS styling"

# Add tests
"@react-specialist write React Testing Library tests for DataTable covering:
- Rendering with mock data
- Sorting functionality
- Pagination controls
- Filter interactions"

Example 4: Security Review Pipeline

# Install security agents
cp categories/04-quality-security/security-auditor.toml .codex/agents/
cp categories/04-quality-security/dependency-auditor.toml .codex/agents/

# Audit authentication code
"@security-auditor review the authentication system in src/auth/ for:
- SQL injection vulnerabilities
- XSS risks
- CSRF protection
- Session management
- Password hashing
- Rate limiting"

# Check dependencies
"@dependency-auditor scan package.json and identify:
- Known CVEs in dependencies
- Outdated packages with security patches
- License compliance issues
- Recommended updates"

Environment Variables

Subagents should reference environment variables for sensitive data:

# ✅ Correct - use environment variables
import os
DATABASE_URL = os.getenv("DATABASE_URL")
API_KEY = os.getenv("API_KEY")

# ❌ Incorrect - never hardcode secrets
DATABASE_URL = "postgresql://user:pass@localhost/db"
API_KEY = "sk-1234567890abcdef"

When instructing subagents:

"@python-pro create a database connection using the DATABASE_URL environment variable from .env"

"@nodejs-expert set up AWS SDK to use credentials from AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables"

Additional Resources

Contributing

To add custom subagents to your local collection:

  1. Create a new .toml file following the structure above
  2. Place it in .codex/agents/ (project) or ~/.codex/agents/ (global)
  3. Reference the official documentation for advanced configuration options

To contribute to the upstream repository, submit a pull request with your subagent in the appropriate category folder.

Discovery
Tags

No tags published for this skill.

Version
Latest version metadata

Version

v2026.09.25

Published

Sep 25, 2026

Category

Uncategorized

License

NOASSERTION

Source path

skills/awesome-codex-subagents

Default branch

main

Latest commit

901a4e3

Tree SHA

faa2fa4