Parallel AI agents that don't break each other's code. Now on Codex CLI.
Status: Usable alpha. The current blessed flow is hybrid: run scout in-session with
$polywave scout, then run wave execution from your shell withscripts/run-polywave-wave. The single-session$polywave waveexperience is not yet viable in the tested Codex runtime. See IMPLEMENTATION-NOTES.md for the current runtime evidence.
This repo provides the Codex CLI implementation of the Polywave protocol: a Codex skill, custom agent definitions, and enforcement hooks that let Codex coordinate parallel agents with disjoint file ownership and worktree isolation.
| Repository | Purpose |
|---|---|
| polywave-protocol | Protocol specification |
| polywave | Claude Code implementation |
| polywave-codex (this repo) | Codex CLI implementation |
| polywave-go | Go engine and polywave-tools CLI |
| polywave-web | Web UI (optional) |
Using Claude Code? Start at polywave.
- Codex CLI installed
- Git 2.20+
- jq 1.6+
polywave-toolsCLI
Install polywave-tools with one of:
brew install blackwell-systems/tap/polywave-tools
go install github.com/blackwell-systems/polywave-go/cmd/polywave-tools@latestUse one terminal. The current blessed flow is sequential.
- Install Polywave Codex artifacts:
./install.sh-
Merge the printed hook configuration into your Codex config, then restart Codex.
-
Verify the install:
./scripts/verify-codex-install- Initialize your target project if needed:
cd your-project
polywave-tools init- Run scout in Codex:
$polywave scout "add a caching layer to the API client"
- Run the wave launcher from your shell:
scripts/run-polywave-wave docs/IMPL/IMPL-caching.yaml --wave 1 --repo-dir "$PWD"A shorter version of the same flow lives in QUICKSTART.md.
The installer installs:
- the hook package
- the
polywaveskill - progressive-disclosure references and injector scripts
- prompt builders for scout and wave execution
- direct Codex ports of the current Polywave custom agents
./install.shUse --write-user-hooks only if ~/.codex/hooks.json does not already exist and you want the installer to create it.
Important: install.sh does not finish the job by itself. You must:
- merge the printed hook config into
~/.codex/config.tomlor~/.codex/hooks.json - restart Codex
- run
./scripts/verify-codex-install
To remove installed hook artifacts:
./uninstall.shScout (blessed in-session path): Start Codex and invoke the skill directly:
$polywave scout "add a caching layer to the API client"
The orchestrator delegates to polywave-scout, which writes an IMPL manifest validated through polywave-tools.
Wave (blessed shell path): After reviewing the IMPL, run the wave launcher:
scripts/run-polywave-wave docs/IMPL/IMPL-caching.yaml --wave 1 --repo-dir "$PWD"This prepares worktrees, launches each agent as a parallel codex exec process, and finalizes (merge + verify + cleanup). Disjoint file ownership is enforced through polywave-tools, and worktree isolation comes from per-process sandbox scoping.
Why the split? Codex runtime behavior currently blocks the ideal single-session wave UX:
- in-session spawned workers can fail on git worktree metadata writes
- nested
codex execfrom inside an active session can fail before worker start
The shell launcher avoids both constraints by running each worker as its own top-level process.
Codex limitation: Codex does not support Claude Code's automatic subagent prompt rewrite path (
updatedInputon agent launch), so progressive disclosure references must be loaded explicitly by the$polywaveorchestrator or the shell launchers.
The Codex port carries the same basic disclosure structure as the Claude implementation:
- core orchestrator skill in
SKILL.md - on-demand protocol references in
references/ - deterministic routing scripts in
scripts/inject-contextandscripts/inject-agent-context - deterministic prompt builders in
scripts/build-scout-promptandscripts/build-wave-agent-prompt
The exact in-session procedure is documented in references/live-loop-playbook.md.
$polywave scoutin-session: provenscripts/run-polywave-wave: proven end to end- fully in-session
$polywave wave: not yet a proven production path
Run the hook fixture suite with:
scripts/run-hook-fixturesTo capture real Codex hook payloads, temporarily add the optional audit snippet printed by:
scripts/print-codex-configPayloads are written under ${CODEX_HOME:-$HOME/.codex}/polywave/audit.