codex-subagents-mcp AGENTS.md

Agents

Author custom sub‑agents without code changes by adding files to an agents registry directory. The MCP server loads definitions from agents/*.md and agents/*.json. Agent names map to file basenames (e.g., agents/perf.md registers agent perf). The server may include a few example built‑ins for demos, but prefer files on disk (or use an ad‑hoc inline agent when both persona and profile are provided).

• Point the server to your agents directory via --agents-dir or CODEX_SUBAGENTS_DIR. It also auto-detects ./agents or ./.codex-subagents/agents when not provided.
• Keep personas task‑oriented and concise; avoid generic, unfocused instructions.

Markdown agent (frontmatter + persona)

Create agents/<name>.md:

---
profile: debugger
approval_policy: on-request   # never | on-request | on-failure | untrusted
sandbox_mode: workspace-write # read-only | workspace-write | danger-full-access
---
You are a pragmatic performance analyst. Identify hotspots, propose minimal, measurable fixes, and outline validation steps with lightweight metrics.

Required: profile (loader defaults to default if omitted). Optional: approval_policy, sandbox_mode. The body is the persona text injected for the sub‑agent.

JSON agent

Create agents/<name>.json:

{
  "profile": "debugger",
  "persona": "You plan and validate safe DB migrations with rollbacks.",
  "approval_policy": "on-request",
  "sandbox_mode": "workspace-write"
}

Required: profile, persona. Optional: approval_policy, sandbox_mode.

Tips

• Validate registry: tools.call name=validate_agents (optionally pass { "dir": "/abs/path" }).
• List available agents: tools.call name=list_agents.
• Align metadata with Codex profiles you run under; enforce behavior in ~/.codex/config.toml.
• Keep personas short, specific, and action‑biased; prefer concrete checklists over philosophy.
• See also: docs/OPERATIONS.md.

Usage Hint

When a task matches a sub‑agent specialty, call the MCP tool: