opencode-mad

Multi-Agent Dev (MAD) - Parallel development orchestration plugin for OpenCode.

Decompose complex tasks into parallelizable subtasks, each running in isolated git worktrees with dedicated AI subagents. Now with 10 specialized agents and hard constraints enforced at the code level.

🎉 What's New in v1.0.0

🤖 5 New Specialized Agents

• mad-analyste - Analyzes the codebase (full or targeted analysis), READ-ONLY
• mad-architecte - Creates detailed development plans with file ownership, READ-ONLY
• mad-reviewer - Reviews code quality before merge, READ-ONLY
• mad-security - Scans for security vulnerabilities, READ-ONLY
• mad-pentester - Web penetration testing via URL, READ-ONLY

🔒 Hard Constraints (Code-Level Enforcement)

The plugin now blocks unauthorized actions at the code level:

• READ-ONLY agents cannot use edit, write, or patch tools
• Developers are constrained to their assigned file ownership
• Dangerous bash commands are blocked for read-only agents

🔄 Refactored Orchestrator

The orchestrator now delegates analysis and planning to specialized agents:

• Uses mad-analyste for codebase understanding
• Uses mad-architecte for development planning
• Focuses on coordination and monitoring

🛠️ New Tools

• mad_register_agent - Register agent with role and permissions
• mad_unregister_agent - Unregister agent when done
• mad_analyze - Trigger codebase analysis
• mad_create_plan - Create development plan
• mad_review - Request code review
• mad_security_scan - Run security scan

Features

• Smart Planning - Orchestrator delegates to Analyste and Architecte for thorough planning
• File Ownership - Each agent has exclusive files, preventing merge conflicts
• Hard Constraints - Plugin enforces permissions at the code level
• Parallel Execution - Multiple developers work simultaneously in git worktrees
• Quality Gates - Tester, Reviewer, and Security agents validate before merge
• Conflict Resolution - Dedicated merger agent handles git conflicts
• Integration Fixes - Fixer agent ensures everything works together

Installation

Option 1: npx (Recommended)

# Install to current project
npx opencode-mad install

# Or install globally (all projects)
npx opencode-mad install -g

# Update existing installation
npx opencode-mad update -g

# Check version
npx opencode-mad version

Option 2: Manual copy

# Clone the repo
git clone https://github.com/Nistro-dev/opencode-mad.git

# Copy to your project
cp -r opencode-mad/agents your-project/.opencode/
cp -r opencode-mad/commands your-project/.opencode/
cp -r opencode-mad/plugins your-project/.opencode/
cp -r opencode-mad/skills your-project/.opencode/

# Or copy globally
cp -r opencode-mad/agents ~/.config/opencode/agents/
cp -r opencode-mad/commands ~/.config/opencode/commands/
cp -r opencode-mad/plugins ~/.config/opencode/plugins/
cp -r opencode-mad/skills ~/.config/opencode/skills/

Project structure after installation

your-project/
├── .opencode/
│   ├── agents/
│   │   ├── orchestrator.md      # Main coordinator
│   │   ├── mad-analyste.md      # Codebase analysis (READ-ONLY)
│   │   ├── mad-architecte.md    # Development planning (READ-ONLY)
│   │   ├── mad-developer.md     # Implements features
│   │   ├── mad-tester.md        # Tests before merge
│   │   ├── mad-reviewer.md      # Code review (READ-ONLY)
│   │   ├── mad-security.md      # Security scanning (READ-ONLY)
│   │   ├── mad-merger.md        # Resolves conflicts
│   │   └── mad-fixer.md         # Fixes integration
│   ├── commands/
│   ├── plugins/
│   │   └── mad-plugin.ts
│   └── skills/
└── ... your code

Usage

Once installed, just talk to the orchestrator naturally:

You: Create a Task Timer app with Express backend and React frontend

Orchestrator: I'll analyze the codebase first...
[Spawns mad-analyste for codebase analysis]

Analyste: Analysis complete. Here's the structure...

Orchestrator: Now creating the development plan...
[Spawns mad-architecte for planning]

Architecte: Here's the development plan with file ownership:
- Developer 1: /backend/** (Express API)
- Developer 2: /frontend/** (React UI)
- Developer 3: /shared/** (Types & utils)

Orchestrator: Ready to proceed? Reply "GO"

You: GO

Orchestrator: [Creates worktrees, spawns developers in parallel...]

Commands (Optional)

| Command | Description | |---------|-------------| | /mad <task> | Start parallel orchestration | | /mad-status | Show worktree status | | /mad-visualize | ASCII dashboard | | /mad-fix <worktree> | Fix errors in a worktree | | /mad-merge-all | Merge all completed worktrees |

Reporting Bugs

Just tell the orchestrator about the bug - it will delegate to a fixer:

You: There's a CORS error, the frontend can't reach the backend

Orchestrator: I'll spawn a fixer to resolve this.
[Delegates to mad-fixer]

How It Works

┌─────────────────────────────────────────────────────────────┐
│  You: "Create a full-stack app..."                          │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  ORCHESTRATOR (primary agent)                               │
│  - Coordinates the entire workflow                          │
│  - Delegates analysis and planning                          │
│  - Monitors progress and handles issues                     │
└─────────────────────────────────────────────────────────────┘
                            │
            ┌───────────────┴───────────────┐
            ▼                               ▼
┌───────────────────────┐     ┌───────────────────────┐
│  ANALYSTE (READ-ONLY) │     │  ARCHITECTE (READ-ONLY)│
│  - Analyzes codebase  │────▶│  - Creates dev plan    │
│  - Maps dependencies  │     │  - Assigns ownership   │
│  - Identifies patterns│     │  - Defines interfaces  │
└───────────────────────┘     └───────────────────────┘
                                          │
                                          ▼ "GO"
┌─────────────────────────────────────────────────────────────┐
│  DEVELOPERS (parallel in git worktrees)                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                  │
│  │ Backend  │  │ Frontend │  │  Config  │                  │
│  │ /backend │  │ /frontend│  │ /root    │                  │
│  └──────────┘  └──────────┘  └──────────┘                  │
│  Each owns exclusive files - ENFORCED BY PLUGIN!            │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  QUALITY GATES (parallel)                                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                  │
│  │ TESTER   │  │ REVIEWER │  │ SECURITY │                  │
│  │ Run tests│  │ Code     │  │ Vuln     │                  │
│  │ & verify │  │ quality  │  │ scanning │                  │
│  └──────────┘  └──────────┘  └──────────┘                  │
│  All READ-ONLY - cannot modify code!                        │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  MERGER (if conflicts)                                      │
│  - Understands both branches' intent                        │
│  - Combines functionality intelligently                     │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  FIXER (if integration issues)                              │
│  - Fixes cross-component bugs                               │
│  - Ensures frontend + backend work together                 │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
                        DONE! 🎉

🔒 Hard Constraints

MAD v1.0.0 introduces hard constraints enforced at the plugin level. This means agents cannot bypass their permissions, even if they try.

How It Works

When an agent registers with the plugin, it declares its role:

// Agent registers with the plugin
mad_register_agent({
  agentId: "analyste-abc123",
  role: "analyste",
  permissions: {
    canWrite: false,      // READ-ONLY
    canExecute: false,    // No bash commands
    filePatterns: ["**/*"] // Can read everything
  }
})

The plugin then intercepts all tool calls and blocks unauthorized actions:

❌ BLOCKED: Agent 'analyste-abc123' attempted to use 'edit' tool
   Reason: Agent role 'analyste' does not have write permissions

Permission Matrix

| Agent | Read | Write | Execute | File Scope | |-------|------|-------|---------|------------| | orchestrator | ✅ | ✅ | ✅ | **/* | | mad-analyste | ✅ | ❌ | ❌ | **/* | | mad-architecte | ✅ | ❌ | ❌ | **/* | | mad-developer | ✅ | ✅ | ✅ | Assigned files only | | mad-tester | ✅ | ✅ | ✅ | Test files + worktree | | mad-reviewer | ✅ | ❌ | ❌ | **/* | | mad-security | ✅ | ❌ | ❌ | **/* | | mad-pentester | ✅ | ❌ | ✅ | **/* (bash for pentest tools only) | | mad-merger | ✅ | ✅ | ✅ | Conflict files | | mad-fixer | ✅ | ✅ | ✅ | Integration files |

Developer File Ownership

Developers are constrained to their assigned files:

