Skip to content
codex-modules

subagents

codex-subagents runs multiple codex exec workers in parallel and stores every worker result as files. It also reports whether the local Codex binary exposes native multi_agent support.

It does not install hooks, edit Codex config, or modify $CODEX_HOME.

Install

Section titled “Install”
Terminal window
npm install -g @codex-modules/subagents

Or from source:

Terminal window
npm install
npm run build

Use the CLI from this package:

Terminal window
node dist/cli.js doctor

When installed globally or through npm linking, the command is:

Terminal window
codex-subagents doctor

Usage

Section titled “Usage”

Create tasks.jsonl, one TaskSpec per line:

{"id":"map","prompt":"Inspect the source tree and summarize likely entry points.","cwd":"/path/to/repo","sandbox":"read-only","model":"gpt-5.5","effort":"high"}
{"id":"tests","prompt":"Inspect test coverage gaps. Do not edit files.","cwd":"/path/to/repo","sandbox":"read-only","configOverrides":{"agents.max_depth":"1"}}

Run with a concurrency cap:

Terminal window
codex-subagents run --tasks tasks.jsonl --out .work/subagents/run-001 --parallel 2 --timeout 600 --stall 180

Workers do not load $CODEX_HOME/config.toml by default. This prevents user-level hooks, MCP servers, model providers, and other local settings from silently changing an automated run while still allowing Codex to use authentication from the same CODEX_HOME. Pass --inherit-user-config only when the task intentionally depends on those settings.

Outputs:

  • <out>/<id>.md: final message from codex exec -o
  • <out>/<id>.events.jsonl: --json event stream from stdout
  • <out>/<id>.stderr.log: stderr from the worker process
  • <out>/<id>.result.json: atomic completion manifest with the task fingerprint and process exit evidence

Programmatic API:

import { runTasks, detectNative } from "@codex-modules/subagents";


const native = detectNative();
const results = await runTasks(
  [{ id: "one", prompt: "Summarize this repo.", sandbox: "read-only" }],
  { outDir: ".work/subagents/example", parallel: 2 },
);

How It Works

Section titled “How It Works”

The default engine is an external codex exec runner. Each task is spawned as:

codex exec --skip-git-repo-check --ignore-user-config [-C cwd] -s <sandbox> [-m model] [-c model_reasoning_effort=...] [-c k=v ...] [--output-schema file] -o <out>/<id>.md --json --ephemeral <prompt>

The runner passes the prompt as an argv argument and sets worker stdin to the platform null device (/dev/null or NUL). This avoids the known hang case where piped stdin can wait for EOF in automation.

Concurrency is controlled by an in-process semaphore. parallel = 2 means at most two child codex exec processes are open at once.

Stall detection watches the mtimes of the final message, JSONL event stream, and stderr log. If none of them changes for stallSec, the child process tree receives a graceful termination request and then a forced kill after killGraceSec (default: 2 seconds). If wall-clock runtime exceeds timeoutSec, the same escalation runs and the status is timeout.

Each new attempt replaces that task’s old message and logs instead of appending to them. With --resume, a task is skipped only when <id>.result.json records status ok, exit code 0, a matching task fingerprint and execution contract, and all expected artifacts are present. The manifest records the SHA-256 and byte size of the final message, event stream, and stderr log; all three are rehashed before reuse, so replacement, truncation, or modification causes a fail-closed rerun. The execution contract covers the Codex binary identity and bounded codex --version result, effective CODEX_HOME, config-inheritance mode, inherited config.toml/hooks.json contents, artifact layout version, and output-schema contents. Paths and configuration contents are represented only by SHA-256 identifiers in the manifest. A Codex upgrade, binary/home/config/inheritance/schema change, legacy manifest, or stale final-message file therefore causes a rerun.

By default, --ignore-user-config isolates the $CODEX_HOME user config layer. Project-local .codex/config.toml, project hooks, and repository instructions remain part of the task’s selected working directory. Use a dedicated trusted working directory if those project-local inputs must also be controlled. --inherit-user-config restores the older behavior intentionally.

Native multi_agent is diagnostic only in this module. Local Codex versions can report multi_agent as stable and enabled, but related fan-out surfaces such as enable_fanout, multi_agent_v2, and child_agents_md may be under development. For predictable pipeline operation, this package keeps the exec runner as the default and reports native feature state through doctor.

Dangerous sandbox bypass options are intentionally not exposed. Task sandboxes are limited to read-only and workspace-write. configOverrides uses an allowlist limited to model-output tuning, project-document size/fallback settings, tool-output limits, and agent concurrency/depth settings; endpoint, MCP, hook, approval, network, and sandbox configuration cannot be injected through it.

Attribution

Section titled “Attribution”

Runner design references kimsh-1/codex-fleet (MIT): https://github.com/kimsh-1/codex-fleet

Orchestration structure references leonardsellem/codex-specialized-subagents (MIT): https://github.com/leonardsellem/codex-specialized-subagents

This module vendors local kit utilities adapted from modules/config-kit/src/ in this repository. Vendored source files carry // Adapted from modules/config-kit/src/<file>.ts comments.

Uninstall Rollback

Section titled “Uninstall Rollback”

This package does not edit Codex settings, register MCP servers, or write to the real $CODEX_HOME. Rollback is stopping any running codex-subagents process and deleting the output directory you passed with --out.

If installed globally, remove it with your package manager:

Terminal window
npm uninstall -g @codex-modules/subagents