Installation Guide

Zero to First Scout

Five commands from nothing to your first /polywave scout. Copy-paste in order:

# 0. Prerequisites: Git 2.20+, jq 1.6+
git --version && jq --version

# 1. Install skill files, hooks, and Agent permission
git clone https://github.com/blackwell-systems/polywave.git
cd polywave && ./install.sh

# 2. Install the CLI (pick one)
brew install blackwell-systems/tap/polywave-tools            # Homebrew
go install github.com/blackwell-systems/polywave-go/cmd/polywave-tools@latest  # Go install

# Or download a pre-built binary (no Go/Homebrew required):
# https://github.com/blackwell-systems/polywave-go/releases/latest

# 3. Initialize your project
cd /path/to/your-project
polywave-tools init

# 4. Verify everything works
polywave-tools verify-install

# 5. Restart Claude Code, then run your first scout
/polywave scout "describe your feature here"

The installer auto-detects Claude Code and handles everything: skill files, enforcement hooks, settings.json registration, and Agent permission. No manual configuration needed.

For non-Claude-Code platforms, use ./install.sh --generic to install to ~/.agents/skills/polywave/ instead (see Platform Support below).

That's it for most users. The Web UI is optional -- see Step 3 below if you want the browser interface.

Prerequisites

What you need

Most users need two repos: this one (skill files, hooks, agent prompts) and polywave-tools (a single binary from polywave-go). The protocol spec lives in polywave-protocol but you don't need it to use Polywave. The web UI is optional.

Installation Steps

Install in this order. Each step builds on the previous one.

Step 1: Protocol, Skill Files, and Hooks

Clone this repository and run the installer:

git clone https://github.com/blackwell-systems/polywave.git
cd polywave
./install.sh

The installer auto-detects Claude Code (checks for ~/.claude) and does four things:

1. Symlinks skill files to ~/.claude/skills/polywave/ (SKILL.md, agent definitions, references, scripts).
2. Symlinks hook scripts to ~/.claude/agents/hooks/ (22 enforcement hooks, see Hooks below).
3. Registers hooks in ~/.claude/settings.json under PreToolUse, PostToolUse, SubagentStart, SubagentStop, and UserPromptSubmit lifecycle events.
4. Adds Agent permission to ~/.claude/settings.json so Polywave can launch agents without manual approval.

The installer is idempotent — safe to run multiple times. It backs up settings.json before modifying it. Run ./install.sh --generic to install to ~/.agents/skills/polywave/ without Claude Code-specific configuration.

Skill Files

After installation, the skill directory structure looks like this:

~/.claude/skills/polywave/
├── SKILL.md              -> prompts/polywave-skill.md
├── agent-template.md     -> prompts/agent-template.md
├── polywave-bootstrap.md -> prompts/polywave-bootstrap.md
├── agents/
│   ├── critic-agent.md   -> prompts/agents/critic-agent.md
│   ├── integration-agent.md -> prompts/agents/integration-agent.md
│   ├── planner.md        -> prompts/agents/planner.md
│   ├── scaffold-agent.md -> prompts/agents/scaffold-agent.md
│   ├── scout.md          -> prompts/agents/scout.md
│   └── wave-agent.md     -> prompts/agents/wave-agent.md
├── references/
│   ├── amend-flow.md     -> prompts/references/amend-flow.md
│   ├── failure-routing.md -> prompts/references/failure-routing.md
│   ├── impl-targeting.md -> prompts/references/impl-targeting.md
│   ├── integration-gap-detection.md -> prompts/references/integration-gap-detection.md
│   ├── model-selection.md -> prompts/references/model-selection.md
│   ├── pre-wave-validation.md -> prompts/references/pre-wave-validation.md
│   ├── program-flow.md   -> prompts/references/program-flow.md
│   ├── scout-program-contracts.md -> prompts/references/scout-program-contracts.md
│   ├── wave-agent-build-diagnosis.md -> prompts/references/wave-agent-build-diagnosis.md
│   ├── wave-agent-contracts.md -> prompts/references/wave-agent-contracts.md
│   └── wave-agent-program-contracts.md -> prompts/references/wave-agent-program-contracts.md
└── hooks/
    └── pre-commit-guard.sh

All symlink targets point into implementations/claude-code/prompts/ in the protocol repo, so pulling the latest revision updates skill behavior without re-symlinking.

Step 2: CLI Tools (polywave-tools)

Install the polywave-tools binary using one of these methods:

Homebrew (macOS/Linux):

brew install blackwell-systems/tap/polywave-tools

Go install (any platform with Go 1.21+):

