Harness for Codex

English | 한국어 | 日本語

A project-scoped harness factory for Codex. It inspects a project, designs a small team, and creates native Codex agents and reusable skills. A parent orchestrator schedules independent tasks in parallel, integrates the results, and owns final verification.

This is an independent migration of revfactory/harness, based on upstream commit cceac68. The original project’s team-design workflow and six architecture patterns are adapted to Codex. Upstream Claude Code benchmarks do not establish performance for this migration.

Install as a plugin (recommended)

Run these two commands in your terminal. You do not need to clone this repository or run the Python installer:

Add Marketplace

codex plugin marketplace add https://github.com/revfactory/codex-harness.git

Add Plugin

codex plugin add codex-harness@codex-harness

Open your target project in a new Codex session, then send:

$harness Write a short blog post about organizing a new project and save it to article.md.

Explicitly invoking $harness (or $codex-harness:harness) builds or updates a durable harness in the current target project by default, even when the rest of the request is an ordinary content task. It then performs that task. An explicit read-only request or instruction not to build a harness takes precedence. Agent definitions live under the target project’s .codex/agents/*.toml; reusable skills live under .agents/skills/. The harness adds an AGENTS.md pointer, project configuration, and run records as appropriate. When Codex is started in the target project, native agents work there rather than in the plugin cache. Plugin installation alone creates no project files. The optional project installer supplies the predefined five-role team; invocation chooses roles for the actual project.

Start Codex in that project (codex -C /absolute/path/to/project) before using its agents: native spawn has no cwd parameter and inherits the parent project’s session directory. If the current session started elsewhere, bootstrap files can be written in the target with an explicit workdir, but start a fresh session in the target before spawning agents. See quickstart troubleshooting for protected-directory write failures.

The command syntax above was checked against Codex CLI 0.153.4. After adding the marketplace, you can also use /plugins in the CLI to select Codex Harness → Harness for Codex → Install, then start a new session. See quickstart for desktop installation, a local-checkout option, and troubleshooting. Official plugin guide.

Start in this checkout (for development)

Clone the repository:

git clone https://github.com/revfactory/codex-harness.git
cd codex-harness

Open this directory as a trusted local project in a new Codex session, then send:

$harness Build a harness for this project. Use subagents in parallel for independent tasks.

Korean also works:

$harness 이 프로젝트에 맞는 하네스를 구성해줘. 독립 작업은 서브에이전트로 병렬 처리해줘.

Project agents and the harness skill are already in this checkout. If newly generated agents are absent from the current session, start a new thread in the project. See quickstart for installation into another project and a live smoke test.

Install into another project (optional)

Requires Python 3.11+; the scripts use only the standard library. Run from this checkout:

python3 scripts/install.py --target /absolute/path/to/project --dry-run
python3 scripts/install.py --target /absolute/path/to/project
python3 scripts/validate.py --project /absolute/path/to/project

The installer copies the canonical harness skill and five seed agents, and merges supported project configuration forms and the AGENTS.md pointer while preserving existing content. This predefined scaffold is optional; explicit skill invocation builds a project-specific harness without it. Review any reported conflicts. An inline agents = { ... } table that needs missing defaults may require expansion to [agents]; the installer reports this before writing files. It does not change personal Codex configuration. Open the target in a new trusted local Codex session after installation.

The Codex plugin manifest packages the skill from the standard skills/ directory. The repository marketplace makes it installable as codex-harness@codex-harness. Plugin installation alone does not create project files; explicit invocation builds the project-specific harness, while the project installer supplies the optional predefined scaffold.

How the team works

The parent assigns each task an objective, owned files, dependencies, and acceptance criteria. Workers share a workspace, preserve each other’s edits, and return evidence. Shared files have one owner; dependent tasks wait for their inputs. The parent closes or reuses completed agents and handles capacity limits without dropping work.

The project config enables native subagents and requests at most three concurrent subagent threads; the parent session coordinates them. Runtime limits may reduce available capacity. Models and reasoning effort inherit from the parent. Child agents do not recursively delegate by default. QA’s prohibition on product edits is an instruction boundary within its write-enabled sandbox. See multi-agent design for the full protocol and sandbox caveats.

Layout

AGENTS.md                         Project entry point
.codex/config.toml                Project subagent settings
.codex/agents/*.toml               Five native seed agents
skills/harness/                   Single physical skill source
  SKILL.md                        Canonical harness-building workflow
  references/                     Patterns, handoffs, examples, QA guidance
  scripts/create_agent.py         Create a project agent safely
  scripts/validate.py             Structural and run completion validation
  scripts/run.py                  Run state, refreshed context, agent lifecycle
  scripts/communication.py        Explicit collaboration event log
.agents/skills/harness             Symlink → ../../skills/harness
.codex-plugin/plugin.json         Plugin manifest; skills = "./skills/"
.agents/plugins/marketplace.json  Installable repository marketplace
scripts/install.py                Install into a target project
scripts/validate.py               Repository validation entry point
tests/                            Automated installer and validation checks
docs/                             Usage, architecture, migration, compatibility
.harness/runs//            Runtime plans, packets, results, agent registry
_workspace/communications/         Explicit message JSONL logs and optional exports

In this checkout, .agents/skills/harness links to skills/harness for project discovery, so the plugin and project use one source. The installer follows that alias and copies regular files into the target project’s .agents/skills/harness/; the installed project needs no symlink.

The six design patterns remain available: pipeline, fan-out/fan-in, expert pool, producer/reviewer, supervisor, and hierarchical decomposition. Hierarchical decomposition becomes a parent-managed dependency graph; it does not require recursive agent spawning.

Run state and agent communication

The shell examples below use paths created by explicit $harness invocation or the optional project installer. Before invocation, a plugin-only installation keeps those helpers in the installed skill directory.

The parent initializes a run from an actual project plan, records native agent IDs, and gives each child a refreshed packet with the project root, stable input fingerprints, decisions, skills, ownership, dependencies, and acceptance criteria. Related follow-ups can reuse the same agent; independent reviews can use fresh context when the runtime supports it. Models and the three-subagent concurrency setting stay inherited/configured as above.

python3 .agents/skills/harness/scripts/run.py --project . init \
  --plan-file /absolute/path/to/project-plan.json --run-id project-v1
python3 .agents/skills/harness/scripts/run.py --project . ready --run project-v1
python3 .agents/skills/harness/scripts/run.py --project . status --run project-v1

Workers proactively share findings, ask focused questions, answer peers, and announce dependency readiness and handoffs. The parent confirms contracts and ownership. Important messages are explicitly logged under _workspace/communications/.jsonl: record the outward event, use the actual native messaging tool, then record its delivery outcome and correlate replies. Read-only roles ask the parent to log and route their messages. Local logging does not send messages or automatically capture Codex internals.

python3 .agents/skills/harness/scripts/communication.py --project . --run project-v1 view \
  --format markdown --output _workspace/communications/project-v1.md
python3 .agents/skills/harness/scripts/validate.py --project . --run project-v1 --complete

Task completion is separate from native session idleness or termination. Before transferring write ownership, the parent confirms the previous agent has stopped or is idle. On resume, changed inputs/results and affected dependent tasks are invalidated. Use ordinary resume when only existing input file contents change. For changed decisions, ownership, acceptance criteria, objective, or added/removed tasks, supply a revised template without editing the old run ledger:

python3 .agents/skills/harness/scripts/run.py --project . resume \
  --run project-v1 --new-run project-v2 \
  --plan-file /absolute/path/to/revised-project-plan.json

Changed contracts and affected descendants become pending; unchanged accepted work can be reused. Product fixes belong to workers; QA verifies the corrected behavior. See the runtime guide for plan/result schemas, exact commands, and message correlation.

Verification

python3 scripts/validate.py --project .
python3 -m unittest discover -s tests -v

For an optional live test, run from this checkout with an authenticated Codex client. Choose a new target directory:

python3 scripts/live_smoke.py run --target _workspace/live-tests/NEW_ID

The script exercises two native custom workers, a blocked task and failed completion check, an input correction followed by resume and reuse of the unchanged result, then two QA assertions. It allows up to 1,200 seconds and is excluded from default CI. Inspect its actual transcript, files, and check results; the command itself is not a recorded pass.

97 automated tests passed. A repeated-resume correction preserves ancestor outputs; its verification summary and two unresolved cross-run limitations are recorded separately. A separate Codex CLI 0.153.4 run used two native custom workers and an independent QA agent to verify file creation, peer communication records, a blocked completion, partial resume, unchanged-result reuse, and passing final tests. See the verification record for evidence and limits, including the earlier read-only smoke and observed ephemeral-session issue. Other clients, sandbox enforcement, and performance were not benchmarked. Repeat the live regression above in your environment.

• Quickstart
• Multi-agent architecture and task packets
• Claude Code → Codex migration
• Codex compatibility
• Service migration starter example
• Contributing

License and attribution

Apache License 2.0. Original Harness by the contributors to revfactory/harness. This migration retains the upstream license; its Codex behavior and verification status are documented separately from upstream releases.