~~bmalph watch~~ — (deprecated) Use bmalph run instead
Supported Platforms
bmalph works with multiple AI coding assistants. Each platform gets BMAD planning (Phases 1-3). The Ralph autonomous loop (Phase 4) requires a CLI-based platform.
full — Phases 1-4. BMAD planning + Ralph autonomous implementation loop.
instructions-only — Phases 1-3. BMAD planning only. Ralph is not available.
Prerequisites
Node.js 20+
Bash (WSL or Git Bash on Windows)
A supported AI coding platform (see table above)
For Ralph loop (Phase 4): Claude Code (claude), Codex CLI (codex), OpenCode (opencode), Copilot CLI (copilot), or Cursor CLI (cursor-agent; older agent installs are also supported)
Installation
npm install -g bmalph
Quick Start
cd my-project
bmalph init --name my-project
# To target a specific platform, add --platform (e.g. codex, cursor, windsurf)
# Without --platform, bmalph auto-detects strong project markers and
# prompts interactively when detection is ambiguous or missing
Workflow
Step 1: Initialize
cd my-project
bmalph init
Platform resolution:--platform flag > auto-detect from project markers > interactive prompt > default claude-code
Strong markers such as .cursor/, .claude/, .opencode/, .windsurf/, .github/copilot-instructions.md, and .aider.conf.yml are auto-detected directly. Root-only AGENTS.md and CLAUDE.md are treated as weak hints and may still trigger the interactive platform prompt.
This installs:
_bmad/ — BMAD agents and workflows
.ralph/ — Ralph loop, libs, templates (drivers for claude-code, codex, opencode, copilot, and cursor)
bmalph/ — State management (config.json, stores selected platform)
Updates the platform's instructions file with BMAD workflow instructions (e.g. CLAUDE.md, AGENTS.md, .cursor/rules/bmad.mdc)
Delivers BMAD commands using the platform's native mechanism (Claude Code: .claude/commands/; Codex: .agents/skills/; OpenCode: .opencode/skills/; Cursor, Windsurf, Copilot, and Aider: _bmad/COMMANDS.md)
Migrating from standalone BMAD
If you already have BMAD installed (a _bmad/ directory), bmalph init works as a migration path:
_bmad/ (framework files) will be replaced with the bmalph-managed version
_bmad-output/ (your planning artifacts: PRDs, architecture, stories) is not touched
If you've customized framework files inside _bmad/, commit first so you can review changes with git diff
Step 2: Plan with BMAD (Phases 1-3)
Work interactively with BMAD agents in your AI coding assistant.
Claude Code — use /bmalph to see your current phase and available commands.
OpenAI Codex — use Codex Skills such as $analyst and $create-prd.
Cursor — Read _bmad/COMMANDS.md and ask Cursor to run the BMAD master agent.
Windsurf, Copilot, Aider — use _bmad/COMMANDS.md as the command reference and ask the assistant to follow the named BMAD workflow.
Validation commands (validate-brief, validate-prd, validate-ux, validate-architecture, validate-epics-stories) run the same workflow in Validate mode. In Claude Code, invoke them as slash commands; on other platforms use the equivalent entry from _bmad/COMMANDS.md or Codex Skills.
Phase 1 — Analysis
BP Brainstorm Project — guided facilitation through brainstorming techniques
MR Market Research — market analysis, competitive landscape, customer needs
DR Domain Research — industry domain deep dive
TR Technical Research — technical feasibility, architecture options
CB Create Brief — guided experience to nail down your product idea
Phase 2 — Planning
CP Create PRD — expert led facilitation to produce your PRD (required)
VP Validate PRD — validate PRD is comprehensive and cohesive
EP Edit PRD — improve and enhance an existing PRD
CU Create UX — guidance through realizing the plan for your UX
Phase 3 — Solutioning
CA Create Architecture — guided workflow to document technical decisions (required)
CE Create Epics and Stories — create the epics and stories listing (required)
IR Implementation Readiness — ensure PRD, UX, architecture, and stories are aligned (required)
Anytime Commands
Available in any phase for supporting tasks:
QS Quick Spec — lightweight spec for small tasks without full planning
QD Quick Dev — quick implementation for small tasks
DP Document Project — analyze existing project to produce documentation
CC Correct Course — navigate significant changes mid-project
WD Write Document — tech writer agent for documentation
MG Mermaid Generate — create Mermaid diagrams
VD Validate Document — review documents against standards
BSP Brainstorming — interactive idea generation techniques (core, distinct from BP)
ID Index Docs — create lightweight doc index for LLM scanning
SD Shard Document — split large documents into smaller files
ES Editorial Review (Structure) — propose document reorganization
AR Adversarial Review — critical content review for QA
US Update Standards — update tech-writer documentation standards
EC Explain Concept — create technical explanations with examples
_bmad/COMMANDS.md — generated command reference for platforms without native slash commands
Note:EP means Edit PRD in the bmm workflow (Phase 2) and Editorial Review — Prose in the core module. PM is Party Mode in core. The bmm meanings are the primary workflow codes.
Step 3: Implement with Ralph (Phase 4)
Note: Ralph is only available on full tier platforms (Claude Code, OpenAI Codex, OpenCode, GitHub Copilot, Cursor). Instructions-only platforms (Windsurf, Aider) support Phases 1-3 only. GitHub Copilot and Cursor support is experimental.
Run bmalph implement from the terminal, or use the /bmalph-implement slash command in Claude Code.
This transitions your BMAD artifacts into Ralph's format:
Reads your stories from BMAD output
Generates .ralph/@fix_plan.md with ordered tasks
Copies specs to .ralph/specs/ with changelog tracking
Instructs you to start the Ralph autonomous loop
Then start Ralph:
bmalph run
Advanced: Ralph loads the platform drivers internally. Start the loop with bmalph run, or run bash .ralph/ralph_loop.sh directly if you need to bypass the CLI.
Ralph picks stories one by one, implements with TDD, and commits. The loop stops when all stories are done or the circuit breaker triggers.
Incremental Development
bmalph supports iterative development cycles:
BMAD (Epic 1) → bmalph implement → Ralph works on Epic 1
↓
BMAD (add Epic 2) → bmalph implement → Ralph sees changes + picks up Epic 2
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
A Claude Code plugin that automatically captures everything Claude does during your coding sessions, compresses it with AI (using Claude's agent-sdk), and injects relevant context back into future sessions.
