codex-exec-subagents

Run named Codex roles as independent, auditable codex exec sessions.

Unofficial project: This project is not affiliated with or endorsed by OpenAI. Codex is a trademark of OpenAI.

What this is and why it exists

On affected Codex runtimes, the native spawn tool can no longer select a configured custom role. A child may quietly run without that role's model, reasoning effort, sandbox, or instructions (upstream issue #31097).

That is especially wasteful when the main conversation runs on GPT-5.6-Sol. Sol is useful as the orchestrator, but it is overkill for every repository search or first-pass review. A configured GPT-5.6-Terra or Luna role should be able to do that cheaper work; on affected runtimes, the Sol session cannot reliably select it through the native tool.

codex-exec-subagents is a practical workaround until that is fixed. It launches the role you choose in an independent Codex session, returns a durable handle, and keeps local evidence of what was requested and what Codex returned. You can inspect a run, wait for it, read its result, and continue the exact same Codex thread later.

These are external sessions, not native subagents. They do not inherit hidden parent-chat context or appear in a parent session's subagent UI. Give each role a self-contained task and working directory.

Install

The supported platform is native Linux with Python 3.11 or newer and the Codex CLI already available on PATH.

Install or update with curl:

curl -fsSL https://antoinezambelli.github.io/codex-exec-subagents/install.sh | sh

Or with wget:

wget -qO- https://antoinezambelli.github.io/codex-exec-subagents/install.sh | sh

Or install from PyPI with pipx:

pipx install codex-exec-subagents

See the installation guide for prerequisites, inspect-first installation, version pins, custom paths, updates, rollback, uninstall, and development setup.

Use

The model comes from the role file under ~/.codex/agents/, not from the Sol conversation. The bundled reviewer example uses GPT-5.6-Terra with medium reasoning and a read-only sandbox. Print it with codex-exec-subagents example-role reviewer if you need a starting point.

Once the role exists, tell your main Codex session:

Use the installed codex-exec-subagents command for this task.

First read `codex-exec-subagents --help`. Then dispatch the global `reviewer`
role against the current repository in sandboxed mode. Ask it to map the
packaging and installation flow without editing files. Run it detached, keep
the returned handle, wait for completion, and give me the reviewer's result
with the handle and final status. Do not perform the exploration in this Sol
session.

The Sol session remains the orchestrator while the Terra role performs the bounded exploration. The returned handle also gives the parent a durable run to inspect instead of relying on a silent native handoff.

For a follow-up, tell the same conversation:

Use the same codex-exec-subagents handle to ask the reviewer to inspect the
release workflow next. Wait for that turn and bring back its result and final
status.

Codex runs the underlying commands through its shell tools. You can run those commands directly from Bash too. See the usage guide for role setup, direct CLI examples, execution policy, lifecycle commands, run roots, pruning, and troubleshooting.

Durable evidence

Each invocation retains its prompt, Codex event stream, stderr, final message, status, and receipt under ~/.codex/codex-exec-subagents/runs/. The receipt records the requested role, model, effort, instructions, working directory, effective sandbox policy, process outcome, and exact Codex thread ID.

This evidence shows what the runner requested, what Codex emitted, and whether transport-level verification succeeded. It does not prove that the model semantically followed its role instructions; inspect the result and any repository changes accordingly.

Documentation

• Installation
• Roles and usage
• Security, privacy, and retention
• Artifact lifecycle and local-security contract
• Changelog
• MIT License