Bmalph: BMAD planning + Ralph autonomous loop, glued together in one command

#ai #productivity #opensource #devtools

I built Bmalph because I kept running into the same problem: AI coding assistants are great at writing code, but terrible at remembering why you made a decision three features ago. You re-explain context, the architecture drifts, things contradict each other. For small projects that's fine. For anything real, it's a slow disaster.

bmalph is a CLI that combines two great existing open source projects: BMAD-METHOD for structured AI planning, and Ralph for autonomous implementation. One command installs and wires them together in your project.

Until last week it only worked with Claude Code. That's changed.

How it works

The core idea is simple: separate thinking from doing.

Phases 1-3 (BMAD — Planning)

Before any code gets written, you work interactively with specialized AI agents: an Analyst, a Product Manager, and an Architect. They guide you through producing a product brief, a PRD, UX specs, architecture decisions, and user stories. The AI asks questions. You make decisions. Nothing moves forward without your input.

The output is a set of real planning documents that live in your repo under _bmad-output/. Not chat history. Not a summary in your clipboard. Actual files that persist.

Phase 4 (Ralph — Implementation)

Once planning is done, Ralph takes those docs and implements them autonomously. It picks the next story from @fix_plan.md, writes tests first, implements the code, commits, and moves on to the next story. You don't babysit it. The loop runs until the board is empty or the circuit breaker trips.

The key thing Ralph has that vanilla Claude Code doesn't: a persistent spec. When it implements story 8, it still knows what was decided in story 1 because the planning docs are right there.

Multi-platform support

The initial release assumed Claude Code. That was limiting. This release adds support for six platforms across two tiers.

Platform	Tier	What you get
Claude Code	Full	Phases 1-4, BMAD + Ralph loop
OpenAI Codex	Full	Phases 1-4, BMAD + Ralph loop
Cursor	Instructions-only	Phases 1-3, BMAD planning only
Windsurf	Instructions-only	Phases 1-3, BMAD planning only
GitHub Copilot	Instructions-only	Phases 1-3, BMAD planning only
Aider	Instructions-only	Phases 1-3, BMAD planning only

The tier split comes down to one thing: whether the platform exposes a scriptable CLI. Ralph is a bash loop that spawns fresh AI sessions, so it needs claude or codex in your PATH. Cursor, Windsurf, Copilot, and Aider don't work that way, so they get the planning workflow only.

That said, Phases 1-3 alone are where most of the thinking happens. If you're on an instructions-only platform you still get the full BMAD workflow: analysts, PRDs, architecture, epics, stories.

Platform detection is automatic. Run bmalph init and it figures out which platform you're using from project markers. Or pass --platform <id> explicitly.

npm install -g bmalph

# auto-detect
bmalph init

# or be explicit
bmalph init --platform codex
bmalph init --platform cursor

How bmalph compares to just using your AI assistant directly

This comes up a lot so let me be direct about it.

Just prompting Claude Code / Cursor / Copilot directly

Fine for small tasks. A bug fix, a component, a quick script. bmalph is overkill for that. If you're reaching for bmalph on a weekend project you're over-engineering your workflow.

Where it breaks down is anything with multiple moving parts spanning more than a few sessions. The AI has no memory of earlier decisions, you end up re-explaining context constantly, and the architecture slowly drifts into something nobody planned.

BMAD-METHOD standalone

BMAD is great but setting it up manually in each project is friction. bmalph bundles and installs it with one command, keeps it versioned, and wires it to Ralph. If you're already using BMAD standalone, bmalph init is essentially a migration path — it preserves your _bmad-output/ artifacts.

Devin, SWE-agent, and other fully autonomous systems

Different category. Those are trying to do everything autonomously from a single prompt. bmalph keeps you in the loop during planning — you're making decisions with the AI agents, not handing off a spec and waiting. Ralph only takes over once you've explicitly approved the plan and triggered the implementation.

BMAD is now stable

Earlier versions had version drift issues where the bundled BMAD could get out of sync. That's fixed. The bundled version is now pinned, tested, and the upgrade path is clean.

bmalph upgrade

This updates the bundled BMAD and Ralph assets without touching _bmad-output/ — your planning artifacts are never overwritten.

What's next

A few things on the roadmap:

Story-level diff summary. After each story, Ralph automatically generates a readable summary of what changed, which files were touched, and whether tests passed. Right now that's buried in raw logs.

Automatic context regeneration. When Ralph gets stuck, the circuit breaker detects it and stops. Instead: automatically run GPC (Generate Project Context) and refresh the context before the next iteration.

Multi-agent Ralph. Instead of one Claude/Codex session per story, Ralph spawns a separate session per layer: one for tests, one for implementation, one for review. More complex, but closer to how a real team works..