Stop Writing Code Manually! bmalph Runs Your Entire Dev Lifecycle

Stop Writing Code Manually! bmalph Runs Your Entire Dev Lifecycle

What if I told you that the most expensive mistake in modern software development isn't bad code—it's the gap between planning and execution? You've been there. Your team spends weeks in Figma, Notion, and Jira, crafting the perfect PRD and architecture docs. Then implementation begins, and somehow, the vision dissolves into spaghetti code, scope creep, and sprint deadlines that feel like fiction.

The brutal truth? Traditional development workflows are fundamentally broken. We plan like architects and build like firefighters, constantly context-switching between strategic thinking and tactical debugging. The cognitive load is insane. And with AI coding assistants exploding onto the scene—Claude Code, OpenAI Codex, Cursor, GitHub Copilot—we're drowning in potential but starving for structure.

Enter bmalph—the unified AI development framework that wires BMAD's battle-tested planning methodology directly into Ralph's autonomous implementation loop. This isn't another chatbot wrapper or prompt library. It's a complete operational system that transforms how engineering teams move from "what should we build?" to "it's shipped and tested." No more abandoned PRDs. No more architecture documents gathering digital dust. One command—bmalph run—and your AI agent executes stories with TDD discipline while you focus on what humans do best: judgment, creativity, and strategy.

Ready to see how the top engineering teams are 10x-ing their delivery speed without sacrificing quality? Let's expose exactly how bmalph works—and why you might never write boilerplate again.

What is bmalph? The Framework That Bridges Planning and Autonomous Execution

bmalph is a unified CLI framework created by Lars Cowe that bundles two powerhouse AI development systems into a single, coherent workflow:

• BMAD-METHOD — A rigorous, phase-driven planning methodology with specialized AI agents for analysis, planning, and solutioning (Phases 1-3)
• Ralph — An autonomous implementation loop that executes stories with test-driven development discipline (Phase 4)

The name itself hints at the marriage: BMAD + Ralph = bmalph. But this isn't mere packaging. bmalph solves the integration problem that has plagued AI-assisted development since its inception. Every platform—whether Claude Code, OpenAI Codex, Cursor, or GitHub Copilot—speaks a slightly different dialect. bmalph translates your BMAD planning artifacts into platform-native instructions, commands, and skills, then orchestrates Ralph's execution loop with zero friction.

Why is bmalph trending now? Three converging forces:

1. AI coding assistants have matured—Claude Code's agentic capabilities, Codex's sandboxed execution, and Cursor's context awareness finally make autonomous loops reliable, not reckless.
2. Teams are hitting the "prompt ceiling"—ad-hoc AI interactions don't scale. bmalph provides the process infrastructure that turns sporadic AI help into systematic engineering velocity.
3. The BMAD methodology has proven itself across hundreds of projects, with structured phases that prevent the "planning theater" that kills so many initiatives.

bmalph is distributed via npm with full CI/CD, code coverage tracking, and active maintenance. It's not a side project—it's production infrastructure for the AI-native engineering team.

Key Features: The Technical Architecture That Makes Autonomous Development Possible

Let's dissect what makes bmalph actually work at the implementation level—not just the marketing gloss.

Unified CLI with Platform-Native Delivery

bmalph installs as a single global npm package, then detects and adapts to your AI platform automatically. Strong markers like .cursor/, .claude/, .opencode/ directories trigger instant recognition. Weak hints like root-level AGENTS.md or CLAUDE.md prompt interactive clarification. This means zero configuration guesswork—run bmalph init and the framework becomes native to your environment.

54 Command Definitions, Platform-Optimized

The framework bundles 54 BMAD and bmalph commands, delivered through each platform's native mechanism:

• Claude Code: Slash commands in .claude/commands/ (/bmalph, /analyst, /create-prd)
• OpenAI Codex: Skills in .agents/skills/ ($analyst, $create-prd)
• OpenCode: Skills in .opencode/skills/
• Cursor, Windsurf, Copilot, Aider: Command reference in _bmad/COMMANDS.md

This isn't a lowest-common-denominator abstraction. Each delivery mechanism leverages the platform's strengths—Claude's slash command UX, Codex's skill system, Cursor's rule-based context injection.

Smart State Management and Migration

bmalph maintains project state in bmalph/config.json and bmalph/state/, tracking your current phase and platform. Already using standalone BMAD? bmalph init migrates cleanly—framework files are replaced, but your precious _bmad-output/ planning artifacts remain untouched. Customized _bmad/ files? The CLI warns you to commit first, preserving your diffs for review.

Ralph's Autonomous Loop with Safety Mechanisms

The Ralph loop isn't a naive "prompt and pray" system. It includes:

