BluEng9/parallel-dev

parallel-dev — Parallel Development Across Your Machines

Automate development tasks across multiple machines with AI-powered parallel execution.
MCP server for Claude Code with intelligent task distribution and health monitoring.

✨ Features

• ⚡️ Parallel execution across multiple development machines
• 🧰 Claude Code MCP integration with slash commands
• 🪝 Safety hooks for command validation and audit logging
• 🔒 Privacy-first - local execution, no telemetry
• 📊 Health monitoring with real-time status checks
• 🔧 Per-machine deploy commands - fully customizable workflows
• 🎯 Branch placeholder support - {branch} auto-substitution

🚀 Quick Start

Option 1: Automated Setup (Recommended)

git clone https://github.com/BluEng9/parallel-dev-mcp.git
cd parallel-dev-mcp
pip install -r requirements.txt

# Run complete setup (SSH + verification)
./scripts/setup-all.sh

This one command will:

• ✅ Generate SSH keys
• ✅ Configure both machines (M1 + M3)
• ✅ Create deploy directories
• ✅ Verify everything works

Option 2: Manual Setup

# 1. Clone and install
git clone https://github.com/BluEng9/parallel-dev-mcp.git
cd parallel-dev-mcp
pip install -r requirements.txt

# 2. Configure
cp config/dual-machines.example.json dual-machines.local.json
# Edit with your machine details

# 3. Setup SSH
./scripts/fix-ssh.sh

# 4. Verify
./scripts/verify-setup.sh

# 5. Start MCP server
./scripts/start.sh

Use in Claude Code

/doctor              # Full system diagnostic
/health              # Quick health status
/deploy both master  # Deploy to all machines

📖 See for detailed instructions.

⚙️ Configuration

Basic Setup

Your dual-machines.local.json controls all machine behavior:

{
  "machines": {
    "m1": {
      "ssh": "user@127.0.0.1",
      "health_url": "http://localhost:3000/health",
      "deploy": [
        "cd ~/Workspace/Projects/your-app && git pull origin {branch}",
        "cd ~/Workspace/Projects/your-app && docker compose up -d --build"
      ]
    },
    "m3": {
      "ssh": "user@192.168.0.101",
      "health_url": "http://192.168.0.101:3000/health",
      "deploy": [
        "cd ~/Workspace/Projects/your-app && git pull origin {branch}",
        "cd ~/Workspace/Projects/your-app && docker compose restart"
      ]
    }
  },
  "policy": {
    "max_parallel": 2,
    "require_approval": ["docker compose down"],
    "dangerous_patterns": ["rm -rf", "mkfs"]
  }
}

💡 Tip: Use ./scripts/fix-deploy-paths.sh to update paths automatically.

📁 Project Structure

parallel-dev/
├── mcp_server/           # MCP server implementation
│   ├── main.py           # Server entry point
│   └── tools/            # Tool implementations
├── src/                  # Core source code
│   ├── doctor.py         # Diagnostic tool
│   └── health_server.py  # Test health server
├── scripts/              # Setup & utility scripts
│   ├── setup-all.sh      # Complete automated setup
│   ├── fix-ssh.sh        # SSH configuration
│   ├── verify-setup.sh   # Verify installation
│   └── fix-deploy-paths.sh  # Update config paths
├── docs/                 # Documentation
│   ├── QUICK_START.md    # 5-minute setup guide
│   ├── SETUP_CHECKLIST.md # Detailed checklist
│   └── architecture/     # Design documentation
├── tests/                # Test suite
└── config/               # Configuration examples

📚 Documentation

Getting Started

• ⚡ - Get running in 5 minutes
• 📋 - Step-by-step setup guide
• 📖 - Detailed installation

Architecture & Design

• 🏗️ - System design
• 🎨 - Visual architecture
• 🔧 - All config options

Reference

• ⚡ - Common commands
• 📋 - Development roadmap
• 🐛 - Solutions to common issues

🧭 Usage Examples

System Diagnostics

/doctor                    # Full diagnostic report
/doctor --dry-run          # Preview without execution

Health Monitoring

/health                    # Check all machines

Deployments

/deploy m1 master          # Deploy to single machine
/deploy both feature-xyz   # Deploy to all machines

Verification Scripts

./scripts/verify-setup.sh  # Verify complete setup
./scripts/fix-ssh.sh       # Fix SSH issues

🔒 Security & Safety

Built-in Protection

• ✅ SSH key-based authentication
• ✅ Command allow-list per machine
• ✅ Dangerous pattern blocking (rm -rf, fork bombs, etc.)
• ✅ Audit logging with SHA-256 signatures
• ✅ 5-minute operation timeout
• ✅ Local-first (no external services)

Environment Variables

# Custom log location
export PD_LOG_DIR=~/custom-logs

# Custom state location
export PD_STATE_DIR=~/custom-state

# API keys (if needed)
export ANTHROPIC_API_KEY=sk-ant-...

Log Files

• Logs: .parallel-dev/logs/run_*.jsonl
• State: .parallel-dev/state/machine.facts.json
• Fallback: ~/.parallel-dev/ if local directory fails

🧪 Testing

# Run all tests
pytest tests/

# Run specific test
python tests/test_doctor.py

# Quick verification
./scripts/verify-setup.sh

🐛 Troubleshooting

Quick Fixes

SSH Connection Failed:

./scripts/fix-ssh.sh

Deploy Path Wrong:

./scripts/fix-deploy-paths.sh

Verify Everything:

./scripts/verify-setup.sh

Reset Setup:

./scripts/setup-all.sh

Common Issues

📖 See for detailed solutions.

🤝 Contributing

Contributions are welcome! Please read our .

Development Setup

git clone https://github.com/BluEng9/parallel-dev-mcp.git
cd parallel-dev-mcp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Run in development
PYTHONUNBUFFERED=1 python -m mcp_server.main

📊 Performance

• Parallel execution: Deploy to 2 machines in ~30s (vs 60s sequential)
• Health checks: Sub-second response
• Doctor diagnostics: 3-5s for full check
• Memory: ~50MB MCP server
• Logs: ~10KB per deployment

📄 License

GPL-3.0 — see

🙏 Acknowledgments

Built with:

• FastMCP - MCP server framework
• Claude - AI assistance
• Open source community ❤️

🔗 Quick Links

• 📦 GitHub Repository
• 🐛 Report Issues
• 💬 Discussions
• 📖
• ⚡

Made for developers who live on more than one machine. 🚀

If this project helps you, consider giving it a ⭐️ on GitHub!

See for all commands.