The Problem

Claude Code is remarkably capable...until your context window fills up. As tokens accumulate during a long session, reasoning quality degrades, hallucinations increase, and the model starts losing track of earlier decisions. This is context rot, and it's the primary failure mode when building anything beyond a single-session project.

Plan-Build-Run solves this. It keeps your main orchestrator under ~15% context usage by delegating heavy work to fresh subagent contexts, each getting a clean 200k token window. All state lives on disk. Sessions are killable at any second without data loss. Whether you're on a free tier or Max 5x, wasted context means wasted budget, and context rot is the biggest source of waste.

Why Plan-Build-Run?

Most AI coding tools treat context as infinite. They index your codebase, track your edits, and hope the model keeps up. That works for single-file changes. It falls apart when you're building something that takes days, spans dozens of files, and requires decisions made on Monday to still hold on Friday.

Plan-Build-Run takes a different approach: structured context isolation. Instead of stuffing everything into one session, it delegates each operation to a fresh subagent with a clean 200k token window and coordinates through files on disk.

Goal-backward verification, lifecycle hooks, wave-based parallelism, kill-safe state, and local LLM offloading to cut frontier token costs on routine tasks. See What Sets It Apart for the full comparison and differentiators.

When to use Plan-Build-Run: Multi-phase projects where quality matters. New features spanning 5+ files, large refactors, greenfield builds, anything that would take more than one Claude Code session to complete. Use depth: quick or depth: standard to control agent spawn count per phase.

When to skip it: Single-file fixes, quick questions, one-off scripts. Use /pbr:quick for atomic commits without full workflow overhead: single executor spawn, no research or verification agents.

Works on every Claude Code plan. Use depth: quick on Free/Pro, depth: standard on Max, depth: comprehensive on Max 5x. See What Sets It Apart for tier-specific guidance.

Getting Started

Prerequisites

• Claude Code 2.1.47+  (claude --version)
• Node.js 18+

Install

# From your terminal
claude plugin marketplace add SienkLogic/plan-build-run
claude plugin install pbr@plan-build-run

# Or from inside a Claude Code session
/plugin marketplace add SienkLogic/plan-build-run
/plugin install pbr@plan-build-run

All /pbr:* commands are now available globally.

| Scope | Command | Effect | |-------|---------|--------| | Global (default) | claude plugin install pbr@plan-build-run | Available in all projects | | Project only | claude plugin install pbr@plan-build-run --scope local | This project only, gitignored | | Team project | claude plugin install pbr@plan-build-run --scope project | Shared via git, teammates get prompted |

Plan-Build-Run also works in Cursor. The setup script symlinks rules and agents into your project's .cursor/ directory.

macOS / Linux:

cd /path/to/your/project
bash /path/to/plan-build-run/plugins/cursor-pbr/setup.sh

Windows (PowerShell):

cd C:\path\to\your\project
powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\cursor-pbr\setup.ps1

Both plugins share the same .planning/ directory — start a project in Claude Code, continue in Cursor, or vice versa. See plugins/cursor-pbr/README.md for full details.

Plan-Build-Run also works in GitHub Copilot CLI. The setup script installs PBR as a Copilot CLI plugin and symlinks agents into your project.

macOS / Linux:

cd /path/to/your/project
bash /path/to/plan-build-run/plugins/copilot-pbr/setup.sh

Windows (PowerShell):

cd C:\path\to\your\project
powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\copilot-pbr\setup.ps1

All three plugins share the same .planning/ directory — start in any tool, continue in another. See plugins/copilot-pbr/README.md for full details.

Plan-Build-Run also works in OpenAI Codex CLI. Skills and agents are available via the plugins/codex-pbr/ plugin. No hooks (Codex CLI does not support lifecycle hooks).

macOS / Linux:

cd /path/to/your/project
bash /path/to/plan-build-run/plugins/codex-pbr/setup.sh

Windows (PowerShell):

cd C:\path\to\your\project
powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\codex-pbr\setup.ps1

All five plugins share the same .planning/ directory. See plugins/codex-pbr/README.md for full details.

Plan-Build-Run also works in Google Jules. Skills and agents are available via the plugins/jules-pbr/ plugin. No hooks (Jules does not support lifecycle hooks).

macOS / Linux:

cd /path/to/your/project
bash /path/to/plan-build-run/plugins/jules-pbr/setup.sh

Windows (PowerShell):

cd C:\path\to\your\project
powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\jules-pbr\setup.ps1

All five plugins share the same .planning/ directory. See plugins/jules-pbr/README.md for full details.

Plan-Build-Run ships with a companion web dashboard for browsing your project's planning state in a browser.

# One-time install of dashboard dependencies
npm run dashboard:install

# Launch the dashboard (defaults to current directory)
npm run dashboard

# Or specify a project directory and port
npm run dashboard -- --dir /path/to/your/project --port 3000

Or launch it directly from a Claude Code, Cursor, or Copilot CLI session:

/pbr:dashboard

Opens at http://127.0.0.1:3000 with live updates via SSE.

Quick Start (Max / Max 5x)

Full pipeline with parallel research and multi-agent builds. Best experience.

cd your-project && claude

/pbr:begin                # Plan-Build-Run asks about your project, researches the domain,
                          # scopes requirements, and generates a phased roadmap

/pbr:plan 1               # Research + plan the first phase
/pbr:build 1              # Build it with parallel agents, atomic commits
/pbr:review 1             # Verify the codebase matches requirements
/pbr:plan 2               # Repeat for next phase

That's the whole cycle. Everything lands in a .planning/ directory. Kill your terminal anytime, /pbr:resume picks up where you left off.

Quick Start (Pro / Free)

Lighter workflow that still gives you structured state tracking and clean commits.

cd your-project && claude

/pbr:setup                # Create .planning/ structure without the heavy research step
/pbr:plan 1 --skip-research   # Plan without spawning a research agent
/pbr:build 1              # Build it
/pbr:quick                # For one-off tasks: single agent, atomic commit, lowest cost

Set depth: quick in /pbr:config to reduce agent spawns across all workflows.

Quick Reference

| What you want | Command | |---------------|---------| | Start a new project | /pbr:begin (or /pbr:setup for lightweight init) | | Plan a phase | /pbr:plan 1 | | Build a phase | /pbr:build 1 | | Verify a phase | /pbr:review 1 | | Do something quick | /pbr:quick | | See where you are | /pbr:status | | Resume after restart | /pbr:resume | | Auto-advance | /pbr:continue | | Change settings | /pbr:config |

Commands

Core Workflow

| Command | Description | Agents | |---------|-------------|--------| | /pbr:begin | Start a new project: questioning, research, requirements, roadmap | 4-6 (quick: 2-3) | | /pbr:plan <N> | Plan a phase: research, plan creation, verification loop | 2-3 (quick: 1-2) | | /pbr:build <N> | Build a phase: parallel execution in waves, atomic commits | 2-4 (quick: 1-2) | | /pbr:review <N> | Verify a phase: automated 3-layer checks + conversational UAT | 1 |

See Commands for all 27 commands with flags, cost-by-depth tables, and detailed descriptions.

How It Works

Plan-Build-Run is a thin orchestrator that delegates heavy work to fresh subagent contexts via Task(). Data flows through files on disk, not through messages.

Main Session (~15% context)
  │
  ├── Task(researcher)  ──▶  writes .planning/research/
  ├── Task(planner)     ──▶  writes PLAN.md files
  ├── Task(executor)    ──▶  builds code, creates commits
  ├── Task(executor)    ──▶  (parallel, same wave)
  └── Task(verifier)    ──▶  checks codebase against must-haves

See Architecture for key concepts, the token-saving CLI, data flow details, and supporting directories.

Local LLM Offload

Plan-Build-Run can offload lightweight inference tasks to a local model running on your machine, saving frontier tokens and reducing API costs — without sacrificing quality on complex operations.

This is a novel capability. Other AI coding frameworks use local LLMs as the primary model or not at all. PBR operates at the sub-session level: hook scripts that fire on every tool call use a local model for fast classification tasks (artifact type, commit scope, error category, file intent) while the frontier model handles planning, execution, and verification. You get the cost savings of local inference where it matters, with automatic fallback to Claude when confidence is low.

How it works

Hook fires (e.g., PostToolUse:Write)
  │
  ├─ Complexity scorer evaluates the prompt
  │   └─ High complexity? → Route to frontier (Claude)
  │   └─ Low complexity? ↓
  │
  ├─ Local LLM classifies (Ollama, ~50-200ms)
  │   └─ Confidence below threshold? → Fallback to frontier
  │   └─ Confidence OK? → Use local result ✓
  │
  └─ Metrics logged to .planning/logs/local-llm-metrics.jsonl

Key features

• 3 routing strategies: local_first (default), balanced, quality_first — control the cost/quality tradeoff
• 8 offloadable operations: artifact classification, task validation, commit classification, error classification, file intent, test triage, source scoring, context summarization
• Shadow mode: Run local and frontier in parallel, compare results, but always use frontier output — safe way to validate local accuracy before trusting it
• Adaptive threshold tuning: Analyzes shadow logs to suggest confidence threshold adjustments per operation
• Circuit breaker: Automatically disables local routing after consecutive failures — no cascading slowdowns
• Session metrics: See tokens saved, cost reduction, and per-operation breakdowns via /pbr:status or the dashboard