go install github.com/blackwell-systems/polywave-go/cmd/polywave-tools@latest

git clone https://github.com/blackwell-systems/polywave-go.git
cd polywave-go
go build -o ~/.local/bin/polywave-tools ./cmd/polywave-tools

Verify the installation:

polywave-tools version

Step 2b: Initialize Your Project

After installing polywave-tools, run polywave-tools init in your project directory to auto-generate a polywave.config.json configuration file:

cd your-project
polywave-tools init

polywave-tools init auto-detects your project's language (Go, Rust, Node, Python, Ruby, or Makefile-based), build command, and test command, then writes a polywave.config.json with sensible defaults. No manual configuration needed for most projects.

Flags:

• --repo <path> — Initialize a project at a different path (default: current directory)
• --force — Overwrite an existing polywave.config.json

If you already have a polywave.config.json or prefer to configure manually, this step is optional — see Configuration below.

Step 3: Web UI (Optional)

If you want the browser-based interface:

git clone https://github.com/blackwell-systems/polywave-web.git
cd polywave-web
cd web && npm install && npm run build && cd ..
go build -o polywave-web ./cmd/polywave-web

The React frontend is embedded into the Go binary via //go:embed, so both the npm build and the Go build are required. Any change to the frontend requires re-running both steps.

Start the server with:

./polywave-web serve

Hooks

The installer registers 22 hooks across six lifecycle events. All hook scripts live in implementations/claude-code/hooks/ and are symlinked to ~/.claude/agents/hooks/.

SubagentStart (3 hooks — fire when an agent session starts)

PreToolUse (8 hooks — fire before tool execution)

PostToolUse (5 hooks — fire after tool execution)

SubagentStop (4 hooks — fire when an agent session ends)

Stop (1 hook — fires when Claude finishes responding)

UserPromptSubmit (1 hook — fires when user submits a prompt)

Hook-Based Enforcement (E43)

As of v0.65.0, worktree isolation is enforced automatically via lifecycle hooks. Wave agents no longer need manual cd commands or $WORKTREE variable usage — hooks inject working directory changes and validate paths before tool execution.

This prevents the Agent B leak scenario where files are accidentally created in the main repository instead of the agent's assigned worktree. Four hooks work together to provide defense-in-depth isolation:

1. Environment injection (SubagentStart)
2. Bash command rewriting (PreToolUse:Bash)
3. Write/Edit path validation (PreToolUse:Write/Edit)
4. Protocol compliance verification (SubagentStop)

See implementations/claude-code/hooks/README.md for full hook documentation.

For detailed hook documentation, see hooks/README.md.

Symlinks Created

The installer creates 22 symlinks in ~/.claude/agents/hooks/:

check_scout_boundaries           validate_agent_launch
validate_impl_on_write           validate_agent_completion
block_claire_paths               validate_agent_isolation
check_wave_ownership             validate_worktree_isolation
check_git_ownership              emit_agent_completion
warn_stubs                       inject_skill_context
check_branch_drift               inject_worktree_env
auto_format_polywave_agent_names inject_bash_cd
validate_write_paths             verify_worktree_compliance
block_git_stash                  auto_commit_on_write
polywave_orchestrator_stop       polywave_critic_impl_commit

Verify Installation

Run the installation verification command:

polywave-tools verify-install

This checks that all prerequisites are met: polywave-tools is on PATH, skill files are symlinked, Git version is sufficient, and configured repos exist on disk. Fix any reported issues before proceeding.

For human-readable output instead of JSON:

polywave-tools verify-install --human

Configuration: polywave.config.json

What it is

polywave.config.json is a per-project configuration file that lives in your project root. It tells Polywave how to build, test, and manage your project -- which repos are involved, which models to use for each agent role, and what quality gates to run.

What happens without it

Polywave works without polywave.config.json, but with reduced capabilities:

Bottom line: A single-repo project with default models works fine without it. Multi-repo projects or custom model selection need it.

Creating it

The recommended approach is auto-detection:

cd your-project
polywave-tools init

This scans for language markers (go.mod, Cargo.toml, package.json, pyproject.toml, Gemfile, Makefile) and generates a config with sensible defaults. Use --force to overwrite an existing file.

Full reference

{
  "repos": [
    {"name": "my-project", "path": "/absolute/path/to/my-project"},
    {"name": "my-shared-lib", "path": "/absolute/path/to/shared-lib"}
  ],
  "agent": {
    "scout_model": "claude-sonnet-4-6",
    "wave_model": "claude-sonnet-4-6",
    "scaffold_model": "",
    "integration_model": "",
    "planner_model": "",
    "critic_model": "",
    "chat_model": ""
  },
  "build": {
    "command": "go build ./...",
    "detected": true
  },
  "test": {
    "command": "go test ./...",
    "detected": true
  },
  "webhooks": {
    "enabled": false,
    "adapters": []
  }
}

