BMAD-METHOD planning + Ralph autonomous implementation, wired through platform-specific instructions, skills, and command indexes.
bmalph bundles and installs two AI development systems:
bmalph provides:
bmalph init — Install both systemsbmalph upgrade — Update to latest versionsbmalph doctor — Check installation healthbmalph implement — Transition from BMAD to Ralphbmalph run — Start Ralph loop with live dashboardbmalph check-updates — Check for upstream updatesbmalph status — Show project status and phasebmalph reset — Remove all bmalph filesbmalph watchbmalph run insteadbmalph 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.
| Platform | ID | Tier | Instructions File | Commands |
|---|---|---|---|---|
| Claude Code | claude-code | full | CLAUDE.md | .claude/commands/ directory |
| OpenAI Codex | codex | full | AGENTS.md | Codex Skills (.agents/skills/) |
| OpenCode | opencode | full | AGENTS.md | OpenCode Skills (.opencode/skills/) |
| Cursor | cursor | full (experimental) | .cursor/rules/bmad.mdc | _bmad/COMMANDS.md |
| Windsurf | windsurf | instructions-only | .windsurf/rules/bmad.md | _bmad/COMMANDS.md |
| GitHub Copilot | copilot | full (experimental) | .github/copilot-instructions.md | _bmad/COMMANDS.md |
| Aider | aider | instructions-only | CONVENTIONS.md | _bmad/COMMANDS.md |
Tiers:
claude), Codex CLI (codex), OpenCode (opencode), Copilot CLI (copilot), or Cursor CLI (cursor-agent; older agent installs are also supported)npm install -g bmalph
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
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)CLAUDE.md, AGENTS.md, .cursor/rules/bmad.mdc).claude/commands/; Codex: .agents/skills/; OpenCode: .opencode/skills/; Cursor, Windsurf, Copilot, and Aider: _bmad/COMMANDS.md)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_bmad/, commit first so you can review changes with git diffWork interactively with BMAD agents in your AI coding assistant.
/bmalph to see your current phase and available commands.$analyst and $create-prd._bmad/COMMANDS.md and ask Cursor to run the BMAD master agent._bmad/COMMANDS.md as the command reference and ask the assistant to follow the named BMAD workflow.| Phase | Agent | Commands |
|---|---|---|
| 1 Analysis | Analyst | BP, MR, DR, TR, CB |
| 2 Planning | PM / UX Designer | CP, VP, EP, CU |
| 3 Solutioning | Architect / PM | CA, CE, IR |
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 techniquesMR Market Research — market analysis, competitive landscape, customer needsDR Domain Research — industry domain deep diveTR Technical Research — technical feasibility, architecture optionsCB Create Brief — guided experience to nail down your product ideaPhase 2 — Planning
CP Create PRD — expert led facilitation to produce your PRD (required)VP Validate PRD — validate PRD is comprehensive and cohesiveEP Edit PRD — improve and enhance an existing PRDCU Create UX — guidance through realizing the plan for your UXPhase 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 planningQD Quick Dev — quick implementation for small tasksDP Document Project — analyze existing project to produce documentationGPC Generate Project Context — scan codebase to generate LLM-optimized contextCC Correct Course — navigate significant changes mid-projectWD Write Document — tech writer agent for documentationMG Mermaid Generate — create Mermaid diagramsVD Validate Document — review documents against standardsBSP Brainstorming — interactive idea generation techniques (core, distinct from BP)ID Index Docs — create lightweight doc index for LLM scanningSD Shard Document — split large documents into smaller filesES Editorial Review (Structure) — propose document reorganizationAR Adversarial Review — critical content review for QAUS Update Standards — update tech-writer documentation standardsEC Explain Concept — create technical explanations with examples_bmad/COMMANDS.md — generated command reference for platforms without native slash commandsNote:
EPmeans Edit PRD in the bmm workflow (Phase 2) and Editorial Review — Prose in the core module.PMis Party Mode in core. The bmm meanings are the primary workflow codes.
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:
.ralph/@fix_plan.md with ordered tasks.ralph/specs/ with changelog trackingThen start Ralph:
bmalph run
Advanced: Ralph loads the platform drivers internally. Start the loop with
bmalph run, or runbash .ralph/ralph_loop.shdirectly 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.
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
Smart Merge: When you run bmalph implement again after Ralph has made progress:
[x]) are preserved in the new fix_plan[ ])Specs Changelog: .ralph/SPECS_CHANGELOG.md shows what changed in specs since the last run, so Ralph knows what's new or modified.
| Command | Description |
|---|---|
bmalph init | Install BMAD + Ralph into project |
bmalph upgrade | Update bundled assets to current version |
bmalph doctor | Check installation health |
bmalph check-updates | Check if bundled BMAD/Ralph versions are up to date |
bmalph status | Show current project status and phase |
bmalph implement | Transition BMAD planning artifacts to Ralph format |
bmalph run | Start Ralph loop with live dashboard |
bmalph reset | Remove all bmalph files from the project |
bmalph watch | (deprecated) Use bmalph run instead |
| Flag | Description |
|---|---|
--verbose | Enable debug logging |
--no-color | Disable colored output |
--quiet | Suppress non-essential output |
-C, --project-dir <path> | Run in specified directory |
--version | Show version |
--help | Show help |
| Flag | Description | Default |
|---|---|---|
-n, --name <name> | Project name | directory name |
-d, --description <desc> | Project description | (prompted) |
--platform <id> | Target platform (claude-code, codex, opencode, cursor, windsurf, copilot, aider) | auto-detect |
--dry-run | Preview changes without writing files |
| Flag | Description |
|---|---|
--force | Override pre-flight validation errors |
| Flag | Description |
|---|---|
--json | Output as JSON |
| Flag | Description |
|---|---|
--json | Output as JSON |
| Flag | Description |
|---|---|
--json | Output as JSON |
| Flag | Description |
|---|---|
--force | Skip confirmation prompts |
--dry-run | Preview changes |
| Flag | Description |
|---|---|
--dry-run | Preview changes |
--force | Skip confirmation prompt |
| Flag | Description |
|---|---|
--driver <platform> | Override platform driver (claude-code, codex, opencode, copilot, cursor) |
--review [mode] | Quality review: enhanced (every 5 loops) or ultimate (every story). Claude Code only |
--interval <ms> | Dashboard refresh interval in milliseconds (default: 2000) |
--no-dashboard | Run Ralph without the dashboard overlay |
Deprecated: Use
bmalph runinstead. Thewatchcommand will be removed in a future release.
| Flag | Description |
|---|---|
--interval <ms> | Refresh interval in milliseconds (default: 2000) |
bmalph bundles 54 BMAD and bmalph command definitions. Delivery varies by platform:
.claude/commands/ (invoke with /command-name).agents/skills/ (invoke with $command-name).opencode/skills/_bmad/COMMANDS.md; ask Cursor to run the BMAD master agent_bmad/COMMANDS.md reference indexKey commands (Claude Code syntax):
| Command | Description |
|---|---|
/bmalph | BMAD master agent — navigate phases |
/analyst | Analyst agent |
/pm | Product Manager agent |
/architect | Architect agent |
/dev | Developer agent |
/sm | Scrum Master agent |
/qa | QA agent |
/ux-designer | UX Designer agent |
/tech-writer | Tech Writer agent |
/quick-flow-solo-dev | Quick Flow solo developer agent |
/create-prd | Create PRD workflow |
/create-architecture | Create architecture workflow |
/create-epics-stories | Create epics and stories |
/bmad-help | List all BMAD commands |
For the full list:
/bmad-help.agents/skills/.opencode/skills/_bmad/COMMANDS.mdUse bmalph implement (or /bmalph-implement in Claude Code) to transition from BMAD planning to Ralph implementation.
project/
├── _bmad/ # BMAD agents, workflows, core
│ ├── config.yaml # Generated platform/project config
│ ├── COMMANDS.md # Generated command reference index
│ ├── _config/ # Generated manifests
│ │ ├── task-manifest.csv # Combined task manifest
│ │ ├── workflow-manifest.csv # Combined workflow manifest
│ │ └── bmad-help.csv # Combined help manifest
│ ├── core/
│ │ ├── agents/ # Master agent
│ │ ├── tasks/ # Workflow tasks
│ │ ├── workflows/ # Brainstorming, party-mode, etc.
│ │ ├── module.yaml # Core module metadata
│ │ └── module-help.csv # Core module help entries
│ └── bmm/
│ ├── agents/ # Analyst, PM, Architect, Dev, QA, etc.
│ ├── data/ # Templates (project-context-template.md)
│ ├── workflows/ # Phase 1-4 workflows
│ ├── teams/ # Agent team definitions
│ ├── module.yaml # BMM module metadata
│ └── module-help.csv # BMM module help entries
├── _bmad-output/ # BMAD planning artifacts (generated)
│ ├── planning-artifacts/ # PRD, architecture, stories
│ ├── implementation-artifacts/ # Sprint plans (optional)
│ └── brainstorming/ # Brainstorm sessions (optional)
├── .ralph/ # Ralph autonomous loop (drivers for claude-code, codex, opencode, copilot, and cursor)
│ ├── ralph_loop.sh # Main loop script
│ ├── ralph_import.sh # Import requirements into Ralph
│ ├── ralph_monitor.sh # Monitor loop progress
│ ├── .ralphrc # Ralph configuration
│ ├── RALPH-REFERENCE.md # Ralph usage reference
│ ├── drivers/ # Platform driver scripts
│ │ ├── claude-code.sh # Claude Code driver (uses `claude`)
│ │ ├── codex.sh # OpenAI Codex driver (uses `codex exec`)
│ │ ├── opencode.sh # OpenCode driver (uses `opencode run`)
│ │ ├── copilot.sh # GitHub Copilot driver (uses `copilot`, experimental)
│ │ ├── cursor.sh # Cursor driver (uses `cursor-agent`/`agent`, experimental)
│ │ └── cursor-agent-wrapper.sh # Wrapper for Windows .cmd Cursor installs
│ ├── lib/ # Shell libraries
│ ├── docs/generated/ # Generated documentation
│ ├── specs/ # Copied from _bmad-output during transition
│ ├── logs/ # Loop execution logs
│ ├── PROMPT.md # Iteration prompt template
│ ├── PROJECT_CONTEXT.md # Extracted project context (after bmalph implement)
│ ├── SPECS_CHANGELOG.md # Spec diff since last run (after bmalph implement)
│ ├── SPECS_INDEX.md # Prioritized spec file index (after bmalph implement)
│ ├── @AGENT.md # Agent build instructions
│ └── @fix_plan.md # Generated task list (after bmalph implement)
├── bmalph/ # State management
│ ├── config.json # Project config (name, description, platform)
│ └── state/ # Phase tracking data
├── .claude/ # Claude Code specific
│ └── commands/ # Slash commands (claude-code only)
└── <instructions file> # Varies by platform (see Supported Platforms)
The instructions file and command directory depend on the configured platform. See the Supported Platforms table for details.
Ralph is a bash loop that spawns fresh AI coding sessions using a platform driver matching the configured platform:
claude with --output-format json, --permission-mode bypassPermissions, --allowedTools, and explicit --resume <session_id>codex exec --json --sandbox workspace-write with explicit --resume <session_id>opencode run --agent build --format json with optional --continue --session <session_id>copilot --autopilot --yolo with plain-text outputcursor-agent -p --force --output-format json, persists session_id for --resume, and switches to stream-json only for live outputEach iteration:
@fix_plan.mdSafety mechanisms:
--review [mode], Claude Code only). Enhanced: periodic review every 5 loops. Ultimate: review after every completed story. A read-only session analyzes git diffs and feeds structured findings into the next implementation loop@fix_plan.md items are checked offCursor-specific runtime checks:
bmalph doctor validates command -v jq in the bash environment Ralph usesbmalph doctor validates command -v cursor-agent and cursor-agent statusbmalph run --driver cursor runs the same bash-scoped preflight before the loop startsRun bmalph run to start the loop with a live dashboard, or bmalph run --no-dashboard for headless mode. Press Ctrl+C to stop the loop at any time.
Ralph requires bash to run. On Windows, install one of:
Git Bash (Recommended)
# Install Git for Windows from https://git-scm.com/downloads
# Git Bash is included and works well with bmalph
# bmalph prefers Git Bash over broken Windows bash.exe shims
WSL (Windows Subsystem for Linux)
# In PowerShell as Administrator
wsl --install
# Then restart and run bmalph from WSL terminal
If you get permission errors:
# Claude Code only: broaden the tool allowlist in the managed config
# .ralph/.ralphrc
ALLOWED_TOOLS="Write,Read,Edit,MultiEdit,Glob,Grep,Task,TodoWrite,WebFetch,WebSearch,EnterPlanMode,ExitPlanMode,NotebookEdit,Bash"
# Keep interactive approval workflows out of unattended Claude loops
CLAUDE_PERMISSION_MODE="bypassPermissions"
# Keep the loop unattended by continuing after detected denials
PERMISSION_DENIAL_MODE="continue"
# Reset stale session state and restart
bash .ralph/ralph_loop.sh --reset-session
bmalph run
Notes:
ALLOWED_TOOLS only applies to the Claude Code driver and controls normal tool access.CLAUDE_PERMISSION_MODE="bypassPermissions" keeps unattended Claude loops out of interactive approval flows without relying on the unsupported afk-mode beta header..ralph/PROMPT.md.| Scenario | Solution |
|---|---|
| Commands fail before init | Run bmalph init first |
| Transition finds no stories | Create stories in Phase 3 with /create-epics-stories, the matching Codex Skill, or the _bmad/COMMANDS.md entry |
| Ralph stops mid-loop | Circuit breaker detected stagnation. Check .ralph/logs/ |
| Doctor reports version drift | Run bmalph upgrade to update bundled assets |
| Wrong platform detected | Re-run bmalph init --platform <id> with the correct platform |
| Ralph unavailable on platform | Ralph requires a full tier platform (claude-code, codex, opencode, copilot, or cursor) |
bmalph run --driver cursor is experimental on Windows and is designed for Git Bash.
bmalph prefers a working Git Bash install instead of Windows bash.exe shims.cursor-agent. The driver also accepts cursor-agent.cmd, agent, agent.cmd, and %LOCALAPPDATA%\\cursor-agent\\*.cmd as compatibility fallbacks.cursor-agent -p --force --output-format json and stores Cursor's session_id for --resume on the next loop.stream-json; background execution stays on JSON mode for reliable parsing.command -v jq, command -v cursor-agent, and cursor-agent status must all succeed in the same shell Ralph uses..ralph/ instead of trying to inline the full prompt on the command line.The simplest way to remove all bmalph files:
bmalph reset
Use --dry-run to preview what will be removed, or --force to skip confirmation.
If the CLI is unavailable, remove these directories and files manually:
rm -rf _bmad/ .ralph/ bmalph/
Then remove the bmalph-managed sections from your instructions file. The file depends on your platform:
.claude/commands/ and bmalph section from CLAUDE.mdAGENTS.md.opencode/skills/bmad-*/ and bmalph sections from AGENTS.md.cursor/rules/bmad.mdc.windsurf/rules/bmad.md.github/copilot-instructions.mdCONVENTIONS.mdSee the Supported Platforms table for details. After manual removal, run bmalph init to reinitialize.
# Interactive mode (prompts for name/description, auto-detects platform)
bmalph init
# Non-interactive mode
bmalph init --name my-app --description "My awesome app"
# Specify platform explicitly
bmalph init --name my-app --platform codex
bmalph init --name my-app --platform cursor
bmalph init --name my-app --platform windsurf
# Preview what would be created
bmalph init --dry-run
# Human-readable output
bmalph doctor
# JSON output for scripting
bmalph doctor --json
# Update BMAD and Ralph to latest bundled versions
bmalph upgrade
# Preview changes first
bmalph upgrade --dry-run
Claude Code:
# 1. Open Claude Code in your project
claude
# 2. Use the /bmalph slash command to start
# This shows your current phase and available commands
# 3. Follow the BMAD workflow:
# Phase 1: /analyst → create product brief
# Phase 2: /pm → create PRD
# Phase 3: /architect → create architecture and stories
# 4. Transition to Ralph
# Run: bmalph implement
# 5. Start autonomous implementation
bmalph run
OpenAI Codex:
# 1. Open your project in your AI coding assistant
# 2. Use Codex Skills such as $analyst, $create-prd, and $architect
# See .agents/skills/ and _bmad/COMMANDS.md for the full catalog
# 3. Follow phases: Analysis -> Planning -> Solutioning
# 4. Transition to Ralph
# Run: bmalph implement
# Then: bmalph run
OpenCode:
# 1. Open your project in your AI coding assistant
# 2. Use OpenCode Skills such as $analyst, $create-prd, and $architect
# See .opencode/skills/ and _bmad/COMMANDS.md for the full catalog
# 3. Follow phases: Analysis -> Planning -> Solutioning
# 4. Transition to Ralph
# Run: bmalph implement
# Then: bmalph run
Cursor, Copilot, Windsurf, Aider:
# 1. Open your project in your AI coding assistant
# 2. Read _bmad/COMMANDS.md for the available BMAD agents and workflows
# On Cursor specifically: ask Cursor to run the BMAD master agent
# 3. Follow phases: Analysis -> Planning -> Solutioning
# Or check progress from terminal: bmalph status
# 4. For full tier platforms (Cursor and Copilot), transition to Ralph:
# Run: bmalph implement
# Then: bmalph run
See CONTRIBUTING.md for development setup, test workflow, and commit guidelines.
MIT
FAQs
Unified AI Development Framework - BMAD phases with Ralph execution loop
The npm package bmalph receives a total of 189 weekly downloads. As such, bmalph popularity was classified as not popular.
We found that bmalph demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
TeamPCP is partnering with ransomware group Vect to turn open source supply chain attacks on tools like Trivy and LiteLLM into large-scale ransomware operations.
Security News
/Research
Widespread GitHub phishing campaign uses fake Visual Studio Code security alerts in Discussions to trick developers into visiting malicious website.
Security News
Five malicious npm packages typosquatting crypto libraries steal private keys via Telegram, targeting Solana and Ethereum developers, with active C2 infrastructure.