Task: "Implement backend API"
YOU OWN: /backend/**

✅ ALLOWED: edit /backend/server.js
✅ ALLOWED: write /backend/routes/api.js
❌ BLOCKED: edit /frontend/App.tsx (not in ownership)
❌ BLOCKED: write /package.json (not in ownership)

This prevents merge conflicts and ensures clean parallel development.

Agents

| Agent | Mode | Permissions | Description | |-------|------|-------------|-------------| | orchestrator | primary | Full | Coordinates workflow, delegates to specialists. Never codes directly. | | mad-analyste | subagent | READ-ONLY | Analyzes codebase structure, dependencies, and patterns | | mad-architecte | subagent | READ-ONLY | Creates development plans with file ownership | | mad-developer | subagent | Scoped Write | Implements tasks in isolated worktrees (constrained to owned files) | | mad-tester | subagent | Test Write | Tests code before merge, can fix simple issues | | mad-reviewer | subagent | READ-ONLY | Reviews code quality, suggests improvements | | mad-security | subagent | READ-ONLY | Scans for security vulnerabilities | | mad-merger | subagent | Conflict Write | Resolves git merge conflicts | | mad-fixer | subagent | Integration Write | Fixes cross-component integration issues | | mad-pentester | subagent | READ-ONLY | Web penetration testing via URL (3 scan modes) |

Custom Tools

The plugin provides these tools:

Core Tools

| Tool | Description | |------|-------------| | mad_worktree_create | Create isolated git worktree | | mad_status | Get status of all worktrees | | mad_visualize | ASCII art dashboard | | mad_test | Run tests on a worktree | | mad_merge | Merge completed worktree | | mad_cleanup | Remove finished worktree | | mad_done | Mark task as completed | | mad_blocked | Mark task as blocked | | mad_read_task | Read task description | | mad_log | Log orchestration events | | mad_check_update | Check for plugin updates | | mad_push_and_watch | Push and monitor CI | | mad_final_check | Run final build/lint checks |

New in v1.0.0

| Tool | Description | |------|-------------| | mad_register_agent | Register agent with role and permissions | | mad_unregister_agent | Unregister agent when done | | mad_analyze | Trigger codebase analysis (full or targeted) | | mad_create_plan | Create development plan with file ownership | | mad_review | Request code review for a worktree | | mad_security_scan | Run security vulnerability scan | | mad_pentest_check_tools | Check if pentest tools are installed (nmap, nikto, etc.) | | mad_pentest_scan | Register pentest scan results for a target URL |

Updates

opencode-mad checks for updates automatically and notifies you when a new version is available.

To update manually:

npx opencode-mad update -g

To check for updates:

npx opencode-mad version

Web Penetration Testing

MAD includes a pentester agent for dynamic security testing of web applications.

Prerequisites

Install the required tools:

# Debian/Ubuntu
sudo apt install nmap nikto sqlmap

# macOS
brew install nmap nikto sqlmap

# Verify installation
npx opencode-mad pentest-check

Scan Modes

| Mode | Description | Tools Used | |------|-------------|------------| | basic | Headers, SSL/TLS, known vulnerabilities | nmap, nikto | | deep | Crawling, fuzzing, endpoint discovery | nikto, dirb, gobuster | | exploit | Active SQLi, XSS, CSRF testing | sqlmap, nikto |

Usage Examples

You: Run a basic security scan on https://example.com

Orchestrator: I'll spawn the pentester agent...
[Spawns mad-pentester]

Pentester: Starting basic scan on https://example.com
- Checking SSL/TLS configuration...
- Scanning for open ports...
- Testing security headers...

Results:
⚠️  Missing X-Frame-Options header
⚠️  TLS 1.0 still enabled
✅ No known CVEs detected

For deeper analysis:

You: Run a deep scan on https://staging.myapp.com

Pentester: Starting deep scan...
- Crawling site structure...
- Fuzzing endpoints...
- Testing authentication flows...

⚠️ Legal Disclaimer

IMPORTANT: Only run penetration tests on systems you own or have explicit written permission to test. Unauthorized security testing is illegal in most jurisdictions.

The pentester agent will:

• Ask for confirmation before running scans
• Log all scan activities
• Never run exploit mode without explicit user consent

Requirements

• OpenCode 1.0+
• Git (for worktrees)
• Node.js 18+
• For pentesting: nmap, nikto, sqlmap (optional)

Configuration

The orchestrator uses these defaults:

• Model: anthropic/claude-opus-4-5
• Never pushes automatically (only commits)
• Always delegates analysis and planning to specialists

To change the model, edit .opencode/agents/orchestrator.md:

---
model: anthropic/claude-sonnet-4-20250514
---

License

MIT

Contributing

Issues and PRs welcome at github.com/Nistro-dev/opencode-mad