A newcomer path from an empty terminal to a reviewed first result: install, check, talk to your first agent, review, keep context, stay up to date. Each step with the real command and what to expect.
This page takes you from nothing to a first result you have reviewed yourself, in an order that works. You need a project folder, Node.js 20 or newer, and an AI coding tool you already use (Claude Code, Gemini CLI, Cursor, Codex CLI and others). BMAD+ supplies the instructions, roles and workflows; your tool supplies the model and the permissions to edit files and run commands. Nothing here needs an account with BMAD+, an API key of its own or a background service.
BMAD+ in briefWhat BMAD+ installs, how a pack asks before it acts, how a swarm is counted honestly, and the ten packs.Transcript
BMAD+ installs roles, workflows and shared context into the AI coding tool you already use. It starts by asking: a pack declares the questions it needs answered before it acts. You answer a few at a time, and what you do not know is recorded as unknown, with its risk. Then Nexus can run a swarm of sub-agents, within a budget you set. Each one reads a brief and writes an answer, and only valid answers are counted. The tally on screen is demo data, and it says plainly that simulated units are not people. For planned work, Nexus requires independent checks before it accepts a result. Core's four roles, nine optional packs, and adapters for seven AI coding tools. Install it with one npx command from your project folder.
Commands that start with npx bmad-plus go in a terminal. Sentences such as bmad-help, autopilot, parallel or "Atlas, ..." go in the chat of your AI tool. Typing autopilot in a terminal does nothing useful.
Use the repository you want to work on. The command should print v20 or higher; install or update Node.js separately if it does not.
In your project terminal
node --version
02
Run the installer
The interactive wizard asks for your language, the packs, the tools (if none is detected), your name, your communication language, a test-environment URL for acceptance recipes (optional) and the execution mode. Core is always installed. The tools are detected from folders such as .claude/ or .cursor/.
In your project terminal
npx bmad-plus@0.23.1 install
03
Or install without questions
For a script or a first try, give everything on the command line. --yes skips the wizard (English by default unless you pass --lang); --tools takes ids such as claude-code, gemini-cli, antigravity, cursor, codex-cli, opencode, aider, or all or none.
The installer ends with a short guide of who to talk to and a line such as "BMAD+ is ready! Talk to Atlas to get started". With an unknown pack or tool id it stops and prints the valid ids; without a terminal and without --yes it refuses to run.
What the install leaves in a Git project
$ npx bmad-plus install --yes --lang en --packs core --tools claude-code$ git status --short?? .agents/?? AGENTS.md?? CLAUDE.md?? _bmad/$ ls .agents/skillsagent-architect-devagent-orchestratoragent-qualityagent-strategistbmad-plus-autopilotbmad-plus-intakebmad-plus-parallelbmad-plus-swarmbmad-plus-syncbmad-plus-uat# Four new paths, nothing in your source tree. Decide with your team whether to commit them or ignore them; either way, `_bmad/.bmad-plus-install.json` records which files BMAD+ owns.
npx bmad-plus install --yes --lang en --packs core --tools claude-code
git status --short
ls .agents/skills
Output captured from a real run. Source: Replayed on a test server on 2026-10-18 with the 0.23.0 source (tools/cli/bmad-plus-cli.js) in a throwaway Git project
The installer does not put bmad-plus in your project’s node_modules, and the npx --no-install commands used from here on run only a local copy: without it they stop with npx canceled due to missing packages and no YES option. This adds a dev dependency to package.json. Skip the step if you prefer to type npx bmad-plus <command> instead, which downloads the package when needed. Without a local copy, the update check that the generated CLAUDE.md and AGENTS.md ask your assistant to run is simply skipped.
In your project terminal
npm install --save-dev bmad-plus
02
Run the health check
doctor is read-only: it never changes the project and never contacts npm. It ends with a line like "98/98 checks passed" and "0 error(s)" and exits 1 if there is any error.
In your project terminal
npx --no-install bmad-plus doctor
03
Open your AI tool in the same folder
Start a new session (or restart the tool) so that it loads its adapter file and AGENTS.md. There is no extra BMAD+ initialisation command.
04
Ask it what it knows
In the chat, not in the terminal. If it lists Atlas, Forge, Sentinel and Nexus, your tool has read the instructions. If not, check that the tool is open in the installed project, that you chose its adapter, and that AGENTS.md and .agents/skills/ exist.
Pick the smallest real thing you need. The four Core agents cover most starts: Atlas for ideas and requirements, Forge for architecture and code, Sentinel for review and tests, Nexus for plans and coordination. A good prompt gives the goal, the constraints and the output you want to review.
Use when there is no code yet, or when you want to write down the problem before changing anything.
In your AI assistant
Atlas, I want a small tool that lets our support team triage incoming issues. Ask me about the users and their daily workflow, then write a product brief with the first useful workflow and acceptance criteria I can check. Keep it to one page.
What you should get Atlas may first show its menu and wait: answer with your request, or with the menu code CB (create a product brief). It then asks questions and writes the brief under _bmad-output/; the skill chooses the file name, so read the path it reports. Read the brief as you would read a colleague’s draft: the acceptance criteria should be checkable, and anything you did not say should be marked as an assumption.
Use for a bounded change. "Quick dev" is Forge’s minimum-ceremony path; it keeps the proportionate checks and skips the full pipeline.
In your AI assistant
Forge, quick dev: add a loading state to the invoice list. Show me which files you will touch before you edit, change only those, run the existing tests that cover them and tell me exactly what you ran and what passed.
What you should get A short list of files, a small diff, and a report of the checks that really ran. If the tests could not run in the assistant’s environment, the report says so instead of claiming success.
Ask Sentinel, a different role, to check what Forge produced against the acceptance criteria. If the BMAD+ command line is available, the review can be sealed so that its verdict follows from coverage and not from tone: it lists the files it must read, quotes the code of every finding and ends with one of incomplete, findings or clean. The code review page explains the three words.
Sentinel, review this change against the acceptance criteria in the brief. Check the success path and the main failure paths. If the BMAD+ CLI is available, seal the scope with bmad-plus review scope first-change --workspace, quote the code of every finding, account for every selected file and report what bmad-plus review gate answers. Say what you could not check.
What you should get A review in _bmad-output/review/first-change/ ending with a verdict. incomplete means some file was not accounted for; findings lists what to fix, each with the quoted code; clean means no open finding within a fully covered scope, which is not a proof that the code is correct.
A new session starts with nothing. Without the Memory pack, ask the assistant for a short handoff note that you save in the project: what was done and verified, what is pending, the decisions and the next step. With the Memory pack, Zecher does this and keeps decisions, lessons and handoffs in .agents/memory/. You can add the pack later: running the installer again with --packs core,memory only adds what is missing and keeps your configuration.
In your project terminal, to add the Memory pack later
Use at the end of a working session, with the Memory pack installed. Without the pack, drop the name “Zecher” and ask your assistant, then save the note yourself.
In your AI assistant
Zecher, write a handoff for the next session. Separate what is implemented, what is tested, what is only planned, the decisions we made and why, the open questions, and the exact first step to take next. Dates in YYYY-MM-DD. Do not include secrets.
What you should get A dated note (with the Memory pack, .agents/memory/sessions/YYYY-MM-DD-<topic>.md and an updated context.md) that a cold session can read in under a minute and trust, because it separates done from planned.
By default BMAD+ only notifies. update-check reports the installed and the published versions without changing anything, and offline it says unknown rather than guessing. update-policy shows or sets whether updates are off, notify (the default) or auto (which needs an explicit version range). update with no option says "Nothing to update" when the installed version equals the package that runs it; update --latest looks at npm.
Reading the update state, offline
$ npx --no-install bmad-plus update-check --offlineInstalled: 0.23.0; running: 0.23.0; channel latest: unknownunknown: offline$ npx --no-install bmad-plus update-policyUpdate policy: notify; channel=latest; range=none; prereleases=false$ npx --no-install bmad-plus update● Installed: v0.23.0 -> Executing package: v0.23.0◆ The installed version matches this executing package. Use --latest to check the registry.└ Nothing to update.
Output captured from a real run. Source: Replayed on a test server on 2026-10-18 with the 0.23.0 source (tools/cli/bmad-plus-cli.js) in a throwaway Git project
When an update does apply, files you edited are kept and reported, a receipt and backups are written under .bmad/updates/, and update --restore <receipt-id> --yes takes it back. The team guide and the install lifecycle page cover the details.