bmalph CLI
A CLI that installs BMAD planning and the Ralph loop: BMAD roles write the PRD and stories, then an agent builds them test-first
- 407 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The Ralph loop runs the agent with no questions: in Claude Code it uses `bypassPermissions`, edits files and commits on its own
- In `--swarm` mode workers change separate branches, and a conflict has to be resolved by hand
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/bmalphDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The Ralph loop runs the agent with no questions: in Claude Code it uses `bypassPermissions`, edits files and commits on its own
- In `--swarm` mode workers change separate branches, and a conflict has to be resolved by hand
This is third-party code. Review the repository files before installing.
What it does
bmalph is an npm package with a bmalph command that assembles two systems in a project. BMAD-METHOD handles planning: roles such as analyst, product manager and architect talk you through analysis, the PRD, architecture and epics with stories. Ralph handles implementation: a bash loop starts a fresh agent session again and again, takes the next story from `@fix_plan.md`, writes tests and code, and commits. `bmalph init` puts the `_bmad/`, `.ralph/` and `bmalph/` folders into the project and appends platform instructions, for example to `CLAUDE.md` or `AGENTS.md`. In Claude Code the BMAD commands land in `.claude/commands/`, in Codex they become skills in `.agents/skills/`, in OpenCode in `.opencode/skills/`. For Cursor, Windsurf, Copilot and Aider a `_bmad/COMMANDS.md` reference remains. `bmalph implement` turns the BMAD stories into the Ralph plan, and `bmalph run` starts the loop with a status dashboard. A circuit breaker interrupts the loop when a story stalls. The `--review` flag adds code review in Claude Code, and `--swarm` starts two to six workers in separate git worktrees, each on its own epics.
Who it is for. Teams and solo developers who take a project from idea to code with BMAD and want to hand implementation to an autonomous loop on Claude Code, Codex, OpenCode, Copilot or Cursor.
Good fit when
- A project starts from zero and the idea has to become a PRD, architecture and a story list before the first line of code
- The story list is ready and you want to hand implementation to a loop that goes through the stories with tests and a commit after each
- A project has plain BMAD installed and moves under bmalph: `bmalph init` replaces `_bmad/` and leaves the plans in `_bmad-output/` alone
- There are several epics and workers can run them in parallel in isolated branches
- The team sits in Windsurf or Aider and takes only BMAD planning without the loop
Not a fit when
- A task of a couple of edits: a full BMAD pass is too much, and BMAD has Quick Spec and Quick Dev for small jobs
- You need to watch every step: Ralph in Claude Code runs with `bypassPermissions` and asks the human nothing
- A working tree with uncommitted edits: `--swarm` requires a clean tree and at least two unfinished epics
Example request
Run /create-prd for a task tracker app and walk me through the planning phase, then remind me about bmalph implement once the stories are readyLimitations
Node.js 20 or newer and bash are required. On Windows the loop runs through Git Bash or WSL. The Ralph loop is available on Claude Code, Codex, OpenCode, Copilot and Cursor, with Copilot and Cursor labelled experimental by the author. Windsurf and Aider get BMAD planning only. The `--review` code check works only with Claude Code. The `bmalph watch` command is deprecated in favor of `bmalph run`. The Cursor driver on Windows is experimental and designed for Git Bash, and `bmalph doctor` checks for `jq` and `cursor-agent`.
How to disable. The `bmalph reset` command removes every bmalph file from the project, and with `--dry-run` it first shows what will go. The package itself comes off with `npm uninstall -g bmalph`. A running loop stops with Ctrl+C.
FAQ
How do I install bmalph and start?
Run `npm install -g bmalph`, then `bmalph init --name my-project` in the project folder. Without `--platform`, bmalph detects the platform from project markers and asks you when it is unclear.
How does BMAD planning differ from the Ralph loop?
BMAD runs a dialogue: analysis, PRD, architecture, epics and stories. Ralph runs without one: it takes a story from `@fix_plan.md`, writes tests and code, commits and moves on. `bmalph implement` sits between them.
What does the loop do when a story fails?
A circuit breaker interrupts the loop when a story stalls, and a response analyzer notices stuck or repeating output. Look for the cause in the logs under `.ralph/logs/`.
How do I run workers in parallel?
With `bmalph run --swarm 3`: two workers by default, six at most. You need a clean tree, at least two unfinished epics, a full-tier platform and a HEAD that is not detached. When they finish, the branches merge one by one, and on a conflict the merge stops and the branches are kept.
Which platforms are supported?
Claude Code, OpenAI Codex, OpenCode, Cursor, Windsurf, GitHub Copilot and Aider. The Ralph loop exists on Claude Code, Codex, OpenCode, Cursor and Copilot; Windsurf and Aider get planning only.
Discussion
No questions or reviews yet.
Related
CLI toolsThe ralph command repeats one prompt for Claude Code, Codex, Cursor Agent or OpenCode until a completion tag appears in the reply
A Ralph loop for long tasks: an agent in a Docker sandbox works through a PRD task list, checks each task with tests and commits until the list is done
A terminal dashboard that drives Claude Code, Codex and five more agents through a task list in a loop until the list is done
A CLI orchestrator that loops Claude Code, Codex, Gemini CLI and other agents until a task is done and blocks incomplete work with tests and lint
Autonomous plan execution task by task: each task in a fresh Claude Code or Codex session, then a multi-pass review. Written in Go
An autonomous spec-driven coding loop: the agent takes a task, checks acceptance criteria and commits until the list runs out.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| bmalph (this card) | no | 407 | |
| BMad Method | no | 55,080 | the BMAD roles and workflows themselves, with no implementation loop |
| Open Ralph Wiggum | no | 1,908 | repeats one prompt until a completion marker and does not plan a project |
README in short
The README opens with a flow diagram from BMAD planning to the Ralph loop, then a platform table with support tiers, a quick start and the BMAD phases with their command codes. Next come the command and flag reference, the project layout after `bmalph init`, how the Ralph loop works with swarm mode, and a troubleshooting section that covers Windows and Cursor setup.