CodexLog

Appearance

Custom Agents in Codex CLI ​

When OpenAI Codex first appeared, developers mostly used it as a single assistant: you'd describe a change, and Codex would suggest or apply edits. That worked, but it left users juggling context—reminding Codex what role to take ("act as a security reviewer," "focus only on TypeScript types," etc.). With the Codex CLI and Codex Cloud, OpenAI has introduced a more structured alternative: Custom Agents.

Custom Agents are specialized AI configurations, stored as files (similar to AGENTS.md) that define role, scope, and permissions. They're automatically invoked when a task matches their description, much like how Codex already auto-selects tools (file read, test run, etc.).

Docs reference: OpenAI Codex documentation on AGENTS.md and configuration confirms that Codex uses project- or user-level configuration files to influence behavior, including agent definitions and tool scopes.

Why Custom Agents Matter ​

  • Automatic Delegation. Codex now routes tasks to the right agent based on context and description fields—no manual invocation required.
  • Separate Context Windows. Each agent operates with its own context window, keeping tasks isolated and avoiding "context poisoning."
  • Specialized Prompts & Tools. Agents can be restricted to only certain tools (e.g., Read + Grep for a security reviewer), reducing risk while improving accuracy.
  • Reusable & Shareable. Because agents are just Markdown/YAML files, they can be versioned, copied across projects, or shared with a team.

This brings Codex closer to an "AI team" model, where each specialist agent mirrors a role you'd normally assign to a human teammate.

Quick Start: Creating a Custom Agent ​

Codex CLI looks for agent definitions in two locations:

TypeLocationScopePriority
Project agents.codex/agents/Current project onlyHighest
User agents~/.codex/agents/All projectsLower

A minimal custom agent file (.codex/agents/security-reviewer.md) might look like this:

yaml
---
name: security-reviewer
description: Security analysis specialist. Reviews code for common vulnerabilities after each change.
tools: Read, Grep, Glob
model: gpt-5-codex
---
You are a senior security engineer.
- Focus on authentication, input validation, and secret management.
- Summarize vulnerabilities, categorize by severity.
- Suggest minimal, safe fixes.

Once saved, Codex will automatically select this agent whenever you ask for a security review.

Basic Usage ​

  • Automatic Invocation. Example:

    codex exec "Review recent changes for security risks"

    Codex will delegate to security-reviewer if the description matches.

  • Manual Invocation. You can explicitly call an agent:

    codex exec --agent security-reviewer "Analyze utils.ts for unsafe eval() usage"

  • Task Delegation. Codex routes tasks intelligently, similar to tool selection.

Best Practices ​

  • Separation of Concerns. Keep each agent tightly scoped (security, performance, UX) for clarity and performance.
  • Provide Examples. Include concrete examples in your agent definitions to improve consistency.
  • Version Control. Check agent definitions into git so your team shares the same specialized behaviors.
  • Tool Restrictions. Limit each agent to only the tools it needs to reduce risk and improve focus.

The Vision: An AI Team ​

Instead of wrestling with a single general-purpose assistant, Custom Agents make Codex feel less like a single assistant and more like a team of AI collaborators. By defining specialized agents with their own prompts, tools, and context, you can scale workflows, reduce error, and share expertise across projects.

The next step is to start building your own arsenal: a security-reviewer, a performance-auditor, a doc-writer. Each agent is just one file—but together, they transform Codex into a flexible, role-aware development platform.

Sources ​