# Adapters

> The seven AI tools BMAD+ prepares: the file written for each, how a tool is detected, the shared AGENTS.md spine, and how installs and updates protect instructions you wrote yourself.

Canonical: https://bmad-plus.rochetta.fr/docs/reference/adapters/
Language: en
BMAD+ version: 0.23.1
Documentation reviewed: 2026-10-19
Author: Laurent Rochetta
License: MIT

BMAD+ documentation › [Reference](https://bmad-plus.rochetta.fr/docs/reference/) › Adapters

Each AI assistant looks for its instructions in a different file. An adapter is that file: a short generated document that tells one assistant about the agents, skills and rules BMAD+ installed. Install writes one adapter per tool you use, plus a common spine, `AGENTS.md`, so that every assistant sees the same roster and the same rules. This page is for anyone choosing `--tools`, or wondering what BMAD+ will do to an instruction file that already exists.

<a id="tools"></a>
## The seven tools

**Tools, files and detection**

| Id for `--tools` | Tool | File written | Detected when this exists | Note written for the tool |
| --- | --- | --- | --- | --- |
| `claude-code` | Claude Code | `CLAUDE.md` | `.claude` | Loads `CLAUDE.md` from the project root by itself; activate an agent by saying its name. |
| `gemini-cli` | Gemini CLI | `GEMINI.md` | `.gemini` | Loads `GEMINI.md` from the project root by itself. |
| `antigravity` | Antigravity | `GEMINI.md` (shared with Gemini CLI) | `.gemini/antigravity` | Reads the same file; the note adds a concurrency rule: coordinate with other agentic tools and never edit the same files at the same time. |
| `cursor` | Cursor | `.cursor/rules/bmad-plus.mdc` | `.cursor` | A rule with `alwaysApply: true` in its header, so Cursor always loads it; the spine stays the source of truth. |
| `codex-cli` | Codex CLI | `.codex/AGENTS.md` | `.codex` | Follows the open AGENTS.md convention; the file relays to the root spine, which is better read directly when both exist. |
| `opencode` | OpenCode | `.opencode/AGENTS.md` | `.opencode` | Same as Codex CLI. |
| `aider` | Aider | `CONVENTIONS.md` | `.aider.conf.yml` | Aider does not load convention files by itself: add `read: CONVENTIONS.md` to `.aider.conf.yml`, or run `/read CONVENTIONS.md` in the session. |

Gemini CLI and Antigravity point at the same `GEMINI.md`. When both are selected, one file is written and it is titled for both. Detection is a simple check that the marker exists in the project folder; it says nothing about whether the tool is installed on the machine.

<a id="choosing"></a>
## Choosing tools at install

**How --tools and the wizard decide**

| You pass | Result |
| --- | --- |
| nothing, interactive | Tools whose marker is found are selected. If none is found, the wizard asks which tools you use. |
| nothing, with `--yes` | Detected tools only. With none detected, no adapter is written and the installer says: `No AI tool detected; no instruction adapter written. Re-run with --tools <ids> or --tools all to add one.` |
| `--tools claude-code,cursor` | Exactly these. The list is comma separated. |
| `--tools all` | All seven. |
| `--tools none` (or `skip`) | No adapter is written and existing instruction files are left alone. The agents and skills are still installed. |
| an unknown id | The command stops before writing anything: “Unknown tool ID(s): … Available: claude-code, gemini-cli, antigravity, cursor, codex-cli, opencode, aider, all, none.” |

Running `install` again keeps the tools this installation already owns, whatever you pass now, unless you pass `--tools none`. So adding a tool never drops another one.

**A real install that prepares Claude Code**

```text
$ npx bmad-plus install --yes --lang fr --packs core,design --tools claude-code --directory .\demo-app
•  IDE détectés: Claude Code
o  ✅ 5 agents, 9 skills, 4 fichiers copiés
o  ✅ 1 IDE configuré(s)
```

Output captured from a real run. Source: Captured during the 0.23.0 acceptance run, 2026-10-18 (step 1; installer run in French)

<a id="files"></a>
## What is inside the files

`AGENTS.md` is the spine. It is written whenever at least one tool is selected, and it carries everything: the project context, the roster of agents (with the skills each one drives), the skills folder and auto-activation file, your name and language, the update instructions, the registry facts (pack and agent counts, data-handling flows, cohabitation notes) and the key chat commands. The memory rules (the four guardrails and the four `.agents/memory` files) are added only when the Memory pack is installed. Each tool file starts with a link to the spine and the tool note from the table, then repeats the same sections, because many tools load only their own file.

**Two lines of a generated AGENTS.md**

```text
$ Select-String -Path .\demo-app\AGENTS.md -Pattern 'Atelier','Cohabitation'
demo-app\AGENTS.md:22:- **Atelier** (Design Engine) — Senior product designer and design engineer: surfaces, tokens, accessibility, audits, redesigns (Design) — drives: design, design-review, redesign
demo-app\AGENTS.md:54:- Cohabitation (Design): Overlaps Sentinel's UX-review role and Dev Studio's Rachel (UX Designer); when this pack is installed its rules govern visual design and accessibility, and the others hand those over.
# Long lines were wrapped by the terminal in the recorded run; they are shown joined here.
```

Output captured from a real run. Source: Captured during the 0.23.0 acceptance run, 2026-10-18 (step 3; Select-String on the AGENTS.md of the demo-app folder)

Every generated file carries the markers `AUTO-GENERATED by tools/build/generate-adapters.js — DO NOT EDIT.` and `BMAD+ installed project configuration`. These markers are how BMAD+ later recognises a file as its own. The Cursor rule starts with its YAML header (`description`, `alwaysApply: true`), so the markers come right after it.

<a id="ownership"></a>
## What happens to a file that already exists

Install records a fingerprint of each adapter it writes (the file’s content hash, line endings normalised). That fingerprint, kept in the install manifest, is how BMAD+ tells its own untouched file from one you edited.

**Behaviour by situation**

| The file at the target path is… | install | update |
| --- | --- | --- |
| missing | Written. | Written. |
| BMAD+’s own, identical to what would be written | Left as is. | Left as is. |
| BMAD+’s own, untouched since install | Refreshed. | Refreshed, and the new fingerprint recorded. |
| BMAD+’s own, but you edited it | Preserved. Warning: `<file>: existing project instructions preserved.` | Preserved and listed as a conflict (reason `local-instructions`). |
| written by you, without BMAD+ markers (interactive run) | Preserved, with the same warning. | Preserved, even with `--yes`. |
| written by you, without BMAD+ markers, with `install --yes` | Copied to `<file>.bak` first, then replaced. An existing `.bak` is never overwritten: the next copy is `.bak.1`, then `.bak.2`. | — |
| left by an older BMAD+ installer | Backed up to `.bak`, then refreshed: `<file>: backed up to <file>.bak before refreshing.` | Same: backed up, then migrated. |
| the generated file of a BMAD+ source checkout (generator marker, no install marker) | Preserved, with a hint on how to compare it with the package defaults. | Preserved, reason `repository-adopted`. |

> **Warning · install --yes replaces an instruction file you wrote** Unattended installs cannot ask, so they make a `.bak` copy and write the BMAD+ version. If your own `CLAUDE.md` matters, either run `install` interactively once, or pass `--tools none` and merge the generated content yourself. `update` never does this: it always preserves a file it does not own.

`doctor` reports the state of each adapter as `Instruction file: <state>.` with the states `unchanged` (pass), `modified`, `unowned` or `adopted` (warnings), and `missing` or `unreadable` (errors). `uninstall` removes an adapter only when it still carries the install marker and its content hash matches the recorded one; a file you edited stays.

<a id="limits"></a>
## What an adapter does not do

- It is text for the assistant to read. BMAD+ installs no hook and no extension in any of these tools: the registry records the integration as host-managed, with lifecycle events not integrated.
- It is model-agnostic by contract: Claude, GPT, Gemini and local models are all supported, because the content is plain instructions.
- It does not make the assistant run `bmad-help`, `autopilot` or `parallel`: those are phrases you say in the chat.
- It tells the assistant to check for a new release once per session with `npx --no-install bmad-plus update-check --json`, and to apply one only as your update policy allows. That form runs only a local copy: add it once with `npm install --save-dev bmad-plus`, or use `npx bmad-plus update-check --json`.

<a id="examples"></a>
## Examples

<a id="example-cli-adapters-add-cursor"></a>
### Add Cursor to a project that already uses Claude Code

BMAD+ is installed with `claude-code`. A colleague works in Cursor and needs the same agents.

**In your AI assistant**

```text
Add Cursor to this project’s BMAD+ install without touching the Claude Code setup: run `npx bmad-plus install --yes --tools cursor`, then tell me which files changed.
```

**What you should get** `--yes` is needed when the assistant runs the command, because without a terminal the installer refuses to start; a run in your own terminal would first ask for the language, the packs and your name. The installer keeps `claude-code` (tools already owned are retained) and writes `.cursor/rules/bmad-plus.mdc` with `alwaysApply: true` and a link back to `AGENTS.md`. `CLAUDE.md` and `AGENTS.md` are rewritten only if their generated content differs; a copy you edited is preserved with the “existing project instructions preserved” warning. The manifest now lists both tools.

<a id="example-cli-adapters-edited-claude-md"></a>
### You added your own rules to CLAUDE.md

You appended team conventions at the bottom of the generated `CLAUDE.md`, then a new BMAD+ version comes out.

**In your AI assistant**

```text
Update BMAD+ in this project with `npx bmad-plus update --latest --yes`, and list every file the update preserved instead of replacing.
```

**What you should get** The plan prints “CLAUDE.md: preserved (local-instructions).” and the receipt records it as a conflict; the update then finishes with “applied partially.” Your additions are untouched. To adopt the new generated text, merge by hand or restore the original and edit again.

**See also**

- [install and its --tools flag](https://bmad-plus.rochetta.fr/docs/reference/cli-install/)
- [update: how conflicts are preserved](https://bmad-plus.rochetta.fr/docs/reference/cli-update/)
- [doctor: adapter states](https://bmad-plus.rochetta.fr/docs/reference/cli-doctor/)
- [uninstall](https://bmad-plus.rochetta.fr/docs/reference/cli-uninstall/)
- [Project layout](https://bmad-plus.rochetta.fr/docs/reference/project-layout/)

[BMAD+ documentation](https://bmad-plus.rochetta.fr/docs/) · [Reference](https://bmad-plus.rochetta.fr/docs/reference/)

[Source on GitHub](https://github.com/lrochetta/BMAD-PLUS)