• Circuit breaker: Halts on stagnation or repeated failures
• Response analyzer: Detects stuck or looping AI outputs
• Optional quality review: enhanced mode (every 5 loops) or ultimate mode (every story) for Claude Code
• TDD enforcement: Tests before code, every story

Swarm Mode for Parallel Epic Execution

bmalph run --swarm [N] spawns N parallel Ralph workers in isolated git worktrees, each tackling different epics. Rate limits are divided, starts are staggered by 5 seconds, and branches merge back sequentially. This is distributed autonomous development—not science fiction, but npm install -g bmalph away.

Live Dashboard and Headless Operation

Run with bmalph run for a live dashboard overlay, or bmalph run --no-dashboard for CI/CD integration. The dashboard refreshes every 2000ms by default, configurable via --interval.

Use Cases: Where bmalph Transforms Engineering Outcomes

1. Startup MVPs: From Idea to Tested Code in 48 Hours

Early-stage teams can't afford planning overhead or technical debt. With bmalph, a solo founder runs Phase 1-3 with /analyst and /pm to validate the problem and craft a lean PRD, then bmalph implement → bmalph run delivers tested features while they sleep. The circuit breaker prevents runaway scope, and TDD ensures the codebase doesn't become a liability before Series A.

2. Enterprise Feature Teams: Scaling Consistent Architecture

Large engineering organizations struggle with architectural drift—every team invents their own patterns. BMAD's structured Phase 3 (/create-architecture, /create-epics-stories) enforces consistent decision documentation. Ralph's autonomous execution means senior architects focus on reviewing AI-generated implementations rather than writing boilerplate. The @fix_plan.md and SPECS_CHANGELOG.md create audit trails that compliance teams love.

3. Agency Delivery: Fixed-Price Projects Without Fixed-Price Risk

Consultancies on fixed bids face the estimation death spiral—uncertain scope, changing requirements, margin erosion. bmalph's phase-gated workflow (validate-brief, validate-prd, validate-architecture) surfaces risks before implementation commits. The QS (Quick Spec) and QD (Quick Dev) commands handle out-of-scope client requests without derailing the main delivery. Ralph's deterministic loop means predictable burn rates.

4. Open Source Maintenance: Automated Dependency Updates and Refactoring

Maintaining popular libraries means endless dependency bumps, API migrations, and community PR reviews. Use bmalph init with --platform cursor or --platform codex, then DP (Document Project) to generate current context, GPC (Generate Project Context) for LLM-optimized codebase understanding, and Ralph to execute mechanical refactoring across the full test suite. The swarm mode parallelizes work across multiple major version migrations.

Step-by-Step Installation & Setup Guide

Prerequisites

Before installing, ensure your environment meets these requirements:

