codex-minions

Sol as orchestrator, cheap minions as workers — natively, in the Codex app UI.

The Codex app (ChatGPT macOS) can spawn subagents on a different, cheaper model than the parent thread. Nobody wires this up by default, so every subagent silently inherits the expensive orchestrator model and you pay gpt-5.6-sol prices for exploration and grunt work. These skills fix that in one shot: two agent roles, registered correctly, the AGENTS.md nudge that makes the model actually use them, and an optional watcher so you can see it working.

Quickstart

npx skills@latest add fernandoeeu/codex-minions

Pick the skills you want and which coding agent to install them on, then run /codex-minions in your agent. Add /codex-minions-notify if you want the macOS notifications.

Or standalone, no repo clone, one-liner each:

# agent roles + config + AGENTS.md
curl -fsSL https://raw.githubusercontent.com/fernandoeeu/codex-minions/main/skills/codex/codex-minions/scripts/install.sh | bash

# optional: macOS notifications with the real model of each spawned subagent
curl -fsSL https://raw.githubusercontent.com/fernandoeeu/codex-minions/main/skills/codex/codex-minions-notify/scripts/install.sh | bash

The install scripts fetch their asset files straight from GitHub raw when they don't find them locally, so curl | bash works without cloning.

The skills

• codex-minions — sets up:
  • ~/.codex/agents/minion.toml — gpt-5.6-terra, low reasoning effort. For exploration, heavy reading, searches, bounded tasks.
  • ~/.codex/agents/worker.toml — gpt-5.6, medium reasoning effort. For code implementation and bounded edits.
  • [agents.minion] / [agents.worker] entries in ~/.codex/config.toml, registering the two files above.
  • A block in ~/.codex/AGENTS.md (between # >>> codex-minions >>> / # <<< codex-minions <<< markers) instructing the model to always pass agent_type explicitly on spawn_agent.
• codex-minions-notify — a launchd watcher for live model visibility (see below).

Nothing here is destructive: existing agent TOMLs are never overwritten, config.toml is only ever appended to (never rewritten), and the AGENTS.md block is only added once.

The catch

Three things make Codex subagent model routing silently not work unless you know about them:

1. Agent files aren't auto-discovered. Putting a .toml in ~/.codex/agents/ does nothing on its own — it has to be registered in ~/.codex/config.toml under [agents.<name>] with a config_file path. Unregistered files are ignored entirely.
2. agent_type doesn't show up in the tool schema the model sees, even though it's a real, accepted parameter of spawn_agent (openai/codex#14579, related: openai/codex#20077). The model has no way of discovering it should pass this field unless something tells it to. See the official docs: developers.openai.com/codex/subagents.
3. No agent_type → the child inherits the parent's model. In the Codex app that parent is gpt-5.6-sol — the expensive orchestrator model. Silently. There's no error, no warning; you just pay sol prices for a subagent that was supposed to be doing cheap grunt work.

The AGENTS.md snippet closes gap #2 by instructing the model to always pass agent_type explicitly, and install.sh closes gap #1 by registering the roles correctly.

The watcher

codex-minions-notify polls ~/.codex/sessions/*.jsonl for thread_spawn events and fires a macOS notification showing which model the spawned child actually ran on — flagged if it's the expensive one. This matters because the Codex app UI does not display the model of a subagent; the field isn't wired to the frontend at all.

Cost: zero tokens. It's pure log-tailing with grep/find, no LLM calls, running once every 3 seconds against files modified in the last 2 minutes.

Check

bash skills/codex/codex-minions/scripts/check.sh

Finds the most recent Codex rollout, lists every subagent it spawned, and prints the agent_role + actual model for each — so you can audit whether your minions really ran cheap.

Uninstall

bash skills/codex/codex-minions/scripts/uninstall.sh
bash skills/codex/codex-minions-notify/scripts/uninstall.sh

The first removes the AGENTS.md block; the second removes the launchd watcher, its plist, and the binary. config.toml and the agent TOMLs are left alone on purpose — those are hand-maintained files and a sed-edit to config.toml is riskier than just telling you what to remove by hand.