VoltAgent/awesome-codex-subagents

What is this project?

awesome-codex-subagents is a collection of over 175 pre-built configuration files (called subagents) that you can drop into OpenAI's Codex tool. Each subagent is a specialized AI assistant that focuses on a specific development task — for example, writing backend code, reviewing security, or building a Docker setup. Instead of starting from scratch, you simply copy these files into your Codex setup and call them when needed.

How does it work?

Each subagent is a text file written in TOML (a simple configuration format) that includes:

• Name – what to call the agent.
• Description – when to use it.
• Model – which AI model should handle the task (see below).
• Sandbox mode – whether it can only read files or also write them.
• Instructions – a detailed prompt that tells the AI how to behave (like checklists, patterns, and guidelines).

The subagents are organized into 13 categories — the README shows these six: Core Development, Language Specialists, Infrastructure, Quality & Security, Data & AI, and Developer Experience. The rest are not listed in this excerpt, but the count is 175+ across all categories.

Key design choices

• Smart model routing – Each subagent is assigned one of three AI models based on the job's complexity:
  • gpt-5.6-sol – for deep reasoning (like security audits or architecture reviews).
  • gpt-5.6-terra – for implementation and multi-step professional tasks (like testing or data analysis).
  • gpt-5.6-luna – for lightweight tasks (like search, extraction, or drafting).
• Sandbox mode – reviewers and auditors use read-only (no file changes), while developers use workspace-write (can create/edit files).

How to install and use

1. Clone the repository.
2. Copy the .toml files you want into either:
   • ~/.codex/agents/ – makes the subagent available for all your projects (global).
   • .codex/agents/ inside a specific project – makes it available only for that project (and takes precedence if there's a name clash).
3. Restart or refresh your Codex session.
4. When you want to use a subagent, explicitly mention it in your prompt – Codex does not auto-start them.

Example copy commands:

mkdir -p ~/.codex/agents
cp categories/01-core-development/backend-developer.toml ~/.codex/agents/

Why this matters

Instead of writing your own detailed AI prompts from scratch, you get a tested, task-specific prompt that’s already aligned with Codex’s official documentation. It saves time and gives you fine-tuned behavior for common coding jobs.