Codex Subagent Pack

Codex Subagent Pack is a configuration toolkit and installer for multi-agent Codex workflows. It packages specialized helper agents, task boundaries, prompts, model recommendations, and routing rules as repeatable packs powered by GPT-5.6 Sol, Terra, Luna, GPT-5.3-Codex-Spark, compatibility models, or custom providers.

中文说明

Its goal is not simply to add more agents. It routes bounded work to suitable helpers according to task complexity, risk, and type. The parent Codex remains the active coordinator and owns requirement interpretation, architecture and security decisions, final diff review, and user-facing output; subagents focus on concrete work such as codebase exploration, log summarization, targeted implementation, testing, and review.

The tool installs .codex/agents/*.toml, generates an AGENTS.md routing policy, and records the resolved models, reasoning efforts, packs, and managed-file state in .codex-subagent-pack.json. It configures Codex project files; it does not modify the Codex runtime or automatically change the parent model.

Installation

Node.js 20+ and a working Codex CLI installation are required. Run the commands from the root of the project you want to configure.

For a first run, use npx without installing the package in advance:

npx codex-subagent-pack@latest init

To pin the tool version in a project, install it as a development dependency:

npm install --save-dev codex-subagent-pack
npx codex-subagent-pack init

You may also install it globally:

npm install --global codex-subagent-pack
codex-subagent-pack init

Except for the global-install example, this README consistently uses npx codex-subagent-pack. It prefers the project-local version when present; otherwise npm fetches the package temporarily.

Quick Start

# Initialize the standard pack from the project root
npx codex-subagent-pack init --pack standard

# Check the generated configuration and agent files
npx codex-subagent-pack doctor

# Start Codex with the current default parent model
codex

standard is the default pack, so the first command can also be shortened to:

npx codex-subagent-pack init

Project Root Selection

init resolves its target in this order: an explicit --root, the nearest existing .codex-subagent-pack.json within the current Git worktree, the Git worktree root, then the current directory when outside Git. It never walks to a parent package.json.

When the detected target differs from the current directory, init prints both paths and asks for confirmation. Use --yes only when that target is intentional. To install in the exact current directory, including a nested directory inside a Git worktree, run:

npx codex-subagent-pack init --root .

To select the parent model explicitly, run codex -m gpt-5.6-sol. This is only an example of starting Codex: the pack does not require Sol for the parent and never changes the parent model automatically. The active Codex model remains the parent coordinator.

The standard route is:

Agent	Model	Effort
Explorer	gpt-5.6-luna	low
Log summarizer	gpt-5.6-luna	low
Patch worker	gpt-5.6-terra	medium
Test writer	gpt-5.6-terra	medium
Reviewer	gpt-5.6-terra	high

Using It in Codex

After init, start Codex from the project root and describe the goal as usual. The generated AGENTS.md tells the parent which helper agents are installed and records their roles, models, efforts, and sandboxes. When proactive delegation is available, the parent can select a matching agent according to the routing policy.

You can also name an agent explicitly in the task, for example:

First ask csp_codebase_explorer to locate the files and call paths involved in authentication, then have the parent summarize the result.

Ask csp_reviewer to perform a read-only review of the current changes, focusing on regression risks and missing tests. The parent should make the final decision.

Generate more test prompts for the currently installed agents with:

npx codex-subagent-pack test-prompts --all

Verifying Subagent Delegation

If the pack was installed while a Codex task was already open, start a new Codex task after installation and launch it from the same project root. First, verify the installation and generate test prompts that match the current Manifest:

npx codex-subagent-pack doctor
npx codex-subagent-pack test-prompts --all

test-prompts --all generates prompts only for agents actually installed in the current project. To verify the basic delegation path, send this complete prompt to Codex:

Strictly follow the Codex Subagent Pack routing policy in the current project's AGENTS.md and perform a Subagent delegation test.

Requirements:
1. The parent thread must not perform the codebase exploration itself.
2. Explicitly spawn csp_codebase_explorer.
3. Ask that Subagent to inspect the current project's directory structure, main source entry points, and test entry points in read-only mode.
4. The parent must wait for the Subagent to return, then summarize:
   - relevant_files
   - key_symbols
   - execution_path
   - uncertainty
   - recommended_next_action
5. Finally, report the name of the Agent that was actually started.
6. If a Subagent cannot actually be spawned, output SUBAGENT_DISPATCH_FAILED explicitly. Do not simulate or claim that delegation occurred.

Success is determined by the execution or tool-call trace, not merely by a final response claiming that a Subagent was used. The trace must contain a distinct Agent call named csp_codebase_explorer, and the parent must wait for its result before summarizing. The exact presentation varies by Codex surface; a textual claim without a separate Agent call is a failed test.

After explicit delegation succeeds, send the following prompt to test whether the parent proactively selects a helper according to the routing policy:

Analyze the current codebase's main entry points, module boundaries, and test structure, strictly following the routing policy in AGENTS.md. Proactively delegate any clearly bounded, read-only exploration subtask to an installed Helper Agent. In the final response, state which Agent was actually delegated to and how the parent used its result.

Automatic routing depends on how the parent interprets the task boundary, so use the explicit spawn test first as the baseline for installation and delegation capability. If that explicit test fails, check the following in order:

1. A new Codex task was started after installation.
2. Codex was launched from the project root where the pack was installed.
3. .codex/agents/csp_codebase_explorer.toml exists.
4. npx codex-subagent-pack doctor reports no failed checks.
5. The current Codex account can access the model configured for that Agent.

How It Works

1. The parent Codex interprets the goal and retains responsibility for architecture, security, and final approval.
2. A pack provides role-specific agent, model, and reasoning-effort defaults.
3. Following the generated routing policy, Codex delegates bounded exploration, implementation, testing, or review work to matching helpers.
4. Helpers return concise, structured results for the parent to review and integrate.
5. The Manifest records the resolved configuration and managed-file state, while doctor diagnoses installation integrity and configuration drift.

Models and reasoning efforts resolve through per-agent CLI overrides, global CLI overrides, pack configuration, template recommendations, and Model Catalog defaults, in that order. This is reproducible configuration resolved at installation time, not an opaque runtime switch of the parent model.

Why Use It

• Move search results, noisy logs, and local analysis out of the parent context.
• Separate implementation, testing, and review roles to reduce self-review bias.
• Reserve higher-capability models for complex or high-value work while lighter models handle clear, repeatable tasks.
• Package proven roles, prompts, and model routes as reusable workflows across projects.
• Keep configuration traceable, diagnosable, and removable through the Manifest, integrity checks, and explicit safety boundaries.

Model Catalog

npx codex-subagent-pack models list
npx codex-subagent-pack models info gpt-5.6-sol
npx codex-subagent-pack models recommend codebase/explorer

Catalog model IDs are:

• Recommended: gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna
• Specialized preview: gpt-5.3-codex-spark
• Compatibility: gpt-5.5, gpt-5.4, gpt-5.4-mini
• Advanced: custom-provider

The official shorthand gpt-5.6 resolves to gpt-5.6-sol; the canonical ID is stored for reproducible agent configuration. Tier words such as sol, terra, luna, mini, or spark are not standalone model IDs.

Model availability depends on the user's Codex account, plan, workspace, and rollout status. GPT-5.3-Codex-Spark also requires eligible access and is text-only.

Packs

npx codex-subagent-pack init --pack testing
npx codex-subagent-pack init --pack review
npx codex-subagent-pack init --pack fast-coding
npx codex-subagent-pack init --pack spark-fast
npx codex-subagent-pack init --pack compatibility-gpt-5.4
npx codex-subagent-pack init --pack full

testing routes exploration to Luna, test writing to Terra, and strategy to Sol. review uses Terra for exploration and Sol for review work. fast-coding uses Luna and Terra and does not depend on Spark. spark-fast is the explicit text-only Spark path. compatibility-gpt-5.4 uses GPT-5.4 Mini and GPT-5.4. full installs every mature built-in template once.

Inspect packs without installing:

npx codex-subagent-pack packs list
npx codex-subagent-pack packs info standard
npx codex-subagent-pack packs info review

Model And Effort Overrides

Override every agent in a pack:

npx codex-subagent-pack init \
  --pack standard \
  --model gpt-5.6-terra \
  --reasoning-effort medium

Override individual agents:

npx codex-subagent-pack init \
  --pack standard \
  --model-map review/reviewer=gpt-5.6-sol \
  --effort-map review/reviewer=high

The selection precedence is:

1. --model-map / --effort-map
2. --model / --reasoning-effort
3. Per-agent Pack configuration
4. Agent Template recommendation
5. Model Catalog default

Unknown model IDs are rejected unless --allow-unknown-model is explicit. Unknown models are marked isCatalogModel: false; the tool does not claim capability compatibility for them.

Valid reasoning efforts are none, minimal, low, medium, high, xhigh, max, and ultra.

Max and Ultra are reasoning modes, not model IDs. Built-in packs never select them by default. Ultra may proactively delegate additional work on supported models, but helper agents keep agents.max_depth = 1; Ultra is generally most useful on the parent coordinator. The tool never raises agents.max_depth automatically.

Agent Templates

An Agent Template defines role, risk, sandbox, capability requirements, recommended models, reasoning policy, and output contract. Full model metadata lives only in the Model Catalog.

npx codex-subagent-pack agents list
npx codex-subagent-pack agents info codebase/explorer
npx codex-subagent-pack agents add review/reviewer --model gpt-5.6-sol --reasoning-effort high
npx codex-subagent-pack templates validate registry/agents/codebase/explorer
npx codex-subagent-pack templates render registry/agents/codebase/explorer --model gpt-5.6-luna

Generated names use the stable csp_ prefix, such as csp_codebase_explorer, csp_patch_worker, and csp_reviewer.

Community templates may not define provider/auth, scripts, MCP setup, danger-full-access, secret collection, or write-capable custom-provider behavior.

Manifest And Routing Policy

Manifest schema v3 records:

• requested and canonical model selection;
• family, tier, lifecycle, and catalog membership;
• reasoning effort;
• model and reasoning selection sources;
• sandbox, scope, installed pack, and managed-file hashes.

Schema v2 manifests are read and migrated in memory. The next init, packs add, or agents add writes schema v3 without dropping existing Agent records.

The generated AGENTS.md block begins with:

The active Codex model is the parent coordinator.

Its installed-Agent table is generated from the Manifest and includes role, model, effort, and sandbox.

Test And Diagnose

npx codex-subagent-pack doctor
npx codex-subagent-pack test-prompts --model gpt-5.6-luna
npx codex-subagent-pack test-prompts --model gpt-5.6-sol
npx codex-subagent-pack test-prompts --model gpt-5.3-codex-spark
npx codex-subagent-pack test-prompts --all

Test prompts are generated from currently installed project Agents, so they do not tell Codex to spawn names that are absent. doctor compares Manifest model/effort values with Agent TOML, but cannot verify account model access offline. See Verifying Subagent Delegation for the complete procedure and success criteria.

Advanced: Custom Providers

npx codex-subagent-pack provider add openrouter
npx codex-subagent-pack doctor --include-user
npx codex-subagent-pack test-prompts --model custom-provider

Provider safety boundary:

• API key values are never requested or stored.
• Provider/auth configuration is written only to user-level ~/.codex/config.toml.
• Project-level provider/auth is never written.
• The global default model provider is not changed.
• doctor --include-user reports only environment-variable names and presence.
• Custom-provider Agents are read-only; workspace-write Templates reject them.
• Responses-compatible providers are preferred.

custom-provider is a logical Catalog target. The renderer uses the user-configured provider ID and provider model for the actual TOML.

Files Created by init

Project-level:

AGENTS.md
.codex/config.toml
.codex/agents/csp_*.toml
.agents/skills/codex-subagent-pack-router/SKILL.md
.codex-subagent-pack.json

Optional user-level provider setup:

~/.codex/config.toml
~/.codex/agents/csp_alt_explorer.toml
~/.codex/agents/csp_alt_log_summarizer.toml

Codex Subagent Pack has no postinstall script and does not execute community templates as code.

Remove project-level managed files and routing blocks with:

npx codex-subagent-pack remove

Development

npm install
npm run lint
npm test
npm run build
npm pack --dry-run

See the documentation index, architecture, model catalog, registry, template authoring, providers, and security model.

License

MIT