Field reference

repos (array of {name, path}) -- Repositories this project spans. For single-repo projects, polywave-tools init creates one entry pointing to the current directory. For multi-repo projects, add additional entries. Cross-repo IMPL docs use repo: tags on file_ownership and quality_gates that must match a name here.

agent (object) -- Model override per agent role. Empty string or missing field means "inherit the parent session's model." The /polywave skill reads these at agent launch time. Available roles: scout_model, wave_model, scaffold_model, integration_model, planner_model, critic_model, chat_model.

build / test (object with command and detected) -- Build and test commands for the project. polywave-tools init auto-detects these and sets detected: true. Override command if auto-detection chose wrong. These are used by polywave-tools finalize-wave for post-merge verification.

webhooks (object) -- Webhook notification configuration. enabled: true activates delivery. adapters is an array of adapter configs (Slack, Discord, Telegram). Configure via the web UI Settings page or edit directly.

Config file lookup

Polywave checks two locations (first match wins):

1. <project-root>/polywave.config.json -- per-project config
2. ~/.claude/polywave.config.json -- global default for all projects

The project-local file takes full precedence. There is no merging between levels.

Troubleshooting

"polywave-tools: command not found"

Install or reinstall:

brew install blackwell-systems/tap/polywave-tools
# or
go install github.com/blackwell-systems/polywave-go/cmd/polywave-tools@latest

If installed via go install, ensure $GOPATH/bin (typically ~/go/bin) is on your PATH:

export PATH="$(go env GOPATH)/bin:$PATH"

Verify with: which polywave-tools

"/polywave not recognized"

The skill files are not installed. Verify the symlinks exist:

ls -la ~/.claude/skills/polywave/SKILL.md
ls ~/.claude/skills/polywave/agents/
ls ~/.claude/skills/polywave/references/

If any are missing, re-run the installer: ./install.sh

Hooks not firing

1. Check that symlinks exist and are executable:

   ls -la ~/.claude/agents/hooks/check_scout_boundaries
   ls -la ~/.claude/agents/hooks/validate_agent_launch
   

2. Check that hooks are registered in settings:

   jq '.hooks' ~/.claude/settings.json
   

3. Re-run the installer:

   ./install.sh
   

See hooks/README.md for detailed troubleshooting of individual hooks.

"Git worktree error" or worktree creation fails

Your Git version is too old. Polywave requires Git 2.20+ for worktree support.

Check with: git --version

Upgrade Git:

• macOS: brew install git
• Ubuntu/Debian: sudo apt-get install git

Build fails for polywave-go

Ensure you have Go 1.25+ installed:

go version

If you have an older version, update Go from go.dev/dl.

Web UI build fails (npm errors)

Ensure you have Node.js 18+:

node --version

If the React build fails, try clearing the cache:

cd polywave-web/web
rm -rf node_modules
npm install
npm run build

Then rebuild the Go binary (required because assets are embedded):

cd polywave-web
go build -o polywave-web ./cmd/polywave-web

Platform Support

The installer supports multiple platforms via flags:

polywave-tools works on any platform -- it's a standalone Go binary that manages git worktrees, validates IMPL docs, merges branches, and runs quality gates. No LLM API calls. Key capabilities include:

• Worktree management: prepare-wave, finalize-wave, create-worktree
• Validation: pre-wave-validate, verify-install, validate-impl, validate-briefs
• Configuration: init, set-completion, set-impl-state
• Scout automation: check-callers, list-error-ranges, suggest-wave-structure, and check-test-cascade replace manual grep during planning

The orchestrator prompt and hooks are platform-specific. The /polywave skill prompt is written for Claude Code's skill system. The hook scripts use a JSON stdin/stdout protocol that can be adapted to other platforms' hook systems (Gemini CLI's BeforeAgent, Cursor's beforeSubmitPrompt, etc.). Use --generic to install the scripts, then register them in your platform's configuration.

Uninstalling

./install.sh --uninstall

This removes skill file symlinks and hook script symlinks. Hook registrations in settings.json are not removed automatically -- edit that file manually if needed.

Next Steps

• Getting Started -- decide which interface to use
• First Run Walkthrough -- step-by-step example
• Protocol Specification -- deep dive into how Polywave works
• Hook System -- detailed documentation for all enforcement hooks

Last reviewed: 2026-04-03