# 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/

# 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 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/

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

# 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"

# 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"

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

# 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"

# 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"

# 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"

# 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"

[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"

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]
"""

# 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)

# 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

# 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]"

# 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"

# 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"

# 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"

# 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"

# 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"

# 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"

# ✅ 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"

"@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"