Codex Subagent Harness

Codex Subagent Harness is an unofficial, opinionated configuration-and-skill layer for coordinating Codex subagent workflows. It is not a replacement or reimplementation of the Codex harness, agent loop, or App Server.

The package keeps the main agent in a supervisor role, gives normal non-trivial implementation to exactly one writer, and runs an independent review after the diff exists. It was tested with Codex as of 2026-07-22. Codex custom-agent configuration may evolve, so review current Codex documentation before adopting it in a long-lived environment.

Quick install

Download or clone this repository, inspect install.py, the template, and the dry-run output, then run the installer locally. This project intentionally does not provide a curl-to-shell command.

Project installation is recommended. The repository must already exist, its path must be absolute, and Codex will load its .codex/config.toml only after you mark the project as trusted:

python3 install.py --layout project --root /absolute/path/to/repository
python3 install.py --layout project --root /absolute/path/to/repository --apply

Global installation defaults to CODEX_HOME when set, otherwise ~/.codex. Skills go to ~/.agents/skills by default; an existing legacy ~/.codex/skills/execution-harness is reused when the official location is absent. Override the skill parent directory with --skills-root when needed.

python3 install.py --layout global
python3 install.py --layout global --apply

Dry-run is the default and performs the complete preflight without changing the target or creating a backup. --apply is always explicit and non-interactive. Review the paths and semantic-conflict note before applying; installation remains your responsibility.

V1 is additive-only: it never updates, replaces, or upgrades a pre-existing destination file. The installer preserves an existing valid config.toml byte-for-byte, including comments, custom models, effort, limits, plugins, trust settings, and notifications. It relies on Codex's standalone custom-agent discovery instead of inserting missing registration tables. A missing config receives the exact strict template. Installation stops before writing when multi-agent is explicitly disabled, a same-name registration is ambiguous, managed files differ, a managed guidance block was edited, or a protected path is unsafe.

If AGENTS.md is absent, the installer creates versioned, hashed guidance. Any existing AGENTS.md stays byte-identical. When it lacks the harness guidance, the plan warns that automatic routing was skipped: the installation remains usable by explicitly invoking $execution-harness, while automatic routing requires a manual merge. Existing agent and skill files must be absent or byte-identical; v1 has no overwrite, upgrade, or force option.

On apply, each create-only path is recorded in a private creation journal. Its default parent is $CODEX_HOME/backups/codex-subagent-harness/... when CODEX_HOME is set, otherwise ~/.codex/backups/codex-subagent-harness/...; --backup-root selects another private parent. V1 intentionally has no public automatic rollback. Expert manual undo means: work deepest path first, verify the current file SHA-256 still equals its manifest after_sha256, then remove only that exact created file; never remove a changed file or a nonempty directory. Journal entries always have existed: false and contain no original-file payloads.

Safe apply requires POSIX descriptor-relative operations, O_DIRECTORY, O_NOFOLLOW, and atomic hard-link publication. Unsupported platforms, including Windows, refuse --apply and must use the reviewed manual installation path. A failure after publication can leave additive-only files in place: the installer never automatically deletes or replaces destination files. Stop concurrent writers, inspect the journal, and manually remove a file only after verifying its path, SHA-256, device, and inode; otherwise keep it and rerun when identical. No transactionality or power-loss recovery is claimed.

What is included

The neutral template/ layout contains:

template/
├── AGENTS.md
├── config.toml
├── agents/
│   ├── architect.toml
│   ├── explorer.toml
│   ├── implementer.toml
│   ├── reviewer.toml
│   └── tester.toml
└── skills/
    └── execution-harness/

The installed skill is invoked as $execution-harness.

Name collision: installing the included custom agent as explorer overrides Codex's built-in explorer under that name. This repository intentionally keeps the simple role name instead of namespacing it.

Shipped strict profile

Role	Model	Effort	Requested sandbox	Purpose
Main	gpt-5.6-sol	xhigh	Environment-defined	Requirements, decisions, coordination, synthesis
explorer	gpt-5.6-terra	low	read-only	Bounded repository mapping
architect	gpt-5.6-sol	xhigh	read-only	Consequential design decisions
implementer	gpt-5.6-sol	medium	workspace-write	One coherent write package
tester	gpt-5.6-terra	low	workspace-write	Verification without source fixes
reviewer	gpt-5.6-sol	high	read-only	Independent review after implementation

These gpt-5.6-sol and gpt-5.6-terra assignments are an opinionated strict profile, not a universal best practice. If a model is unavailable in your Codex environment, use an available model and validate the resulting profile as described below. A requested sandbox_mode may still be constrained or superseded by the active environment permission profile.

