Show HN: File‑based sub‑agents for Codex CLI (tiny MCP server)

[monsieurleon]

I built a tiny MCP server that adds task‑specific sub‑agents to Codex CLI via one tool: delegate. Agents are files (agents/.md|.json) with frontmatter you can review in PRs. DX: list_agents, validate_agents, copy/pasteable setup. Ops: stderr‑only debug and clear trust boundaries; guidance to isolate work with git worktree. Node ≥18; builds to dist/; the server itself makes no runtime network calls.

Under the hood: each call creates a temp workdir, writes AGENTS.md with the agent persona, and runs codex exec --profile <agent-profile> "<task>". For isolation, run in the temp dir (set mirror_repo=true) or point Codex at a worktree; profiles keep state separate.

Repo + docs: https://github.com/leonardsellem/codex-subagents-mcp?utm_sou...

I’d love feedback on safety/ops trade‑offs (e.g., sandbox modes, approvals) and which personas you’d add first (review, debugger, security, perf?).

Non‑goals: not a general‑purpose orchestrator—just a minimal, auditable bridge for Codex CLI.

If it’s useful, issues/PRs and agent recipe contributions are welcome.

[mutant]

this is already done with Agents, i dont understand the point?

[monsieurleon]

Good question. Codex already supports the AGENTS.md file. I’m not trying to replace that.

This project does one narrow thing: it turns those agents into callable, auditable sub‑agents you can invoke at runtime as an MCP tool.

What it adds on top of Agents/AGENTS.md:

- Runtime delegation: a single MCP tool delegate(task, agent|persona, profile, …) that the outer session (or you) can call mid‑flow. Not just “pick one agent at start,” but spin up a specialist for a subtask and return the result.

- Introspection & CI gates: list_agents and validate_agents are exposed as tools so the model (and CI) can see what’s allowed and fail misconfig before anything runs.

- Isolation defaults: each call runs in a temp workdir; you can point Codex at a git worktree/mirror so sub‑agents don’t write into your main repo. Profiles keep state separate.

- Ops hygiene: server is tiny, no stdout (MCP handshake‑safe), debug → stderr only, and the server itself makes no runtime network calls. Small surface area to audit.

Under the hood it still writes AGENTS.md for the selected persona and executes codex exec --profile <agent-profile> "<task>". So if you’re happy manually choosing agents and running codex exec, you don’t need this. If you want in‑session delegation + CI validation + safer defaults with minimal moving parts, that’s the point.

If I’m missing a built‑in way to get all of the above from Agents alone, I’d love a pointer.

[NewMonarch]

You’re a few steps ahead of the person who asked that question.

Just landed on this page from googling for this very thing.

Context Engineering > Prompt Engineering

[monsieurleon]

Appreciate that. Exactly the idea: less prompt-tweaking, more structured context. Glad it was what you were looking for