Quick setup

# 1. Install Ollama (ollama.com/download)
# 2. Pull the recommended model
ollama pull qwen2.5-coder:7b

# 3. Enable in your project config
/pbr:config local_llm.enabled true

Requires a GPU with 6+ GB VRAM for best performance. CPU-only works but adds latency. See Configuration for full setup details, hardware requirements, and Windows-specific notes.

Deep Dive

| Topic | Description | |-------|-------------| | Agents | 12 specialized agents with configurable model profiles and file-based communication | | Configuration | 12 config keys, depth/model profiles, 14+ feature toggles, local LLM settings | | Hooks | 41 hook scripts that enforce discipline at zero token cost | | Local LLM | Offload hook-level inference to Ollama for token savings with automatic fallback | | Project Structure | The .planning/ directory layout, key files, and file ownership | | Dashboard | Web UI with live updates for browsing project state | | Cursor IDE | Cursor plugin installation and cross-IDE workflow | | Copilot CLI | GitHub Copilot CLI plugin: installation, hooks, and differences | | Philosophy | Design principles and platform alignment strategy | | What Sets It Apart | Feature comparison and key differentiators |

Platform Compatibility

Plan-Build-Run works across five platforms with varying levels of hook support. Hooks are the mechanism that fires validation scripts on every tool call — they power local LLM offloading, commit format enforcement, context budget tracking, and workflow gates.

| Feature | Claude Code | Copilot CLI | Cursor IDE | Codex CLI | Jules | |---------|:-----------:|:-----------:|:----------:|:---------:|:-----:| | Skills (slash commands) | All 27 | All 27 | All 27 | All 27 | All 27 | | Agents (subagent delegation) | All 12 | All 12 | All 12 | All 12 | All 12 | | .planning/ state management | Full | Full | Full | Full | Full | | Hook support | Full (14 events) | Partial (4 events) | Unverified | None | None | | Commit format enforcement | Hook-enforced | Hook-enforced | Manual | Manual | Manual | | PLAN/SUMMARY quality classification | Hook + skill fallback | Hook + skill fallback | Skill fallback only | Skill fallback only | Skill fallback only | | Test failure triage | Automatic (hook) | Automatic (hook) | Not available | Not available | Not available | | Context budget tracking | Automatic (hook) | Not available | Not available | Not available | Not available | | Auto-continue between skills | Automatic (hook) | Not available | Not available | Not available | Not available | | Subagent lifecycle logging | Automatic (hook) | Not available | Not available | Not available | Not available | | Local LLM offloading | Full (8 operations) | Mostly (6-7 operations) | CLI only | CLI only | CLI only | | pbr-tools.js llm CLI commands | Full | Full | Full | Full | Full |

Key differences:

• Claude Code has full hook support — all local LLM operations fire automatically on every tool call
• Copilot CLI supports sessionStart, preToolUse, postToolUse, and sessionEnd — covers most validation hooks but misses lifecycle events (SubagentStop, PreCompact, Stop)
• Cursor IDE hook support is unverified — hooks.json is configured but whether Cursor actually fires them is unknown. Skills include pbr-tools.js llm fallback calls for key operations (plan quality, verification quality) so local LLM classification is available even without hooks
• OpenAI Codex CLI and Google Jules do not support hooks. All skills and agents are available via plugins/codex-pbr/ and plugins/jules-pbr/ respectively. Agent definitions use AGENTS.md format.

All platforms share the same scripts via relative paths — no code duplication. See the Copilot CLI and Cursor IDE READMEs for platform-specific details.

Local Development

# Clone and install
git clone https://github.com/SienkLogic/plan-build-run.git
cd plan-build-run
npm install

# Run tests (9283 tests, 281 suites)
npm test

# Lint
npm run lint

# Validate plugin structure
npm run validate

# Load locally for manual testing
claude --plugin-dir .

CI runs on Node 18/20/22 across Windows, macOS, and Linux. See CONTRIBUTING.md for guidelines.

Stats

| Metric | Count | |--------|-------| | Skills (slash commands) | 27 | | Specialized agents | 12 | | Hook scripts | 41 | | Local LLM operations | 8 | | Supported platforms | 5 (Claude Code, Cursor, Copilot CLI, Codex, Jules) | | Tests | 9283 | | Test suites | 281 | | Config keys | 12 top-level (62+ properties) | | Feature toggles | 14 | | Lib modules | 19 | | Shared fragments | 12 | | Templates | 10 | | References | 19 |

License

MIT