The shipped configuration uses max_threads = 6, max_depth = 1, and interrupt_message = true. max_threads is the cap on concurrently open agent threads; it is not simply a count of subagents executing at the same instant. These are default-profile values and may be tuned for your environment.

Requirements

• A Codex version with custom agents and multi-agent support
• Python 3.11 or newer (tomllib is used by the validator)

Manual project-scoped installation

Project scope limits the effect of the harness and is the recommended default. Back up or review any existing files first; do not blindly overwrite existing AGENTS.md or Codex configuration.

Codex loads a project's .codex/config.toml only after that project has been marked as trusted. Review the repository first and accept the trust prompt only when appropriate.

Map the neutral template into a repository as follows:

Source	Destination
template/AGENTS.md	<repo>/AGENTS.md
template/config.toml	<repo>/.codex/config.toml
template/agents/	<repo>/.codex/agents/
template/skills/execution-harness/	<repo>/.agents/skills/execution-harness/

This is the optional manual path. Merge repository-specific guidance into AGENTS.md. Merging relevant TOML tables into an existing <repo>/.codex/config.toml opts into the strict main profile; unlike this manual procedure, install.py preserves an existing valid config byte-for-byte. The provided configuration references ./agents/*.toml from the .codex configuration directory.

After mapping, validate the installed project layout from any directory:

python3 <repo>/.agents/skills/execution-harness/scripts/validate_harness.py \
  --layout project --root <repo>
python3 <repo>/.agents/skills/execution-harness/scripts/validate_harness.py \
  --layout project --root <repo> --strict-profile

Then restart Codex and open a new session in the trusted repository. First, confirm that $execution-harness is discoverable as an available skill; do not invoke it for this read-only check. Separately, explicitly ask Codex to use or spawn the custom explorer for one bounded read-only repository-mapping task, and confirm from the resulting agent activity that the custom role was used before relying on the setup for writes. The exact activity display may vary by Codex version.

Manual global installation

For a user-wide setup, merge rather than replace:

Source	Destination
template/AGENTS.md	~/.codex/AGENTS.md
Harness blocks from template/config.toml	Matching tables in ~/.codex/config.toml
template/agents/	~/.codex/agents/
template/skills/execution-harness/	~/.agents/skills/execution-harness/

~/.agents/skills/execution-harness is the official user skill location. Existing Codex installations may instead keep this skill at ~/.codex/skills/execution-harness; the validator retains that legacy fallback.

Do not replace a complete ~/.codex/config.toml with the minimal template: personal trust settings, plugins, notifications, and other unrelated configuration must be preserved. Restart Codex after changing global agent registration.

Validate the official global layout with:

python3 ~/.agents/skills/execution-harness/scripts/validate_harness.py \
  --layout global --root ~/.codex
python3 ~/.agents/skills/execution-harness/scripts/validate_harness.py \
  --layout global --root ~/.codex --strict-profile

For a legacy skill under ~/.codex/skills, run the same commands from that script and add --skills-root ~/.codex/skills. Restart Codex, open a new session, and confirm the five custom roles are listed before using the harness for implementation.

Profile customization

Normal validation checks TOML parsing, agent registration and references, required role fields, skill structure, and core safety guidance without enforcing exact models, efforts, sandboxes, or agent limits:

python3 template/skills/execution-harness/scripts/validate_harness.py \
  --layout template --root template

The strict check intentionally verifies the exact shipped profile across config.toml and all five role TOMLs:

python3 template/skills/execution-harness/scripts/validate_harness.py \
  --layout template --root template --strict-profile

When customizing models or effort, keep related documentation and role configuration internally consistent. Normal validation should continue to pass; --strict-profile will intentionally fail until the validator's strict profile constants and the profile documentation are synchronized with your chosen fork. Use rg 'gpt-5\.6|reasoning_effort|max_threads|max_depth|interrupt_message' template to review the profile surface instead of relying on a brittle manual file list.

For installer-created targets with a pre-existing preserved config, use structural validation. Strict validation is expected only when the installed config is the fresh, exact template (or has been deliberately synchronized to that profile).

Operating guarantees

• The main agent supervises requirements, decomposition, sequencing, conflicts, and final synthesis.
• Normal non-trivial changes use exactly one implementer writer, followed by an independent reviewer after the diff exists.
• Exploration, architecture decisions, and review remain read-only; the tester may write only normal test caches or temporary artifacts.
• Concurrent writers never share one checkout. Parallel write packages require separate worktrees, disjoint ownership, and one integration owner.
• Commit, push, PR, deploy, database, secret, and other external writes require an explicit user request.
• Verification starts with the narrowest meaningful check and expands in proportion to risk.

See README.ja.md for Japanese documentation.

License

MIT