• Node.js 20+ (check with node --version)
• Bash (WSL or Git Bash on Windows—Ralph's loop requires a proper shell)
• A supported AI coding platform from the full or instructions-only tier
• For Phase 4 (Ralph loop): CLI access to Claude Code (claude), Codex CLI (codex), OpenCode (opencode), Copilot CLI (copilot), or Cursor CLI (cursor-agent)

Global Installation

npm install -g bmalph

This installs the bmalph CLI globally with all bundled BMAD and Ralph assets.

Project Initialization

Navigate to your project directory and initialize:

cd my-project
bmalph init --name my-project

Platform resolution priority: --platform flag > auto-detect from project markers > interactive prompt > default claude-code

For explicit platform targeting:

bmalph init --name my-project --platform codex
bmalph init --name my-project --platform cursor
bmalph init --name my-project --platform windsurf

Preview mode (no files written):

bmalph init --dry-run

What bmalph init Installs

project/
├── _bmad/              # BMAD agents, workflows, core
├── .ralph/             # Ralph loop, drivers, specs
├── bmalph/             # State management (config.json)
├── .claude/commands/   # (if claude-code) Slash commands
└── CLAUDE.md           # (if claude-code) BMAD instructions

Health Check and Updates

# Verify installation integrity
bmalph doctor

# Check for upstream BMAD/Ralph updates
bmalph check-updates

# Update bundled assets to latest versions
bmalph upgrade

Troubleshooting: Windows Bash

If Ralph fails with "bash not found":

# Option 1: Install Git for Windows (includes Git Bash)
# Download from https://git-scm.com/downloads

# Option 2: Enable WSL
wsl --install  # Run in PowerShell as Administrator

REAL Code Examples: bmalph in Action

Let's examine actual code patterns from the bmalph repository, with detailed explanations of how each piece functions in the unified workflow.

Example 1: Initialize and Auto-Detect Platform

# Navigate to project and initialize with interactive prompts
# bmalph detects platform markers automatically
cd my-project
bmalph init

# Non-interactive: specify everything upfront
bmalph init --name my-app --description "My awesome app" --platform codex

# Preview without writing files—see what would change
bmalph init --dry-run

What's happening here? The init command performs platform resolution in strict priority: explicit --platform flag first, then scanning for strong markers (.cursor/, .claude/, .opencode/, etc.), then weak hints (AGENTS.md, CLAUDE.md in root only), then interactive fallback, finally defaulting to claude-code. The --dry-run flag is essential for CI/CD pipelines or cautious team leads who want to review changes before committing. After resolution, bmalph writes platform-specific instructions (e.g., CLAUDE.md, AGENTS.md, .cursor/rules/bmad.mdc) and delivers commands through native mechanisms—.claude/commands/ for Claude, .agents/skills/ for Codex, _bmad/COMMANDS.md for others.

Example 2: Run the Ralph Autonomous Loop

# Standard: start Ralph with live dashboard
bmalph run

# Headless mode for CI/CD integration
bmalph run --no-dashboard

# Override platform driver (useful for testing or multi-platform projects)
bmalph run --driver codex

# Enhanced quality review every 5 loops (Claude Code only)
bmalph run --review enhanced

# Ultimate review after every completed story (Claude Code only)
bmalph run --review ultimate

# Parallel swarm: 2-6 workers on different epics
bmalph run --swarm 4

# Custom dashboard refresh interval (default 2000ms)
bmalph run --interval 5000

The technical depth here is critical. Ralph's loop is implemented in bash (ralph_loop.sh) and spawns fresh AI sessions via platform drivers. The Claude Code driver, for instance, invokes:

claude --output-format json --permission-mode bypassPermissions \
       --allowedTools Write,Read,Edit,MultiEdit,Glob,Grep,Task,TodoWrite,WebFetch,WebSearch \
       --resume <session_id>

Each iteration: pick next unchecked story from @fix_plan.md, implement with TDD (tests first, then code), commit, advance. The --review modes are read-only analysis sessions that examine git diffs and feed structured findings into subsequent loops—not just prettier output, but actual quality gates that modify loop behavior.

Swarm mode uses git worktrees for true isolation—each worker gets its own branch (swarm/worker-1, etc.), own @fix_plan.md subset, and rate limit budget. The greedy bin-packing algorithm balances epic distribution. After completion, branches merge sequentially with conflict detection that preserves manual resolution branches rather than clobbering work.

Example 3: Transition from BMAD Planning to Ralph Implementation

# After completing Phases 1-3 with BMAD agents
# This command transforms planning artifacts into Ralph's execution format
bmalph implement

# Force transition even if pre-flight validation warns
bmalph implement --force

This is where the magic happens. The implement command performs a structured artifact transformation:

1. Reads stories from _bmad-output/planning-artifacts/
2. Generates .ralph/@fix_plan.md with ordered, checkable tasks
3. Copies specs to .ralph/specs/ with SPECS_CHANGELOG.md tracking
4. Extracts PROJECT_CONTEXT.md for Ralph's prompt template
5. Creates SPECS_INDEX.md for prioritized file access

The smart merge logic handles incremental development: if Ralph has already completed some stories ([x]), re-running bmalph implement preserves those completions while adding new BMAD stories as pending ([ ]). The SPECS_CHANGELOG.md diff tells Ralph exactly what's changed since last run—no redundant work, no missed requirements.

Example 4: Claude Code Workflow with Slash Commands

# Terminal: initialize project
bmalph init --name my-api --platform claude-code

# Start Claude Code in project directory
claude

# Inside Claude Code session:
# /bmalph          → Show current phase and available commands
# /analyst         → Start Phase 1: Analysis agent
# /create-prd      → Phase 2: Create Product Requirements Document
# /create-architecture → Phase 3: Technical architecture
# /create-epics-stories → Phase 3: Implementation stories

# Terminal: transition to implementation
bmalph implement

# Terminal: start autonomous execution
bmalph run

This exemplifies the full bmalph lifecycle. The slash commands aren't aliases—they're full workflow definitions installed as files in .claude/commands/, each triggering multi-step agent interactions with structured outputs. The /bmalph master agent maintains phase awareness, preventing you from running /create-architecture before completing Phase 2 validation. The terminal commands (bmalph implement, bmalph run) bridge from interactive planning to autonomous execution without leaving your shell.

Advanced Usage & Best Practices

Permission Configuration for Unattended Loops

For truly autonomous operation, configure .ralph/.ralphrc:

# Broad tool allowlist for Claude Code driver
ALLOWED_TOOLS="Write,Read,Edit,MultiEdit,Glob,Grep,Task,TodoWrite,WebFetch,WebSearch,EnterPlanMode,ExitPlanMode,NotebookEdit,Bash"

# Bypass interactive approvals (supported mode, not beta header)
CLAUDE_PERMISSION_MODE="bypassPermissions"

# Continue loop after detected denials instead of hanging
PERMISSION_DENIAL_MODE="continue"

Critical distinction: bmalph uses bypassPermissions—a supported Claude Code flag—not the deprecated afk-mode beta. This is production-stable unattended execution.

Reset and Recovery Patterns

# Soft reset: preview what would be removed
bmalph reset --dry-run

# Hard reset: remove all bmalph files
bmalph reset --force

# Session recovery: Ralph stuck? Reset and restart
bash .ralph/ralph_loop.sh --reset-session
bmalph run

CI/CD Integration

# JSON output for programmatic consumption
bmalph doctor --json
bmalph status --json
bmalph check-updates --json

# Headless Ralph with custom interval
bmalph run --no-dashboard --interval 10000

Platform-Specific Optimization

• Claude Code: Use --review ultimate for safety-critical code; --swarm for maximum throughput
• Codex: Leverage sandboxed execution with codex exec --sandbox workspace-write
• Cursor: Validate jq and cursor-agent availability with bmalph doctor before looping
• Windows: Always prefer Git Bash over bash.exe shims; the Cursor driver includes .cmd compatibility fallbacks

Comparison with Alternatives: Why bmalph Wins

The decisive advantage: bmalph isn't competing with Claude Code or Cursor—it's completing them. Raw AI assistants are capabilities; bmalph is orchestration. Traditional tools manage human work; bmalph manages AI-human hybrid work. Other frameworks typically lock you to one platform or lack the rigorous phase-gate methodology that prevents "garbage in, garbage out."

FAQ: Developer Concerns Addressed

Is bmalph replacing human developers?

No—it's amplifying them. BMAD's Phase 1-3 requires human judgment for product decisions, market analysis, and architectural trade-offs. Ralph handles implementation execution, but humans review, guide, and intervene. The circuit breaker and review modes ensure quality gates remain human-controlled.

Which platforms support full autonomous execution (Phase 4)?

Full tier: Claude Code, OpenAI Codex, OpenCode, GitHub Copilot, Cursor. Instructions-only tier (Phases 1-3 only): Windsurf, Aider. Copilot and Cursor support is marked experimental—test thoroughly before production reliance.

Can I use bmalph with existing BMAD installations?

Yes. bmalph init detects existing _bmad/ directories and migrates cleanly. Your _bmad-output/ planning artifacts are preserved. Framework files are replaced with bmalph-managed versions—commit customizations first to review diffs.

How does Ralph handle test failures or infinite loops?

The circuit breaker detects stagnation (repeated failures, no progress) and halts the loop. The response analyzer identifies stuck or repeating AI outputs. Check .ralph/logs/ for diagnostics, then resume with bmalph run or reset the session.

Is Windows fully supported?

Yes, with caveats. Ralph requires bash—use Git Bash (recommended) or WSL. The Cursor driver includes Windows-specific fallbacks for .cmd installs. Run bmalph doctor to validate your environment before starting loops.

What's the difference between bmalph run and bmalph watch?

bmalph watch is deprecated—use bmalph run instead. The run command provides the live dashboard, headless mode, swarm execution, and all modern features. watch will be removed in a future release.

How do I contribute or report issues?

The repository includes CONTRIBUTING.md with development setup, test workflows, and commit guidelines. Issues and PRs are welcome at github.com/LarsCowe/bmalph.

Conclusion: The Future of Development Is Orchestrated, Not Manual

After dissecting bmalph's architecture, running its loops, and comparing it against every alternative on the market, here's my unvarnished take: this is the most coherent attempt yet to solve the "last mile" of AI-assisted development.

The problem was never that AI can't write code. It's that planning and execution live in separate universes—BMAD without Ralph is brilliant strategy with no army; Ralph without BMAD is an army with no strategy. bmalph's genius is the wiring: platform-specific instruction delivery, smart artifact transformation, and safety mechanisms that keep autonomous loops productive rather than destructive.

For teams already using Claude Code, Codex, or Cursor, the activation energy is minimal—one npm install -g bmalph and bmalph init away from structured workflows. For teams drowning in planning debt, the BMAD methodology alone justifies adoption. And for anyone who's watched AI-generated code spiral into unmaintainable complexity, Ralph's TDD enforcement and circuit breakers provide the guardrails that make trust possible.

The engineering teams that dominate the next decade won't be those with the best individual coders. They'll be those with the best orchestration. bmalph is that orchestration layer—open source, actively maintained, and ready for your next project.

Stop writing code manually. Start orchestrating outcomes.

👉 Get bmalph on GitHub — star the repo, run npm install -g bmalph, and transform your first project today.