| verified | true |
| lastVerifiedAt | "2026-02-22T00:00:00.000Z" |
| name | wave-executor |
| description | Fresh-process orchestration for EPIC-tier batch pipelines. Spawns a new Bun process per wave via the Claude Agent SDK, preventing GC-related crashes in long-running sessions. |
| version | 1.0.0 |
| model | sonnet |
| invoked_by | both |
| user_invocable | true |
| tools | ["Read","Write","Bash","Glob","Grep"] |
| aliases | ["batch-executor","ralph-loop"] |
| agents | ["router","master-orchestrator","planner"] |
| category | Planning & Architecture |
| tags | ["wave","orchestration","batch","pipeline","epic"] |
| best_practices | ["Use for EPIC-tier batch work (>10 artifacts, >5 waves)","Always provide a plan file with wave definitions","Prefer append-only writes to prevent regression","Monitor inventory file for progress between waves"] |
| error_handling | strict |
| streaming | supported |
| source | builtin |
| trust_score | 100 |
| provenance_sha | e54358fefd08d215 |
Wave Executor
Overview
Wave Executor runs EPIC-tier batch pipelines by spawning a fresh Claude Code process per wave via the Claude Agent SDK. Each wave gets a clean Bun runtime with zero accumulated spawn() or abort_signal state, preventing the JSC garbage collector use-after-free crash (oven-sh/bun, anthropics/claude-code#21875, #27003) that occurs when a single Bun process handles thousands of concurrent subagent spawns.
This is the framework's implementation of the Ralph Wiggum pattern: iteration over fresh processes with file-based coordination.
When to Use
Use this skill when:
- EPIC-tier batch work: >10 artifacts, >5 waves
- Multi-wave skill updates, bundle generation, or mass refactoring
- Any pipeline expected to run >30 minutes with parallel subagents
- Work that previously crashed due to Bun segfaults
Do NOT use for:
- Simple 1-3 skill updates (use
skill-updater directly)
- Single-skill work (use
Task() subagent)
- Work that fits in one context window (just do it inline)
How It Works
Router invokes wave-executor via Bash
│
└─ node .claude/tools/cli/wave-executor.mjs --plan <path>
│ (runs on system Node.js — NOT Bun)
│
├─ Reads plan.json with wave definitions
├─ Reads inventory.json for resume state
│
├─ For each pending wave:
│ ├─ SDK query() → NEW Bun process (fresh GC)
│ ├─ Claude executes wave tasks
│ ├─ Streams output to stdout
│ ├─ Bun process exits → memory freed
│ ├─ Updates inventory.json
│ └─ Sleeps → next wave
│
└─ Returns JSON summary
Key invariant: no single Bun process accumulates more than ~100 spawns.
Invocation
Via Bash (agents):
node .claude/tools/cli/wave-executor.mjs --plan <path> --json
Via slash command (users):
/wave-executor --plan .claude/context/plans/my-plan.json
CLI flags:
| Flag | Default | Description |
|---|
--plan <path> | required | Path to wave plan JSON |
--model <model> |
