{"id":51508568,"url":"https://github.com/blackwell-systems/polywave-web","last_synced_at":"2026-07-08T03:30:42.866Z","repository":{"id":342731940,"uuid":"1174917653","full_name":"blackwell-systems/polywave-web","owner":"blackwell-systems","description":"Polywave web application: real-time dashboard, React UI, and Go API server for parallel agent coordination","archived":false,"fork":false,"pushed_at":"2026-05-11T22:59:58.000Z","size":15361,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T00:30:01.840Z","etag":null,"topics":["agent-coordination","ai-agents","anthropic","automation","claude","cli","developer-tools","git","go","golang","llm","orchestration","parallel-agents","worktree"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/blackwell-systems/scout-and-wave-go","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blackwell-systems.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","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-03-07T01:42:25.000Z","updated_at":"2026-05-11T22:57:40.000Z","dependencies_parsed_at":"2026-03-07T11:10:40.405Z","dependency_job_id":null,"html_url":"https://github.com/blackwell-systems/polywave-web","commit_stats":null,"previous_names":["blackwell-systems/scout-and-wave-go","blackwell-systems/scout-and-wave-web","blackwell-systems/polywave-web"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/blackwell-systems/polywave-web","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave-web","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave-web/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave-web/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave-web/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blackwell-systems","download_url":"https://codeload.github.com/blackwell-systems/polywave-web/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fpolywave-web/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-coordination","ai-agents","anthropic","automation","claude","cli","developer-tools","git","go","golang","llm","orchestration","parallel-agents","worktree"],"created_at":"2026-07-08T03:30:42.800Z","updated_at":"2026-07-08T03:30:42.860Z","avatar_url":"https://github.com/blackwell-systems.png","language":"TypeScript","funding_links":["https://buymeacoffee.com/blackwellsystems"],"categories":[],"sub_categories":[],"readme":"# Polywave Web\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"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://github.com/blackwell-systems/polywave-web/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/blackwell-systems/polywave-web/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/version-0.20.3-blue\" alt=\"Version\" /\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**Web UI for [Polywave](https://github.com/blackwell-systems/polywave)** — review IMPL docs, monitor live wave execution, and chat with Claude about your implementation plans.\n\n\u003e **Using Claude Code?** Start at [polywave](https://github.com/blackwell-systems/polywave) for the Agent Skill and install guide. This repo provides the web dashboard as an alternative interface.\n\n## What is this?\n\nPolywave coordinates multiple AI agents working in parallel on non-overlapping parts of a codebase. This repo provides the **`polywave-web` binary** — the user-facing web UI + orchestration tool.\n\n**Features:**\n- **Interactive web UI** for reviewing IMPL docs (implementation plans) with visual dependency graphs, wave timelines, and file ownership tables\n- **Live wave dashboard** with real-time agent status, streaming logs, and progress tracking\n- **Chat interface** to ask Claude questions about IMPL docs with full conversation context\n- **HTTP API** (42 endpoints) for programmatic access to Polywave operations\n- **CLI interface** (`./polywave-web`) as an alternative to the web UI\n\nThe web server imports the [polywave-go](https://github.com/blackwell-systems/polywave-go) engine package for all Polywave orchestration logic. The protocol specification lives in [polywave-protocol](https://github.com/blackwell-systems/polywave-protocol).\n\n**Note:** There's also a separate `polywave-tools` CLI in polywave-go for protocol-level operations (CI/CD, power users). See [polywave-go/docs/reference/binaries.md](https://github.com/blackwell-systems/polywave-go/blob/main/docs/reference/binaries.md) for when to use which binary.\n\n## Quickstart\n\n```bash\n# Clone and build\ngit clone https://github.com/blackwell-systems/polywave-web.git\ncd polywave-web\nmake build\n\n# Start the web server\n./polywave-web serve\n# Opens http://localhost:7432 in your browser\n```\n\nThe web UI provides:\n\n1. **IMPL Picker** — browse all IMPL docs in `docs/IMPL/`\n2. **Review Screen** — suitability verdict, wave structure, dependency graph, file ownership, interface contracts, agent prompts\n3. **Wave Dashboard** — live agent execution with per-agent status cards, streaming output, and error reporting\n4. **Chat Panel** — ask Claude about the IMPL doc; conversations persist per-IMPL across sessions\n\n## Prerequisites\n\n- **Go 1.25+** — required by `go.mod`\n- **Node.js 18+** — required for web UI build\n- **git** — Polywave creates/merges git worktrees during wave execution\n- **`claude` CLI** *(optional)* — required only if using `--backend cli` (Claude Max plan, no API key); install from [claude.ai/code](https://claude.ai/code)\n- **`ANTHROPIC_API_KEY`** *(optional)* — required only if using `--backend api`; default is `auto` (uses whichever is available)\n\n## Installation\n\n### From source\n\n```bash\ngit clone https://github.com/blackwell-systems/polywave-web.git\ncd polywave-web\nmake build\n./polywave-web --version\n```\n\nThe `make build` target builds the React frontend (`web/`) and embeds it into the Go binary via `go:embed`. You can then copy `./polywave-web` anywhere on your `$PATH`.\n\n### Docker (planned)\n\nDocker support is planned but not yet available.\n\n## Usage\n\n### Web UI (primary interface)\n\n```bash\n# Start server and open browser\n./polywave-web serve\n\n# Custom port and repo path\n./polywave-web serve --addr :8080 --repo /path/to/your/project\n\n# Don't auto-open browser\n./polywave-web serve --no-browser\n```\n\nThe web UI provides three main views:\n\n#### 1. IMPL Picker (home)\n- Grid of all IMPL docs in `docs/IMPL/`\n- Shows status badge (pending/suitable/not-suitable), wave count, agent count\n- Click any card to open the review screen\n\n#### 2. Review Screen\n- **Overview**: Suitability verdict, estimated complexity, wave count\n- **Wave Structure**: Visual timeline showing which agents run in parallel\n- **Dependency Graph**: Interactive SVG showing agent dependencies\n- **File Ownership**: Table showing which agent owns which files (I1 enforcement)\n- **Interface Contracts**: Shared type scaffolds created before wave execution (I2 enforcement)\n- **Agent Prompts**: Full 9-field prompt each agent will receive\n- **Action buttons**: Approve, Request Changes, Reject (workflow tracking)\n- **Chat panel**: Ask Claude questions about the IMPL doc (resizable, history persists per-IMPL)\n\n#### 3. Wave Dashboard\n- Live view of wave execution progress\n- Per-wave status cards with agent breakdown\n- Streaming output from each agent as they work\n- Error reporting and retry status\n- Auto-refreshes via Server-Sent Events (SSE)\n\n### CLI (alternative interface)\n\nThe binary also provides a CLI for scripting and CI/CD:\n\n```bash\n# Analyze codebase and generate IMPL doc\n./polywave-web scout --feature \"add caching layer\"\n\n# Create scaffold files from IMPL doc\n./polywave-web scaffold --impl docs/IMPL/IMPL-caching.yaml\n\n# Execute all waves automatically\n./polywave-web wave --impl docs/IMPL/IMPL-caching.yaml --auto\n\n# Check status\n./polywave-web status --impl docs/IMPL/IMPL-caching.yaml\n./polywave-web status --impl docs/IMPL/IMPL-caching.yaml --json\n\n# Manual merge (recovery)\n./polywave-web merge --impl docs/IMPL/IMPL-caching.yaml --wave 1\n```\n\nSee [CLI Reference](docs/reference/cli-reference.md) for full command reference.\n\n## Web UI Features\n\n### Chat with Claude about IMPL docs\n\nClick \"Ask Claude about this IMPL\" in any review screen to open the chat panel. Features:\n\n- **Full conversation context**: Each message includes all previous turns (like the Claude Code CLI)\n- **Per-IMPL history**: Switch between IMPLs and return — conversations persist in memory\n- **Markdown rendering**: Code blocks with syntax highlighting, proper paragraph spacing\n- **Resizable panel**: Drag the divider to adjust chat width\n- **Explanatory mode**: When using the CLI backend (no API key), Claude provides educational insights about Polywave patterns\n\nExample conversation:\n\n```\nYou: What's the purpose of Agent B in Wave 2?\nClaude: Agent B implements the cache invalidation layer...\n\n★ Insight ─────────────────────────────────────\n• Interface separation: Agent B depends on the CacheClient\n  interface from Wave 1, not the concrete implementation\n• Wave sequencing (I3): Agent B couldn't run until Wave 1\n  committed the interface contract\n─────────────────────────────────────────────────\n\nYou: Why can't Agent B run in Wave 1?\nClaude: Agent B depends on the RateLimiter type that Agent A creates...\n```\n\n### Dark mode and themes\n\nClick the theme icon in the top-right to cycle through:\n\n- **Light** (default)\n- **Dark** (standard dark mode)\n- **Gruvbox Dark**\n- **Darcula** (JetBrains IDE theme)\n- **Catppuccin Mocha**\n- **Nord**\n\nTheme choice persists to `localStorage`.\n\n### Dependency graph visualization\n\nThe dependency graph panel renders an interactive SVG:\n\n- Nodes represent agents (color-coded by wave)\n- Edges show dependencies (data flow from Wave N → Wave N+1)\n- Hover to highlight connected nodes\n- Auto-layout using hierarchical algorithm\n\n### Live wave execution\n\nWhen running `./polywave-web wave --auto` (or via API), the Wave Dashboard streams live updates:\n\n- Per-wave progress bars\n- Per-agent status cards (pending → running → complete/failed)\n- Streaming stdout/stderr from each agent\n- Error messages and retry attempts\n- Merge status and post-merge verification results\n\nAll updates arrive over SSE (`/api/wave/{slug}/events`), so no polling required.\n\n## Architecture\n\n```\npolywave-web/\n├── cmd/polywave-web/     # CLI entry point (wraps pkg/api + pkg/engine calls)\n├── pkg/\n│   ├── api/             # HTTP server, SSE broker, REST endpoints\n│   │   ├── server.go    # Main server with embedded web bundle\n│   │   ├── chat_handler.go    # Chat SSE endpoint\n│   │   └── wave_handler.go    # Wave execution SSE endpoint\n│   └── protocol/        # IMPL doc parser (wraps polywave-go/pkg/protocol)\n├── web/                 # React + TypeScript + Tailwind\n│   ├── src/\n│   │   ├── components/  # UI components (ReviewScreen, WaveBoard, ChatPanel)\n│   │   ├── hooks/       # useChatWithClaude, useWaveEvents (SSE)\n│   │   └── api.ts       # HTTP client (fetch wrappers)\n│   └── dist/            # Built bundle (go:embed'ed into binary)\n└── docs/IMPL/           # IMPL docs generated by `polywave-web scout` or `/polywave scout`\n```\n\n**Dependency chain**:\n- `polywave-web` (this repo) -\u003e imports `polywave-go` (engine) -\u003e references `polywave-protocol` (spec)\n\nThe engine repo (`polywave-go`) provides:\n- `pkg/engine` — RunScout, RunChat, StartWave, MergeWave\n- `pkg/agent` — Agent runner with tool-use loop\n- `pkg/agent/backend` — Anthropic API client + Claude CLI shim\n- `pkg/orchestrator` — 10-state machine\n- `pkg/protocol` — IMPL doc parser\n\nThis repo (`polywave-web`) provides:\n- Web UI (React)\n- HTTP server with SSE streaming\n- REST API for IMPL operations\n- Chat endpoint with conversation context\n\n## Development\n\n### Prerequisites\n\n```bash\ngo version  # 1.25+\nnode --version  # 18+\n```\n\n### Build the web UI\n\n```bash\ncd web\nnpm install\nnpm run build  # outputs to web/dist/\n```\n\n### Build the Go binary\n\n```bash\ngo build -o polywave-web ./cmd/polywave-web\n```\n\nOr use the Makefile:\n\n```bash\nmake build      # builds web + go\nmake dev        # builds and starts server with hot-reload\nmake test       # runs go tests\n```\n\n### Development workflow\n\n**Frontend changes**:\n```bash\ncd web\nnpm run dev  # Vite dev server on port 5173 with hot-reload\n```\n\nThe Vite dev server proxies API requests to `http://localhost:7432` (configure in `vite.config.ts`). Run `./polywave-web serve` in another terminal to provide the backend.\n\n**Backend changes**:\n```bash\n# Edit Go files\ngo build -o polywave-web ./cmd/polywave-web\npkill -f \"polywave-web serve\"\n./polywave-web serve \u0026\u003e/tmp/polywave-serve.log \u0026\n```\n\nOr use the restart helper:\n```bash\nmake restart  # kills server, rebuilds, restarts\n```\n\n**Full rebuild** (after frontend changes):\n```bash\ncd web \u0026\u0026 npm run build \u0026\u0026 cd .. \u0026\u0026 go build -o polywave-web ./cmd/polywave-web\n```\n\nThe binary embeds `web/dist/` via `go:embed`, so you must rebuild the Go binary after every npm build for changes to appear.\n\n### Logs\n\n- **Server logs**: `/tmp/polywave-serve.log` (configure with `--log-file`)\n- **Chat sessions**: Logged with `[chat]` prefix (includes runID, slug, historyLen)\n- **Wave execution**: Logged with `[wave]` prefix (includes waveNum, agent letters)\n\nExample log output:\n```\n2026/03/08 21:38:43 [chat] Starting chat session: slug=demo-complex runID=1773031123005120000 message=\"explain Agent B\" historyLen=2\n2026/03/08 21:38:43 [chat] Launching RunChat: runID=1773031123005120000 implPath=/path/to/IMPL-demo-complex.md repoPath=/workspace historyLen=2\n2026/03/08 21:39:14 [chat] Streaming chunk #1: runID=1773031123005120000 len=40\n2026/03/08 21:39:14 [chat] Agent completed successfully: runID=1773031123005120000 totalChunks=12\n```\n\n## Documentation\n\n- **[CLI Reference](docs/reference/cli-reference.md)** — Complete command-line interface documentation for all 18 commands\n- **[API Reference](docs/reference/api-reference.md)** — HTTP endpoint documentation for all 42 REST/SSE endpoints\n- **[Configuration Reference](docs/reference/configuration.md)** — `polywave.config.json` structure and settings\n\n### Quick CLI Examples\n\n```bash\n# Generate IMPL doc\n./polywave-web scout --feature \"add OAuth support\"\n\n# Create interface scaffolds\n./polywave-web scaffold --impl docs/IMPL/IMPL-oauth.yaml\n\n# Execute waves\n./polywave-web wave --impl docs/IMPL/IMPL-oauth.yaml --auto\n\n# Check status\n./polywave-web status --impl docs/IMPL/IMPL-oauth.yaml\n\n# Start web server\n./polywave-web serve\n```\n\n### Quick API Examples\n\n```bash\n# List all IMPL docs\ncurl http://localhost:7432/api/impl\n\n# Get IMPL details\ncurl http://localhost:7432/api/impl/oauth\n\n# Start wave execution\ncurl -X POST http://localhost:7432/api/wave/oauth/start \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"wave_num\": 1, \"auto\": true}'\n\n# Stream wave events (SSE)\ncurl -N http://localhost:7432/api/wave/oauth/events\n```\n\n## Protocol Compliance\n\nImplements [Polywave Protocol](https://github.com/blackwell-systems/polywave-protocol):\n\n| Invariant | Enforcement |\n|-----------|-------------|\n| **I1** | Disjoint file ownership — file ownership table parsed pre-merge; any overlap fails validation |\n| **I2** | Interface contracts precede execution — scaffold files committed before worktree creation |\n| **I3** | Wave sequencing — Wave N+1 blocked until Wave N merged + post-merge verification passes |\n| **I4** | IMPL doc is single source of truth — all status, completion reports, and decisions written to IMPL doc |\n| **I5** | Agents commit before reporting — merge procedure checks for commits; missing commits trigger BLOCKED |\n| **I6** | Role separation — orchestrator delegates to Scout/Wave agents via `engine.RunScout`/`engine.StartWave` |\n\n**10-state machine**:\n\n```\nScoutPending → Reviewed → ScaffoldPending → WavePending → WaveExecuting\n                                                 ↑              ↓\n                                            WaveVerified ← WaveMerging\n                                                 ↓\n                                             Complete\n```\n\nTerminal states: `NotSuitable`, `Complete`. Recovery state: `Blocked`.\n\nSee [state-machine.md](https://github.com/blackwell-systems/polywave-protocol/blob/main/state-machine.md) for transition logic.\n\n## Troubleshooting\n\n### \"IMPL doc validation failed\"\n\n```bash\n# Run the validator manually\npolywave-tools validate docs/IMPL/IMPL-feature.yaml\n```\n\nCommon issues:\n- Missing required typed blocks (`impl-wave-structure`, `impl-file-ownership`, `impl-dep-graph`)\n- Wave headers without agent sections\n- Malformed file ownership table (missing columns)\n\n### \"Agent stuck on pending\"\n\nCheck logs:\n```bash\ntail -f /tmp/polywave-serve.log | grep \"\\[wave\\]\"\n```\n\nCommon causes:\n- Claude CLI not in `$PATH` (if using `--backend cli`)\n- `ANTHROPIC_API_KEY` not set (if using `--backend api`)\n- Worktree creation failed (check git status)\n\n### \"Chat stuck on thinking...\"\n\n1. Check if Claude process launched:\n```bash\npgrep -f \"claude.*chat\"\n```\n\n2. Check logs for errors:\n```bash\ntail -20 /tmp/polywave-serve.log | grep \"\\[chat\\]\"\n```\n\n3. Restart server:\n```bash\npkill -f \"polywave-web serve\"\n./polywave-web serve \u0026\u003e/tmp/polywave-serve.log \u0026\n```\n\n### \"Merge conflict detected\"\n\nThis means I1 was violated (overlapping file ownership). Check the file ownership table in the IMPL doc:\n\n```bash\n./polywave-web status --impl docs/IMPL/IMPL-feature.yaml --missing\n```\n\nIf two agents claim the same file, edit the IMPL doc to reassign ownership, then re-run the wave.\n\n## License\n\n[MIT OR Apache-2.0](LICENSE)\n\n## Contributing\n\nIssues and PRs welcome.\n\n## Links\n\n- **Protocol spec**: [polywave-protocol](https://github.com/blackwell-systems/polywave-protocol)\n- **Claude Code skill**: [polywave](https://github.com/blackwell-systems/polywave)\n- **Go engine**: [polywave-go](https://github.com/blackwell-systems/polywave-go)\n- **Buy me a coffee**: [buymeacoffee.com/blackwellsystems](https://buymeacoffee.com/blackwellsystems)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackwell-systems%2Fpolywave-web","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblackwell-systems%2Fpolywave-web","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackwell-systems%2Fpolywave-web/lists"}