{"id":49915546,"url":"https://github.com/blackwell-systems/polywave-codex","last_synced_at":"2026-07-08T03:30:41.060Z","repository":{"id":357464620,"uuid":"1236213256","full_name":"blackwell-systems/polywave-codex","owner":"blackwell-systems","description":"Polywave implementation for OpenAI Codex CLI: parallel AI agents with disjoint file ownership and worktree isolation. Requires polywave-tools.","archived":false,"fork":false,"pushed_at":"2026-05-12T21:58:22.000Z","size":1570,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T23:28:12.283Z","etag":null,"topics":["agent-orchestration","agent-skills","agentic-coding","agentic-workflow","ai-agents","codex","codex-cli","coordination-protocol","git-worktree","llm-agents","llm-orchestration","multi-agent","openai","parallel-agents","polywave","workflow-automation"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blackwell-systems.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-12T03:40:25.000Z","updated_at":"2026-05-12T21:58:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/blackwell-systems/polywave-codex","commit_stats":null,"previous_names":["blackwell-systems/polywave-codex"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/blackwell-systems/polywave-codex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave-codex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave-codex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave-codex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave-codex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blackwell-systems","download_url":"https://codeload.github.com/blackwell-systems/polywave-codex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave-codex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35251015,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-orchestration","agent-skills","agentic-coding","agentic-workflow","ai-agents","codex","codex-cli","coordination-protocol","git-worktree","llm-agents","llm-orchestration","multi-agent","openai","parallel-agents","polywave","workflow-automation"],"created_at":"2026-05-16T16:01:48.745Z","updated_at":"2026-07-08T03:30:41.056Z","avatar_url":"https://github.com/blackwell-systems.png","language":null,"funding_links":["https://buymeacoffee.com/blackwellsystems"],"categories":["Skills"],"sub_categories":["Development \u0026 Code Tools"],"readme":"\u003ch1 align=\"center\"\u003ePolywave for Codex CLI\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/blackwell-systems/polywave-protocol/main/assets/logo.png\" alt=\"Polywave\" width=\"600\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/blackwell-systems\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/blackwell-systems/blackwell-docs-theme/main/badge-trademark.svg\" alt=\"Blackwell Systems\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://buymeacoffee.com/blackwellsystems\"\u003e\u003cimg src=\"https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg\" alt=\"Buy Me A Coffee\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003eParallel AI agents that don't break each other's code.\u003c/strong\u003e Now on \u003ca href=\"https://github.com/openai/codex\"\u003eCodex CLI\u003c/a\u003e.\u003c/p\u003e\n\n\u003e **Status:** Usable alpha. The current blessed flow is hybrid: run scout in-session with `$polywave scout`, then run wave execution from your shell with `scripts/run-polywave-wave`. The single-session `$polywave wave` experience is not yet viable in the tested Codex runtime. See [IMPLEMENTATION-NOTES.md](IMPLEMENTATION-NOTES.md) for the current runtime evidence.\n\n## What is this?\n\nThis repo provides the Codex CLI implementation of the [Polywave protocol](https://github.com/blackwell-systems/polywave-protocol): a Codex skill, custom agent definitions, and enforcement hooks that let Codex coordinate parallel agents with disjoint file ownership and worktree isolation.\n\n## Repositories\n\n| Repository | Purpose |\n|-----------|---------|\n| [polywave-protocol](https://github.com/blackwell-systems/polywave-protocol) | Protocol specification |\n| [polywave](https://github.com/blackwell-systems/polywave) | Claude Code implementation |\n| **polywave-codex** (this repo) | Codex CLI implementation |\n| [polywave-go](https://github.com/blackwell-systems/polywave-go) | Go engine and `polywave-tools` CLI |\n| [polywave-web](https://github.com/blackwell-systems/polywave-web) | Web UI (optional) |\n\n\u003e **Using Claude Code?** Start at [polywave](https://github.com/blackwell-systems/polywave).\n\n## Prerequisites\n\n- [Codex CLI](https://github.com/openai/codex) installed\n- Git 2.20+\n- jq 1.6+\n- `polywave-tools` CLI\n\nInstall `polywave-tools` with one of:\n\n```bash\nbrew install blackwell-systems/tap/polywave-tools\ngo install github.com/blackwell-systems/polywave-go/cmd/polywave-tools@latest\n```\n\n## Quick Start\n\nUse one terminal. The current blessed flow is sequential.\n\n1. Install Polywave Codex artifacts:\n\n```bash\n./install.sh\n```\n\n2. Merge the printed hook configuration into your Codex config, then restart Codex.\n\n3. Verify the install:\n\n```bash\n./scripts/verify-codex-install\n```\n\n4. Initialize your target project if needed:\n\n```bash\ncd your-project\npolywave-tools init\n```\n\n5. Run scout in Codex:\n\n```\n$polywave scout \"add a caching layer to the API client\"\n```\n\n6. Run the wave launcher from your shell:\n\n```bash\nscripts/run-polywave-wave docs/IMPL/IMPL-caching.yaml --wave 1 --repo-dir \"$PWD\"\n```\n\nA shorter version of the same flow lives in [QUICKSTART.md](QUICKSTART.md).\n\n## Installation Notes\n\nThe installer installs:\n- the hook package\n- the `polywave` skill\n- progressive-disclosure references and injector scripts\n- prompt builders for scout and wave execution\n- direct Codex ports of the current Polywave custom agents\n\n```bash\n./install.sh\n```\n\nUse `--write-user-hooks` only if `~/.codex/hooks.json` does not already exist and you want the installer to create it.\n\nImportant: `install.sh` does **not** finish the job by itself. You must:\n- merge the printed hook config into `~/.codex/config.toml` or `~/.codex/hooks.json`\n- restart Codex\n- run `./scripts/verify-codex-install`\n\nTo remove installed hook artifacts:\n\n```bash\n./uninstall.sh\n```\n\n## How to Use Polywave on Codex\n\n**Scout (blessed in-session path):** Start Codex and invoke the skill directly:\n\n```\n$polywave scout \"add a caching layer to the API client\"\n```\n\nThe orchestrator delegates to `polywave-scout`, which writes an IMPL manifest validated through `polywave-tools`.\n\n**Wave (blessed shell path):** After reviewing the IMPL, run the wave launcher:\n\n```bash\nscripts/run-polywave-wave docs/IMPL/IMPL-caching.yaml --wave 1 --repo-dir \"$PWD\"\n```\n\nThis 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.\n\n**Why the split?** Codex runtime behavior currently blocks the ideal single-session wave UX:\n- in-session spawned workers can fail on git worktree metadata writes\n- nested `codex exec` from inside an active session can fail before worker start\n\nThe shell launcher avoids both constraints by running each worker as its own top-level process.\n\n## Progressive Disclosure\n\n\u003e **Codex limitation:** Codex does not support Claude Code's automatic subagent prompt rewrite path (`updatedInput` on agent launch), so progressive disclosure references must be loaded explicitly by the `$polywave` orchestrator or the shell launchers.\n\nThe Codex port carries the same basic disclosure structure as the Claude implementation:\n- core orchestrator skill in `SKILL.md`\n- on-demand protocol references in `references/`\n- deterministic routing scripts in `scripts/inject-context` and `scripts/inject-agent-context`\n- deterministic prompt builders in `scripts/build-scout-prompt` and `scripts/build-wave-agent-prompt`\n\nThe exact in-session procedure is documented in `references/live-loop-playbook.md`.\n\n## Current Proven Paths\n\n- `$polywave scout` in-session: proven\n- `scripts/run-polywave-wave`: proven end to end\n- fully in-session `$polywave wave`: not yet a proven production path\n\n## Development\n\nRun the hook fixture suite with:\n\n```bash\nscripts/run-hook-fixtures\n```\n\nTo capture real Codex hook payloads, temporarily add the optional audit snippet printed by:\n\n```bash\nscripts/print-codex-config\n```\n\nPayloads are written under `${CODEX_HOME:-$HOME/.codex}/polywave/audit`.\n\n## License\n\n[MIT OR Apache-2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackwell-systems%2Fpolywave-codex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblackwell-systems%2Fpolywave-codex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackwell-systems%2Fpolywave-codex/lists"}