Metadata-Version: 2.4
Name: codex-exec-subagents
Version: 0.1.0
Summary: An unofficial external role runner for the OpenAI Codex CLI
Project-URL: Homepage, https://github.com/antoinezambelli/codex-exec-subagents
Project-URL: Repository, https://github.com/antoinezambelli/codex-exec-subagents
Author: Antoine Zambelli
License-Expression: MIT
License-File: LICENSE
Keywords: agents,cli,codex,orchestration,subagents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://github.com/openai/codex/issues/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`:

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

Or with `wget`:

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

Or install from PyPI with `pipx`:

```bash
pipx install codex-exec-subagents
```

See the
[installation guide](https://github.com/antoinezambelli/codex-exec-subagents/blob/main/docs/installation.md)
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](https://github.com/antoinezambelli/codex-exec-subagents/blob/main/examples/agents/reviewer.toml)
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:

```text
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:

```text
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](https://github.com/antoinezambelli/codex-exec-subagents/blob/main/docs/usage.md)
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](https://github.com/antoinezambelli/codex-exec-subagents/blob/main/docs/installation.md)
- [Roles and usage](https://github.com/antoinezambelli/codex-exec-subagents/blob/main/docs/usage.md)
- [Security, privacy, and retention](https://github.com/antoinezambelli/codex-exec-subagents/blob/main/docs/security.md)
- [Artifact lifecycle and local-security contract](https://github.com/antoinezambelli/codex-exec-subagents/blob/main/docs/artifact-lifecycle.md)
- [Changelog](https://github.com/antoinezambelli/codex-exec-subagents/blob/main/CHANGELOG.md)
- [MIT License](https://github.com/antoinezambelli/codex-exec-subagents/blob/main/LICENSE)
