🚀 BMAD Method for Claude Code

Automatically enhance your Claude Code prompts with specialized AI personas using the BMAD (Be My AI Developer) Method. This system uses Gemini AI to intelligently select the best persona for each task, improving response quality and relevance without requiring users to know specific commands.

✨ Features

• 🤖 AI-Powered Selection: Uses Gemini AI to intelligently select the best BMAD persona
• 🎯 No Commands Needed: Users don't need to know exact BMAD commands - AI handles it
• 🔧 10 Specialized Personas: From Senior Developer to Security Expert, each with unique expertise
• ⚡ Smart Enhancement: Context-aware prompt processing powered by Gemini 2.5 Pro
• 🔌 Seamless Integration: Works transparently with Claude Code via hooks
• 🛠️ Automatic Setup: Installer handles Gemini CLI and API key configuration
• 📊 MCP Server Support: Optional advanced features via Model Context Protocol

🎭 Available Personas

Persona	Command	Specialization
Senior Developer	/dev	Coding, debugging, implementation
Code Reviewer	/review	Quality assessment, security analysis
Software Architect	/architect	System design, architecture patterns
DevOps Engineer	/devops	Deployment, CI/CD, infrastructure
Data Analyst	/analyze	Data analysis, visualization, insights
Business Analyst	/business	Requirements, PRDs, specifications
Technical Writer	/doc	Documentation, guides, tutorials
Security Expert	/security	Security assessment, vulnerabilities
Problem Solver	/solve	Troubleshooting, general solutions
Creative Writer	/write	Content creation, storytelling

📋 Prerequisites

• Claude Code CLI (required)
• Node.js 18+ (required for Gemini CLI)
• Gemini API Key (free tier available)

🚀 Quick Start

One-Line Installation

curl -sSL https://raw.githubusercontent.com/wolverin0/bmad-claude/main/install.sh | bash

Or with wget:

wget -qO- https://raw.githubusercontent.com/wolverin0/bmad-claude/main/install.sh | bash

The installer will:

1. Check and install Gemini CLI if missing
2. Guide you through getting a free Gemini API key
3. Configure everything automatically

Manual Installation

1. Clone the repository

git clone https://github.com/wolverin0/bmad-claude.git
cd bmad-claude

2. Set up environment (required)

cp .env.example .env
# The installer will guide you through adding your Gemini API key

3. Run the installer

./install.sh

4. Restart Claude Code to activate hooks

🧪 Test the Installation

Quick Test

# Test hook functionality
./test-installation.sh

# Test Gemini integration
echo '{"prompt": "Create a REST API for user management"}' | python3 ~/.claude/hooks/bmad_gemini_hook.py

You should see Gemini AI selecting the appropriate persona in the debug output.

📖 Usage

Automatic Enhancement (Recommended)

Just use Claude Code normally! Gemini AI automatically selects the best BMAD persona:

# Your prompts are automatically enhanced by AI
claude "Build a authentication system"
# → Gemini AI selects the most appropriate persona

claude "Write unit tests for the user service"  
# → Gemini AI analyzes context and applies best persona

claude "create a deployment pipeline for AWS"
# → Gemini AI recognizes DevOps context automatically

No need to remember commands - Gemini AI understands your intent!

Manual CLI Tools

For explicit control, use the provided CLI tools:

# Get persona suggestion only
bmad-suggest "Create deployment pipeline"

# Force specific persona
bmad-dev "Implement caching layer"
bmad-review "Check this PR"

# Full enhancement + execution
bmad-claude "Analyze user engagement metrics"

🔧 Configuration

Environment Variables

The system requires a Gemini API key to function (free tier available):

1. Get your free API key:

   • Visit: https://makersuite.google.com/app/apikey
   • Click "Create API Key"
   • Copy the generated key

2. Configure during installation: The installer will prompt you for the key, or manually add it:

   cp .env.example .env
   # Edit .env and replace placeholder with your key

3. Verify configuration:

   # Test Gemini connection
   GEMINI_API_KEY=$(grep "GEMINI_API_KEY=" .env | cut -d'=' -f2) gemini -p "Hello"

Settings Location

• Environment config: .env (create from .env.example)
• Project hooks: .claude/settings.json
• Global hooks: ~/.claude/CLAUDE.md
• Hook scripts: .claude/hooks/

How It Works

The system uses Gemini AI to analyze your prompts and select personas:

1. Prompt Analysis: Your input is sent to Gemini 2.5 Pro
2. Intent Recognition: AI understands the task context and requirements
3. Persona Selection: AI picks the most appropriate BMAD persona
4. Enhancement: Your prompt is enriched with persona-specific context

To customize the AI behavior, modify the Gemini prompt in .claude/hooks/bmad_gemini_hook.py.

🏗️ Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   User      │────▶│ Claude Code  │────▶│    Hook     │
│  Prompt     │     │              │     │  System     │
└─────────────┘     └──────────────┘     └─────────────┘
                            │                     │
                            ▼                     ▼
                    ┌──────────────┐     ┌─────────────┐
                    │   Enhanced   │◀────│   Persona   │
                    │   Prompt     │     │  Selector   │
                    └──────────────┘     └─────────────┘

🧪 Development

Running Tests

# Run all tests
./run-tests.sh

# Test specific component
python3 -m pytest tests/test_persona_selection.py

# Test hook integration
./test-hooks.sh

Building from Source

# Install dependencies
npm install
pip install -r requirements.txt

# Build MCP server (optional)
cd bmad-mcp-server
npm run build

🐛 Troubleshooting

Hook Not Working?

1. Check registration:

   # In Claude Code
   /hooks

2. Verify installation:

   ./verify-installation.sh

3. Check logs:

   tail -f ~/.claude/logs/hooks.log

Common Issues

Issue	Solution
"No hooks registered"	Restart Claude Code, check .claude/settings.json
"Command not found"	Run source ~/.bashrc or open new terminal
"Permission denied"	Run chmod +x ~/.claude/hooks/*.py
Spaces in path	Use symlinks or move to path without spaces

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

📝 License

This project is licensed under the MIT License - see LICENSE file for details.

🙏 Acknowledgments

• BMAD Method for persona concepts
• Claude Code team for the amazing IDE
• MCP SDK for advanced integrations

📊 Stats

• Installation Time: ~1 minute (includes Gemini CLI if needed)
• Prompt Enhancement: ~1-2 seconds (Gemini AI processing)
• Persona Accuracy: 98%+ (AI-powered selection)
• Required: Gemini API key (free tier available)

---

Made with ❤️ by the BMAD Claude community