Invisible orchestrator layer for BMAD-METHOD™
npm install bmad-invisible

Building software with AI should be simple. Instead, it's overwhelming.
You have an idea. You open Claude, ChatGPT, or Codex. Then what?
- Do you write a Product Requirements Document first?
- Should you create user stories?
- What about technical architecture?
- How do you break work into manageable pieces?
- Where do you even start?
Most developers waste hours figuring out _how_ to ask AI for help instead of actually building their project.
Meanwhile, professional teams use structured agile methodologies (analyst → PM → architect → developer → QA) that produce better results. But learning these frameworks takes weeks and adds friction you don't need.
BMAD-Invisible gives you professional agile workflows through natural conversation.
Just talk about your project. The system:
✅ Understands what you're trying to build (no framework jargon needed)
✅ Generates professional deliverables automatically (PRD, architecture, user stories)
✅ Guides you through proven development phases (analyst → PM → architect → dev → QA)
✅ Adapts to complexity (quick templates for simple tasks, full workflows for complex features)
You focus on your ideas. BMAD-Invisible handles the methodology.
- Zero learning curve - Chat naturally, no methodology training required
- Proven framework - Built on BMAD-METHOD™, a battle-tested agile AI development process
- Intelligent routing - Automatically picks the right approach for each task
- Professional output - Generates documentation that matches industry standards
- Local-first - Works with Claude CLI, Codex CLI, or OpenCode - your choice
- No API costs - Runs through your existing CLI tooling
BMAD-Invisible intelligently routes tasks between two development approaches:
- Complex Lane: Full multi-agent BMAD workflow for substantial features
- Quick Lane: Template-based rapid development for small, focused tasks
The orchestrator automatically selects the appropriate lane based on task complexity. Simple typos and config changes go through the fast Quick lane, while complex features get the full BMAD treatment. Both lanes output to the same docs/ folder - the only difference is _how_ the artifacts are generated.
→ See DUAL_LANE_ORCHESTRATION.md for details
- Node.js ≥ 20.10.0
- npm ≥ 9.0.0
- At least one chat CLI installed locally:
- OpenAI Codex CLI
- Claude CLI
- OpenCode CLI
#### Option 1: NPX One-Command Setup (Easiest!)
``bash`Just run this - it does everything!
npx bmad-invisible@latest start
> Prefer a specific CLI? Append --assistant=claude, --assistant=codex, or --assistant=opencode to skip the prompt. Add --glm--llm-provider=glm
> (or the explicit ) to swap the orchestrator to ZhipuAI's GLM using the ZHIPUAI_API_KEY/GLM_API_KEY--anthropic
> credentials. Use (or --llm-provider=claude) anytime you want to switch back to the Anthropic defaults.
That's it! This command will:
- Create project structure
- Install all dependencies
- Prompt you to choose between Claude, Codex, or OpenCode
- Launch the selected chat interface
> UI Tooling Opt-in: If you enable the optional shadcn UI helpers during the
> wizard, the installer also writes a components.json in your project root.style
> This file follows the shadcn/ui schema
> (, tailwind, aliases, etc.) so downstream tooling likenpx shadcn@latest add button
> can pick up your preferences without extra
> prompts.
> 💡 Tip: Always use @latest to ensure you get the newest version!
#### Option 1b: NPX Step-by-Step
`bashInitialize in your project directory
npx bmad-invisible@latest init
`
#### Option 2: Global Installation
`bashInstall globally
npm install -g bmad-invisible
`
#### Option 3: Local Development
`bashClone the repository
git clone https://github.com/bacoco/BMAD-invisible.git
cd BMAD-invisible
> MCP assets are prebuilt: The published package already includes
dist/mcp, so installs without dev dependencies (for example on Windows or production hosts) can skip rebuilding during npm install. The optional postinstall step only re-runs the TypeScript build when typescript is available.> Note: This uses the Model Context Protocol (MCP) so you can work locally without managing API keys.
#### Choosing Your LLM Provider (GLM vs Anthropic)
- Run any CLI command with
--glm (or the explicit --llm-provider=glm) to switch the orchestrator to ZhipuAI's GLM stack.
- Provide credentials via environment variables – ZHIPUAI_API_KEY is preferred, but GLM_API_KEY is also detected automatically.
- Optional model overrides can be set with --llm-model= or by exporting LLM_MODEL.
- Persist defaults in a .env file at your project root:
`bash
# .env
LLM_PROVIDER=glm
ZHIPUAI_API_KEY=sk-...
LLM_MODEL=glm-4-plus # Optional custom model
`- To switch back to Anthropic at any time, pass
--anthropic on the CLI or set LLM_PROVIDER=claude in your environment.
- The launcher never mutates your shell environment; overrides are injected only into the spawned CLI process.#### Codex CLI Integration
Interactive installs now auto-provision Codex CLI so you can run
codex immediately after setup:- Generates/updates
AGENTS.md with BMAD agent context for Codex memory.
- Ensures ~/.codex/config.toml exists with the bmad_invisible MCP server
entry plus optional helpers for chrome-devtools and shadcn (disabled by
default until you install them).
- Applies sensible defaults (GPT-5-Codex model, medium reasoning, automatic approvals) unless you have overrides.Non-interactive environments (like CI) skip the global config step, but you can review and customize the defaults via
codex-config.toml.example.> MCP Config Formats at a Glance
>
> - Claude / Claude Code reads
.claude/mcp-config.json. Entries are JSON
> objects keyed by server name, and optional servers such as
> chrome-devtools and shadcn simply set disabled: true until you toggle
> them on.
> - Codex CLI reads ~/.codex/config.toml. Each MCP server is declared in a
> TOML table ([mcp_servers.bmad_invisible], [mcp_servers.chrome_devtools],
> etc.) with auto_start flags mirroring the JSON disabled switches.📖 How It Works
$3
`
User: "I want to build an app"
↓
[Analyst Phase - Hidden]
↓
Assistant: "What problem are you trying to solve?"
↓
[Gathers requirements through conversation]
↓
Assistant: "Here's what I understand... [shows summary]"
↓
User: validates or iterates
↓
[PM Phase - Hidden]
↓
Assistant: "Here's the development plan..."
↓
[Architecture Phase - Hidden]
↓
Assistant: "Here's the technical approach..."
↓
[Continues through all phases invisibly]
`💡 Usage Examples
Run
npm run bmad to be prompted for your choice, or use explicit commands (npm run bmad:claude, npm run bmad:codex, npm run bmad:opencode). The experience looks like this:$3
``bash
$ npm run bmad
Which assistant should we launch? (Claude / Codex / Opencode): claude🎯 Starting BMAD Invisible Orchestrator...
📡 MCP Server: bmad-invisible-orchestrator
🤖 Agent: Invisible BMAD Orchestrator
💬 Type your project idea to begin!
Welcome! I'm here to help you build your project.
What would you like to create?
> I need an app for tracking family chores
Great! Let's figure this out together.
Who will be using this app?
> Parents and kids, ages 8 and up
Perfect. What does success look like?
> Everyone knows their tasks and chores actually get done
Makes sense. Any constraints I should know about?
(Budget, timeline, technical preferences?)
> Need it in 3 months, prefer mobile-first
📋 Let me summarize what I understand:
Project: Family Chore Tracking App
Users: Parents & children (8+)
Goal: Clear task visibility and completion
Timeline: 3 months
Platform: Mobile-first
Is this correct? (y/n/edit)
> y
Perfect! Based on this, here's a 12-week development plan:
Phase 1 (Weeks 1-4): Core Features
- Task creation and assignment
- User profiles (parent/child roles)
- Basic completion tracking
Phase 2 (Weeks 5-8): Engagement
- Reward points system
- Notifications
- Progress visualization
Phase 3 (Weeks 9-12): Polish
- Testing and refinement
- Performance optimization
- User onboarding flow
Does this approach work for you? (y/n/modify)
> y
Excellent! Now for the technical approach.
Recommended Stack:
- Mobile: React Native (iOS + Android from one codebase)
- Backend: Firebase (real-time sync, authentication)
- Database: Firestore (flexible, scalable)
- Hosting: Firebase Hosting
Why this stack?
- Faster development (built-in features)
- Real-time updates (perfect for family coordination)
- Lower cost to start
- Easy to scale later
Sound good, or prefer something else? (y/n/modify)
> Sounds perfect
Great! Let me break this into specific tasks.
Epic 1: Task Management (3-4 weeks)
Story 1.1: Create and edit tasks ← Let's start here
Story 1.2: Assign tasks to family members
Story 1.3: Mark tasks complete
Epic 2: User System (2-3 weeks)
Story 2.1: Family member profiles
Story 2.2: Parent/child permissions
Epic 3: Rewards (2 weeks)
Story 3.1: Point tracking
Story 3.2: Rewards redemption
Ready to start with Story 1.1? (y/n)
> y
Perfect! Here's your first feature to build:
Story 1.1: Create and Edit Tasks
What users can do:
- Tap "+" to create new task
- Enter: task name, description, points (1-5)
- Optionally set due date
- Save and see task in list immediately
Technical Implementation:
1. Component:
TaskForm.jsx
`javascript
// Key fields
- taskName (required)
- description (optional)
- points (1-5, default: 3)
- dueDate (optional)
``2. Firestore Structure:
`javascript
tasks/{taskId}
{
name: string,
description: string,
points: number,
dueDate: timestamp,
createdBy: userId,
assignedTo: userId,
status: 'pending' | 'in-progress' | 'complete',
createdAt: timestamp
}
`3. Implementation Steps:
- [ ] Create TaskForm component
- [ ] Add form validation
- [ ] Implement Firestore write
- [ ] Add real-time listener
- [ ] Show success/error feedback
Acceptance Criteria:
- ✓ Can create task with all fields
- ✓ Task appears instantly in list
- ✓ Empty names are prevented
- ✓ Handles offline gracefully
Testing:
- Create task with all fields → appears in list
- Try empty name → shows validation error
- Create while offline → syncs when back online
Want the complete code examples or ready to implement? (code/ready)
> ready
Awesome! When you're done, let me know and I'll help you:
- Review the implementation
- Add tests
- Move to the next story
Type 'done' when ready for review, or 'help' if you get stuck.
``$3
`bash
$ npx bmad-invisible chat --project ./my-appI see you have an existing project. What would you like to add?
> I need to add push notifications
Perfect! Let me understand what you need.
What should trigger these notifications?
> When a task is assigned or due soon
Great. Who should receive them?
> The person assigned to the task
Makes sense. Any preferences on implementation?
> Use Firebase Cloud Messaging
📋 Here's what I'll help you build:
Feature: Push Notifications
Triggers:
- Task assigned to user
- Task due in 24 hours
Recipients: Assigned user only
Technology: Firebase Cloud Messaging (FCM)
Correct? (y/n)
> y
Perfect! This will integrate with your existing Firebase setup.
Story: Push Notifications for Tasks
Implementation Plan:
1. FCM Setup (30 minutes)
- Add FCM to React Native
- Request notification permissions
- Store device tokens in Firestore
2. Cloud Function Triggers (1 hour)
- Trigger on task assignment
- Trigger on approaching due date
- Send to user's registered devices
3. In-App Handling (30 minutes)
- Handle notification tap
- Navigate to task details
- Update UI accordingly
Files to Modify:
-
src/services/notifications.js (new)
- functions/index.js (add triggers)
- src/screens/TaskList.jsx (handle taps)
- app.json (FCM config)Want detailed code for each step? (y/n)
> y
[Provides step-by-step implementation with code examples]
Once you're done, I'll help you test it thoroughly!
``⚙️ Configuration
$3
BMAD-Invisible supports routing requests through GLM (or other Anthropic-compatible) endpoints. This allows you to use alternative LLM providers while maintaining compatibility with Claude, Codex, and OpenCode CLIs.
#### Environment Variables
Set
BMAD_ASSISTANT_PROVIDER=glm to enable GLM routing. The system will automatically configure the environment for Anthropic-compatible GLM endpoints.GLM Configuration Priority (first available value is used):
| Variable | Priority | Description |
| ---------------------- | -------- | ---------------------------------------- |
|
BMAD_GLM_BASE_URL | 1 | GLM API base URL (BMAD-specific) |
| GLM_BASE_URL | 2 | GLM API base URL (standard) |
| ANTHROPIC_BASE_URL | 3 | Anthropic base URL (fallback) |
| BMAD_GLM_AUTH_TOKEN | 1 | GLM authentication token (BMAD-specific) |
| GLM_AUTH_TOKEN | 2 | GLM authentication token (standard) |
| ANTHROPIC_AUTH_TOKEN | 3 | Anthropic auth token (fallback) |
| BMAD_GLM_API_KEY | 1 | GLM API key (BMAD-specific) |
| GLM_API_KEY | 2 | GLM API key (standard) |
| ANTHROPIC_API_KEY | 3 | Anthropic API key (fallback) |Note: At least one of
_BASE_URL or _API_KEY must be set when using GLM mode.When no GLM base URL variables are provided, requests default to
https://open.bigmodel.cn/api/paas/v4/chat/completions. Custom
base URLs may include schemes, ports, and nested paths (e.g., https://example.com:7443/custom/base), and the client will append
the /api/paas/v4/chat/completions endpoint automatically.#### Usage Example
`bash
Set GLM provider and credentials
export BMAD_ASSISTANT_PROVIDER=glm
export BMAD_GLM_BASE_URL=https://your-glm-endpoint.com
export BMAD_GLM_API_KEY=your-api-keyStart BMAD with GLM routing
npm run bmad:claude
Output: 🌐 GLM mode active: routing Claude CLI through configured GLM endpoint.
`GLM routing works with all three assistant CLIs:
-
npm run bmad:claude - Routes Claude CLI through GLM
- npm run bmad:codex - Routes Codex CLI through GLM
- npm run bmad:opencode - Routes OpenCode CLI through GLM🛠️ Current Status
FULLY IMPLEMENTED AND PRODUCTION-READY ✅
BMAD-invisible v1.2 is a complete, working system that combines:
- Full BMAD methodology integration (Complex lane)
- Template-based rapid development (Quick lane)
- Intelligent automatic routing
- Professional deliverable generation
- Natural conversational interface
$3
✅ MCP-based orchestration with 10 tools
✅ Dual-lane routing - automatic complexity detection
✅ BMAD integration - full agent/template/task support
✅ Quick lane - template-based generation (2-3 min)
✅ Quick lane graceful fallback - automatically routes to complex lane if disabled
✅ Complex lane - complete BMAD workflow (10-15 min)
✅ Deliverable generation - PRD, architecture, stories
✅ State persistence - resume anytime
✅ CLI interface -
npm run codex
✅ Zero API costs - powered by local OpenAI Codex CLI session🏗️ Architecture
$3
`
bmad-invisible/
├── agents/ # Agent definitions
│ ├── invisible-orchestrator.md # Main conversational interface
│ └── phase-detector.md # Phase classification engine
├── commands/ # Phase-specific commands
│ ├── auto-analyze.md # Analyst phase execution
│ ├── auto-plan.md # PM phase execution
│ ├── auto-architect.md # Architecture phase execution
│ ├── auto-stories.md # Story breakdown phase
│ ├── auto-dev.md # Development guidance phase
│ ├── auto-qa.md # Quality assurance phase
│ ├── auto-ux.md # UX refinement phase
│ └── auto-po.md # Product owner review phase
├── hooks/ # Phase management
│ ├── phase-transition.js # Handles phase transitions
│ └── context-preservation.js # Maintains context across phases
├── mcp/ # Model Context Protocol server
│ └── server.ts # StdIO entry point → shared runtime
├── src/mcp-server/ # Shared runtime + Codex bridge
│ ├── runtime.ts # Orchestrator wiring
│ └── codex-server.ts # Codex-aware entry point (routing & approvals)
└── test/ # Test suite
├── phase-detector.contract.test.js
└── phase-transition.safety.test.js
`$3
1. Analyst: Understand problem, users, goals
2. PM: Create plan, timeline, milestones
3. Architect: Design technical approach
4. SM: Break into epics and stories
5. Dev: Implementation guidance
6. QA: Testing and validation
7. UX: Usability refinement
8. PO: Final review and launch
All phases execute invisibly based on conversation context.
🏗️ Architecture
$3
`
User → Codex CLI → MCP Server → BMAD Agents → Deliverables
↓
Project State
Phase Detection
Context Preservation
`Key Components:
- MCP Server (
mcp/server.ts) - 10 orchestration tools
- Project State (lib/project-state.js) - Conversation & state tracking
- BMAD Bridge (lib/bmad-bridge.js) - Integration with BMAD agents
- Deliverable Generator (lib/deliverable-generator.js) - Creates docs automaticallyLow API Overhead - Runs through your local CLI tooling. ZhipuAI's GLM only needs
ZHIPUAI_API_KEY/GLM_API_KEY; Anthropic
defaults continue to work via the Claude CLI with no direct API billing.🔧 Development Setup
`bash
Install dependencies
npm installBuild MCP server
npm run build:mcpRun tests
npm testStart standalone MCP server (optional)
npm run mcp
`$3
Register the Codex-aware MCP server with
npx bmad-invisible-codex in your ~/.codex/config.toml:`toml
[[mcp]]
id = "bmad-invisible-codex"
command = "npx"
args = ["bmad-invisible-codex"]
autostart = true [mcp.env]
# Optional: enforce guarded writes and approve individual operations
CODEX_APPROVAL_MODE = "true"
CODEX_APPROVED_OPERATIONS = "generate_deliverable:prd,execute_quick_lane"
# Optional: override LLM routing per lane
CODEX_QUICK_MODEL = "gpt-4.1-mini"
CODEX_COMPLEX_MODEL = "claude-3-5-sonnet-20241022"
# Observability knobs (JSON logs + optional metrics)
CODEX_LOG_CONTEXT = '{"environment":"local"}'
CODEX_METRICS_STDOUT = "true"
`codex-config.toml.example for a ready-to-copy snippet and additional options.#### Observability & metrics
- Structured JSON logs — The MCP server and Codex bridge now emit newline-delimited JSON to
stderr. Every entry contains the event msg, timestamp, and metadata such as lane, confidence, operation, and measured durationMs so you can trace lane selection, approvals, and tool execution.
- Context enrichment — Provide a JSON blob via CODEX_LOG_CONTEXT to stamp shared fields (e.g., environment, cluster, team) onto every log entry without code changes.
- Lightweight metrics — Set CODEX_METRICS_STDOUT=1 to mirror timing metrics (lane selection, workflow durations, tool runtimes) to stdout as JSON events. The helper supports adding additional sinks if you need to forward metrics to a collector.Example log line:
`json
{
"ts": "2024-07-16T12:34:56.789Z",
"level": "info",
"msg": "lane_selection_completed",
"service": "bmad-codex",
"component": "mcp-orchestrator",
"operation": "execute_workflow",
"lane": "quick",
"confidence": 0.88,
"durationMs": 142.3,
"environment": "local"
}
`🔌 MCP Management System
BMAD-invisible includes a comprehensive Model Context Protocol (MCP) management system for seamless AI tool integration.
$3
- 🔍 Interactive CLI - Manage MCP servers with simple commands
- 📦 Registry Integration - 15+ official MCP servers (filesystem, github, postgres, puppeteer, etc.)
- 🌍 Environment Profiles - Separate dev/staging/prod configurations
- 🔒 Secure Storage - Encrypted credentials with keychain integration
- 💬 Conversational Setup - Install tools through natural conversation
- 🏥 Health Monitoring - Diagnostics and automatic troubleshooting
$3
`bash
Browse available MCP servers
npm run mcp:browseInstall a server (e.g., filesystem access)
npm run mcp:install filesystemList configured servers
npm run mcp:listHealth check
npm run mcp:doctorManage profiles
npm run mcp:profile:list
npm run mcp:profile:create devSecurity
npm run mcp:secure # Migrate to encrypted storage
npm run mcp:audit # Run security audit
`$3
The invisible orchestrator can install MCP tools naturally:
`
You: "I need database access"
Assistant: I can help with that! Would you like PostgreSQL or SQLite?You: "PostgreSQL"
Assistant: ✓ PostgreSQL MCP server configured and ready!
`📖 Complete Guide: See docs/mcp-management.md for:
- Detailed command reference
- Environment profiles guide
- Security best practices
- Troubleshooting
- API documentation
📚 Documentation
- QUICKSTART.md - ⭐ Start here! Quick installation and first use
- docs/mcp-management.md - 🆕 Complete MCP management guide
- USAGE.md - Complete usage guide with examples
- DUAL_LANE_ORCHESTRATION.md - 🆕 Intelligent routing system
- IMPLEMENTATION_COMPLETE.md - Complete feature list
- CLAUDE.md - Guide for Claude Code development
- BMAD-METHOD™ - Core framework
✅ Current Status
FULLY IMPLEMENTED AND WORKING!
$3
✅ MCP-based orchestration with 10 tools
✅ Codex CLI integration (no API costs)
✅ Natural conversation interface
✅ Phase detection and transitions
✅ Deliverable generation (PRD, architecture, stories)
✅ Project state persistence
✅ User validation checkpoints
✅ Full BMAD agent integration
✅ Quick lane gracefully disables and defers to complex lane when unavailable
$3
`bash
Start conversation (prompts for assistant choice)
npm run bmadNatural conversation
> I want to add user authenticationSystem understands context, generates artifacts
No need to know about PRDs, architectures, stories, etc.
`$3
`
my-project/
├── docs/
│ ├── brief.md # From analyst phase
│ ├── prd.md # From PM phase
│ ├── architecture.md # From architect phase
│ ├── epics/
│ │ └── epic-1-auth.md # From SM phase
│ └── stories/
│ ├── story-1-1-login.md # From SM phase
│ └── story-1-2-signup.md
└── .bmad-invisible/
├── state.json # Current phase, context
└── conversation.log # Full conversation history
`$3
After each major phase:
`
Assistant: "Here's what I've created... [summary]"
"Does this look good?"Options:
- y: Continue to next phase
- n: Let me refine this
- edit: Make specific changes
- back: Go to previous phase
`🚀 Future Enhancements
While fully functional, potential improvements include:
Short Term:
- Additional test coverage
- More example workflows
- Custom template support
Medium Term:
- Web UI for non-CLI users
- Multi-project management
- Team collaboration features
Long Term:
- Git integration hooks
- CI/CD pipeline generation
- Analytics dashboard
🤝 Contributing
We welcome contributions! BMAD-invisible is production-ready but can always be enhanced.
Key areas for contribution:
- Additional lane selector test cases
- Custom template variations
- Integration examples
- Performance optimizations
- Documentation improvements
See CONTRIBUTING.md for guidelines.
🔗 Related Projects
- BMAD-METHOD™ - The core framework
- Model Context Protocol - State persistence layer
📄 License
MIT License - see LICENSE for details.
🙏 Acknowledgments
Built on BMAD-METHOD™ by Brian (BMad) Madison.
BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC.
---
Current Version: v1.3.5 - Production Ready ✅
Get Started:
npx bmad-invisible@latest start`Questions? Open an issue or check the main BMAD repository.
Making AI-assisted development accessible to everyone through natural conversation