Skip to content
Back to search

codex-subagents-mcp

Claude-style sub-agents (reviewer, debugger, security) for Codex CLI via a tiny MCP server. Each call spins up a clean context in a temp workdir, injects a persona via AGENTS.md, and runs codex exec --profile <agent> to preserve isolated state.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/leonardsellem--codex-subagents-mcp/badge.svg)](/listings/leonardsellem--codex-subagents-mcp)

HTML

<a href="/listings/leonardsellem--codex-subagents-mcp"><img src="/api/listings/leonardsellem--codex-subagents-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

- Prereqs: Node.js >= 18, npm, Codex CLI installed and on PATH. - Install deps and build:

npm install
npm run build

- Start server (manual run):

npm start

Tools exposed by this server: - Primary: `delegate` - Support: `list_agents`, `validate_agents`

Agents directory discovery (in order): `--agents-dir` arg, `CODEX_SUBAGENTS_DIR` env, then defaults `./agents`, `./.codex-subagents/agents`, `dist/../agents`.

60‑second Quickstart (copy‑paste)

# 1) Install + build
npm i && npm run build

# 2) Point Codex at the built server (absolute paths recommended)
# ~/.codex/config.toml
[mcp_servers.subagents]
command = "/usr/bin/env"
args    = ["node", "/ABS/PATH/TO/dist/codex-subagents.mcp.js", "--agents-dir", "/ABS/PATH/TO/agents"]

# Example profiles you can reference from agent frontmatter
[profiles.review]
model = "gpt-5"
approval_policy = "on-request"
sandbox_mode    = "read-only"

[profiles.debugger]
model = "o3"
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

# 3) In Codex, verify tools and agents
tools.call name=list_agents
tools.call name=validate_agents

# 4) Delegate one task to an agent
subagents.delegate(agent="review", task="Summarize and review the last commit")

Tip: See `docs/SECURITY.md` for trust boundaries and `docs/OPERATIONS.md` for E2E and logging.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 310 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # codex-subagents-mcp
  2. [![CI](https://github.com/leonardsellem/codex-subagents-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/leonardsellem/codex-subagents-mcp/actions/workflows/ci.yml)
  3. ![Node >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)
  4. ![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
  5. ![GitHub stars](https://img.shields.io/github/stars/leonardsellem/codex-subagents-mcp?style=social)
  6. > **Status: Archived.** This repo is no longer maintained.
  7. >
  8. > I’m restarting this project from scratch with a new approach in: https://github.com/leonardsellem/codex-specialized-subagents
  9. File‑based sub‑agents for Codex CLI. One MCP tool. Zero fluff.
  10. - Auditable: agents are files reviewed in PRs
  11. - CI‑friendly: `validate_agents`, `list_agents`
  12. - Safer ops: temp workdirs, quiet stdout, git worktree isolation
  13. Claude‑style sub‑agents for Codex CLI via a tiny MCP server. Each call spins up a clean context in a temp workdir, injects a persona via `AGENTS.md`, and runs `codex exec --profile <agent>` to preserve isolated state.
  14. ## Quickstart
  15. - Prereqs: Node.js >= 18, npm, Codex CLI installed and on PATH.
  16. - Install deps and build:
  17. ```
  18. npm install
  19. npm run build
  20. ```
  21. - Start server (manual run):
  22. ```
  23. npm start
  24. ```
  25. Tools exposed by this server:
  26. - Primary: `delegate`
  27. - Support: `list_agents`, `validate_agents`
  28. Agents directory discovery (in order): `--agents-dir` arg, `CODEX_SUBAGENTS_DIR` env, then defaults `./agents`, `./.codex-subagents/agents`, `dist/../agents`.
  29. ### 60‑second Quickstart (copy‑paste)
  30. ```
  31. # 1) Install + build
  32. npm i && npm run build
  33. # 2) Point Codex at the built server (absolute paths recommended)
  34. # ~/.codex/config.toml
  35. [mcp_servers.subagents]
  36. command = "/usr/bin/env"
  37. args = ["node", "/ABS/PATH/TO/dist/codex-subagents.mcp.js", "--agents-dir", "/ABS/PATH/TO/agents"]
  38. # Example profiles you can reference from agent frontmatter
  39. [profiles.review]
  40. model = "gpt-5"
  41. approval_policy = "on-request"
  42. sandbox_mode = "read-only"
  43. [profiles.debugger]
  44. model = "o3"
  45. approval_policy = "on-request"
  46. sandbox_mode = "workspace-write"
  47. # 3) In Codex, verify tools and agents
  48. tools.call name=list_agents
  49. tools.call name=validate_agents
  50. # 4) Delegate one task to an agent
  51. subagents.delegate(agent="review", task="Summarize and review the last commit")
  52. ```
  53. Tip: See `docs/SECURITY.md` for trust boundaries and `docs/OPERATIONS.md` for E2E and logging.
  54. ## Wiring with Codex CLI
  55. Build the server and point Codex at the **absolute** path to the compiled entrypoint. Pass the agents directory explicitly so the server doesn't scan until after the handshake. The server also falls back to an `agents/` folder adjacent to the installed binary (e.g. `dist/../agents`) if `--agents-dir` and `CODEX_SUBAGENTS_DIR` are not provided:
  56. ```
  57. # ~/.codex/config.toml
  58. [mcp_servers.subagents]
  59. command = "/absolute/path/to/node"
  60. args = ["/absolute/path/to/dist/codex-subagents.mcp.js", "--agents-dir", "/absolute/path/to/agents"]
  61. [profiles.review]
  62. model = "gpt-5"
  63. approval_policy = "on-request"
  64. sandbox_mode = "read-only"
  65. [profiles.debugger]
  66. model = "o3"
  67. approval_policy = "on-request"
  68. sandbox_mode = "workspace-write"
  69. [profiles.security]
  70. model = "gpt-5"
  71. approval_policy = "never"
  72. sandbox_mode = "workspace-write"
  73. ```
  74. Usage (in Codex):
  75. - “Review my last commit. Use the review sub-agent.”
  76. - “Reproduce and fix the failing tests in api/ using the debugger sub-agent.”
  77. - “Audit for secrets and unsafe shell calls; propose fixes with rationale using the security sub-agent.”
  78. ## AGENTS hint to drop into your repo’s `AGENTS.md`
  79. ```
  80. Route all work through the orchestrator:
  81. subagents.delegate(agent="orchestrator", task="<goal>")
  82. Example security review routed via orchestrator:
  83. subagents.delegate(agent="orchestrator", task="Audit the repo for secrets and unsafe shell calls")
  84. Prefer tool calls over in-thread analysis to keep the main context clean.
  85. ```
  86. Note: MCP servers run outside Codex’s sandbox. Keep surfaces narrow and audited. This server exposes a single tool: `delegate`.
  87. ## Who This Is For / Not For
  88. - For: teams already on Codex CLI who want auditable specialist agents and CI gating.
  89. - Not for: folks seeking a general agent framework or multi‑tool orchestrator.
  90. ## Terminology: Agents vs Profiles
  91. - `agent` (what you pass to `subagents.delegate`): the name of an agent loaded from your registry directory. The name is the file basename, e.g., `agents/review.md` → agent `review`.
  92. - `profile` (Codex CLI): an execution profile you define in `~/.codex/config.toml` under `[profiles.<name>]`. Agents typically specify which profile to use via frontmatter (`profile: <name>`), but agent names and profile names don’t have to match.
  93. There are no hardcoded built‑in agent names. The server loads agents from disk (`agents/*.md|*.json`) or accepts an ad‑hoc agent when both `persona` and `profile` are provided inline.
  94. ## Tool: `delegate`
  95. - Parameters:
  96. - `agent`: string — the agent name from your registry (basename of `agents/<name>.md|json`)
  97. - `task`: string (required)
  98. - `cwd?`: string (defaults to current working directory)
  99. - `mirror_repo?`: boolean (default false). If true and `cwd` provided, mirrors the repo into the temp workdir for maximal isolation.
  100. - `profile?` and `persona?`: optional ad-hoc definition when `agent` is not found in registry. Provide both.
  101. - Behavior:
  102. 1. Creates a temp workdir; writes `AGENTS.md` with the agent persona.
  103. 2. Optionally mirrors the repo into the temp dir via `cp -R` fast path.
  104. - Safer alternative (recommended for large repos): `git worktree add <tempdir> <branch-or-HEAD>` (documented in `docs/INTEGRATION.md`).
  105. 3. Spawns `codex exec --profile <agent-profile> "<task>"` with `cwd` set to the temp dir if mirrored, else your provided `cwd`.
  106. 4. Returns JSON: `{ ok, code, stdout, stderr, working_dir }`.
  107. ## Custom agents
  108. Add agents without code changes:
  109. 1) File-based registry (recommended)
  110. - Create an agents directory and point the server to it via either:
  111. - Config args: add `"--agents-dir", "/path/to/agents"` in `~/.codex/config.toml` under the MCP server args
  112. - Env var: `CODEX_SUBAGENTS_DIR=/path/to/agents`
  113. - Defaults (auto-detected): `./agents` or `./.codex-subagents/agents`
  114. - Define agents as files using the basename as the agent name:
  115. Example `agents/perf.md`:
  116. ```
  117. ---
  118. profile: debugger
  119. approval_policy: on-request # one of: never | on-request | on-failure | untrusted
  120. sandbox_mode: workspace-write # one of: read-only | workspace-write | danger-full-access
  121. ---
  122. You are a pragmatic performance analyst. Identify hotspots, measure, propose minimal fixes with benchmarks.
  123. ```
  124. Or JSON `agents/migrations.json`:
  125. ```
  126. {
  127. "profile": "debugger",
  128. "approval_policy": "on-request",
  129. "sandbox_mode": "workspace-write",
  130. "persona": "You plan and validate safe DB migrations with rollbacks.",
  131. "personaFile": null
  132. }
  133. ```
  134. 2) Ad-hoc agent via tool params
  135. Call `delegate` with a new name and supply both `profile` and `persona`:
  136. ```
  137. subagents.delegate(
  138. agent="perf",
  139. task="Analyze render jank",
  140. profile="debugger",
  141. approval_policy="on-request",
  142. sandbox_mode="workspace-write",
  143. persona="You are a perf specialist..."
  144. )
  145. ```
  146. List available agents:
  147. ```
  148. tools.call name=list_agents
  149. ```
  150. Validation: `approval_policy` and `sandbox_mode` are validated against the allowed values above. They are advisory metadata and should match the Codex profile you run under. Enforce actual behavior via profiles in `~/.codex/config.toml`.
  151. Validate agent files:
  152. ```
  153. tools.call name=validate_agents
  154. # or
  155. tools.call name=validate_agents arguments={"dir":"/abs/path/to/agents"}
  156. ```
  157. Returns per-file errors/warnings and a summary. Invalid values are flagged; missing `profile` in Markdown is a warning (loader defaults to `default`).
  158. ## Build, Lint, Test
  159. ```
  160. npm install
  161. npm run build
  162. npm run lint
  163. npm test
  164. ```
  165. Note: Do not edit `dist/` manually; it is build output.
  166. ## E2E Demo
  167. Automated end-to-end check using the real Codex CLI:
  168. ```
  169. npm run e2e
  170. ```
  171. It will:
  172. 1. Build the project.
  173. 2. Write a temporary `~/.codex/config.toml` pointing to the built server.
  174. 3. Run `/mcp` to verify the server is connected.
  175. 4. Pick the first agent on disk and call `subagents.delegate`.
  176. The script requires `OPENAI_API_KEY` and a working Codex CLI binary.
  177. ## Safety & Operations
  178. | Concern | This repo does |
  179. | --- | --- |
  180. | Prevent handshake break | No stdout logs; debug only to stderr (`DEBUG_MCP=1`) |
  181. | Reduce blast radius | Temp workdir + optional `git worktree` isolation |
  182. | Gate risky personas | `validate_agents` + profiles/approvals alignment |
  183. | Network surface | Single tool (`delegate`); Codex handles model I/O |
  184. | Auditability | Agents live as files; reviewable in PRs |
  185. ## Troubleshooting MCP timeouts
  186. > Warning: Stdout must be newline‑delimited JSON only. Any logs on stdout will break the MCP handshake. Use `DEBUG_MCP=1` to emit diagnostics to stderr.
  187. - “codex not found”: Install Codex CLI and ensure it is on PATH. Re-run `npm run e2e`.
  188. - Timeout on startup: confirm the config points at the absolute `dist/codex-subagents.mcp.js` path and passes `--agents-dir`.
  189. - Logs on stdout break the handshake. Set `DEBUG_MCP=1` to log timing to stderr only.
  190. - The server speaks newline-delimited JSON; older configs expecting HTTP headers will stall.
  191. - Large repos: prefer `git worktree` over `mirror_repo=true` (see `docs/INTEGRATION.md`).
  192. - Slow start: agent files are loaded lazily after initialization.
  193. ## Agent Recipes (starter personas)
  194. These come as file‑based agents under `agents/`. Each link includes a one‑line goal and suggested metadata (frontmatter).
  195. - `agents/review.md`: Code review and refactor checklist. Frontmatter: `profile: review` (suggested: `approval_policy: on-request`, `sandbox_mode: read-only`).
  196. - `agents/debugger.md`: Reproduce failures and propose minimal fixes. Frontmatter: `profile: debugger` (suggested: `approval_policy: on-request`, `sandbox_mode: workspace-write`).
  197. - `agents/security.md`: Threat modeling and concrete mitigations. Frontmatter: `profile: security` (suggested: `approval_policy: never`, `sandbox_mode: workspace-write`).
  198. - `agents/perf.md`: Identify hotspots; measure and optimize. Frontmatter: `profile: default` (suggested: `approval_policy: on-request`, `sandbox_mode: workspace-write`).
  199. - `agents/docs.md`: Improve and restructure docs. Frontmatter: `profile: default` (suggested: `approval_policy: on-request`, `sandbox_mode: read-only`).
  200. - `agents/a11y.md`: Accessibility reviews and fixes. Frontmatter: `profile: default` (suggested: `approval_policy: on-request`, `sandbox_mode: read-only`).
  201. Invite PRs that add new agents—see “Contribute an agent”.
  202. ## Contribute an agent (fast path)
  203. 1. Fork and create `agents/<name>.md` with frontmatter:
  204. ```yaml
  205. profile: debugger
  206. approval_policy: on-request
  207. sandbox_mode: workspace-write
  208. ```
  209. Then describe the persona in free text.
  210. 2. Run `tools.call name=validate_agents`.
  211. 3. Open a PR using the “Agent request / contribution” template.
  212. We track requested personas in GitHub Discussions (open a new topic under Show & Tell if none exists yet).
  213. ## Comparisons
  214. - vs. building your own MCP server: this repo keeps a single tool and file‑based agents to minimize attack surface.
  215. - vs. complex orchestrators: this intentionally avoids graphs/routers—Codex CLI profiles + file personas keep it simple.
  216. If this project helps, a star helps others discover it.
  217. ## Docs
  218. - `docs/INTEGRATION.md`: deeper wiring, profiles, AGENTS.md guidance.
  219. - `docs/SECURITY.md`: isolation, trust boundaries, sandbox guidance.
  220. - `docs/OPERATIONS.md`: logs, env vars, upgrades.
  221. ## License
  222. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.