BMADX is a lightweight BMAD-first guardrail for Codex.
It helps agentic builders choose the smallest safe workflow:
- copy tweaks stay tiny,
- normal product changes stay bounded,
- auth, billing, data, and production work escalates,
- messy repos get a rare Rescue Mode (
X4/FUBAR).
Use it when plain Codex feels too ad-hoc, but full BMAD ceremony feels too heavy for everyday work. Copy tweak != architecture ceremony. Auth change != vibe-coded one-shot.
If this matches how you use Codex/BMAD, stars and misroute reports help find early testers.
Current public version: v0.2.5
If this is your first time:
- Read START_HERE.md
- Run the install wrapper from 5-Minute Quickstart
- Paste one of the prompts from What to Paste into Codex
BMADX is easiest to judge on tasks where a coding agent can either stay useful or quietly become too clever.
| Task you give Codex | BMADX should do |
|---|---|
Fix this typo in the pricing copy. |
keep it tiny (X1) |
Add Google login without breaking existing auth. |
slow down, identify ownership and proof (X3) |
This repo is messy and I need a migration recovery plan. |
use Rescue Mode only if the entropy is real (X4/FUBAR) |
The point is not to add ceremony. The point is to stop treating copy, auth, and unclear migration recovery as the same kind of work.
Visual map
- BMADX requires BMAD for Codex. If BMAD is not installed, start there first.
- BMADX is Codex-first, not Claude Code-native.
- BMADX adds routing and guardrails; it does not prove code quality by itself.
- Model experiments such as
PMAX Xare benchmark probes, not support claims. - Tests, CI, static analysis, and human review still matter for red-zone work.
BMADX is for:
- founders, makers, designers, and PM-ish users who already use Codex
- non-technical builders who understand the problem better than the technology
- engineers who want more discipline than ad-hoc prompting
- people who want BMAD behind the scenes without running full BMAD ceremony on every bounded task
- teams that occasionally need a rescue/scaffold layer for messy repos
BMADX is probably not for you if:
- you already know you want to work directly in BMAD all the time
- you want a durable orchestration runtime with
.omx-style state and runtime tooling - you only need plain Codex for trivial one-off prompts
- you want Claude Code-native hooks, MCP, plugins, subagents, or settings automation
BMADX is intentionally Codex-first. The current product is optimized around
Codex Skills, CODEX_HOME, codex exec benchmarkability, and a compact gate
that separates classification from execution permission.
Claude Code is not a near-term target. Its Skills, CLAUDE.md, hooks,
subagents, MCP, plugins, permissions, and interactive/non-interactive behavior
make a simple BMADX port misleading. BMADX may watch Claude Code as an
execution surface, but the repo does not currently ship or promise a Claude
adapter.
Model experiments are welcome inside Codex. The benchmark runner supports the primary OpenAI/Codex path and can also run experimental local-model checks via Codex OSS providers when a local model is installed.
- Primary lane: Codex on GPT-5.5.
- Experiment lane:
PMAX X, currently focused on cheaper Ollama/OpenRouter/local candidates. - Current best PMAX X experiment:
minimax-m2.7:cloud, but it is not safe as the BMADX router yet. - Not defaults: Claude adapters, local/Ollama/OpenRouter models, and any model that fails red-zone routing.
Rule: no public model claim without the same BMADX benchmark gates for routing,
compactness, red-zone escalation, degraded BMAD behavior, and X4 rarity.
The most useful feedback is not "nice project." It is where BMADX over-escalated, under-escalated, or explained itself badly.
Try one real Codex task and report:
- what BMADX chose,
- what you expected,
- whether the result was too light or too heavy,
- what proof would convince a non-technical owner it is safe.
Feedback templates: Community Feedback
Prerequisite: BMAD must already be installed in your Codex skills. BMADX depends
on bmad-method-codex.
git clone https://github.com/pdurlej/BMADX.git
cd BMADX
python3 scripts/install_and_verify_bmadx.py --forceThen open Codex in your project and paste:
Use BMADX for this repo. Pick the lightest safe mode. Keep it lightweight unless BMAD is truly needed.
Use the Architecture Guardrail Card silently unless a risk changes the safe mode.
My task:
<describe the change in plain English>
What I care about:
<speed / clarity / safety / cleanup / shipping>
More onboarding:
Most users should not choose X1/X2/X3/X4 manually.
The intended model is:
- describe the task in plain language
- let BMADX classify it
- let BMADX stay compact for normal work
- escalate to BMAD-heavy work only when the task genuinely needs it
The internal gear model is:
X1for tiny local fixesX2for normal bounded changesX3for BMAD-heavy workX4for Rescue Mode (X4/FUBAR) when the repo or rollout needs extra structure
X4 is intentionally rare. It is the ace in the sleeve, not the default.
| Use this when... | Best fit | Why |
|---|---|---|
| you just need a trivial one-off answer | plain Codex | lowest setup and lowest ceremony |
| you want full process ownership and BMAD artifacts should drive the work | BMAD | BMAD remains the upstream source of truth |
| you want lighter day-to-day Codex usage with BMAD-compatible guardrails | BMADX | compact routing, verify discipline, rare rescue mode |
| you want a heavier runtime layer and broader orchestration | OMX | closer to that product category than BMADX |
More detail:
- Architecture Guardrail Card
- Why BMAD is required
- Choose BMAD vs BMADX vs OMX
- Ecosystem and strategic stance
- Model experiments
- FAQ
BMADX works best as part of a small, explicit stack:
- BMAD for process and architecture source of truth
- BMADX for lightest-safe-mode routing in Codex
- Oracle for second-opinion reviews with the right files and stronger models when the builder does not know what to ask
- pyfallow for Python codebase intelligence when available
- Guardrails.md for repo-local safety constraints and repeated failure lessons
- CI, tests, static analysis, and secret scans for hard technical facts
More detail: Ecosystem and strategic stance
In plain language: Oracle helps ask the expert second opinion, BMADX decides the safe work mode, BMAD owns the process, Guardrails.md remembers hard mistakes, pyfallow checks Python code structure, and CI/tests prove the result.
BMADX has a real public wedge:
- it is much lighter than OMX in the repo’s benchmarked runs
- it keeps BMAD as the source of truth instead of competing with it
- it reduces day-to-day process selection friction inside Codex
- it keeps a rare but useful Rescue Mode for messy repos
What it does not prove:
- that BMADX is categorically better than BMAD
- that token counts alone capture user value
- that every task should use BMADX instead of plain Codex
Benchmark reading:
- Benchmark Overview
- Historical benchmark summary
- Current mixed-metric summary
- GPT-5.5 benchmark summary
Human-readable proof:
Latest benchmark snapshot:
BMADX GPT-5.5 healthy(2026-04-24):6302.0average tokensBMADX GPT-5.5 degraded(2026-04-24):8918.5average tokens, with X3/X4 hard-gate semantics preservedBMADX GPT-5.4 healthy(2026-04-24comparison):12370.75average tokens- GPT-5.5 healthy passed core
format,token,reference_budget,routing, andoverreachvalidation - historical
OMXbaseline remains25540.5average tokens
Rescue Mode exists for cases where BMAD alone is not enough as a tactical operating surface inside Codex.
Typical triggers:
- the repo is messy or high-entropy
- scope is diffuse or multi-threaded
- rollout and ownership need to be made explicit
- the team needs a scaffold bundle, not just a short answer
What it generates:
AGENTS.md.customize.yamlsnippets- trigger and verify matrices
- rollout checklist
- subagent policy
More detail:
- START_HERE.md
- docs/index.md
- skill/bmadx
- scripts/install_and_verify_bmadx.py
- scripts/install_bmadx.py
- benchmark/scripts/run_bmadx_benchmark.py
- samples/fubar-bundle
Public onboarding comes first. Contributor and internal guidance lives here: