MACP = Multiple AI models working in parallel on the same project
APCP = Project context for a single AI
Together = Super powerful
This guide: Assumes you have already set up APCP
Task: Add MACP and perform multi-AI setup
Time: 30-45 minutes
Result: Synchronized operation of 2-5 AI models
# If not already done, download/copy:
cp MACP_MULTI_AI_COORDINATION.md /your/project/MACP.md
# Add to Git
git add MACP.md
git commit -m "docs: add MACP (Multi-AI Coordination Protocol)"# Open .gitignore and add:
cat >> .gitignore << 'EOF'
# MACP - Multi-AI Coordination
.ai_team/heartbeats/ # Local heartbeat logs (privacy)
.ai_team/*.log # Session logs
.ai_team/session-logs/
# But track these:
!.ai_team/handshakes/
!.ai_team/handoffs/
!.ai_team/conflicts/
!.ai_team/AI_TEAM_STATE.json
!.ai_team/integration-points/
!.ai_team/metrics/
EOF
git add .gitignore
git commit -m "chore: configure .gitignore for MACP privacy"# Create .ai_team/templates/ directory
mkdir -p .ai_team/templates
# Handshake template
cat > .ai_team/templates/handshake-template.json << 'EOF'
{
"handshake": {
"version": "1.0",
"timestamp": "2024-01-15T10:30:00Z",
"initiator": {
"ai_model": "[Your AI Model Name]",
"role": "[frontend|backend|database|testing|devops]",
"session_id": "[role]-$(date +%Y-%m-%d-%H%M%S)",
"token_budget": {
"allocated": [NUMBER],
"used": 0,
"remaining": [NUMBER]
}
},
"project": {
"name": "[PROJECT_NAME]",
"github_repo": "[REPO_URL]",
"current_sprint": "[SPRINT_NAME]"
},
"status": "READY",
"focus_areas": [
"TASK-XXX: [Description]"
],
"dependencies": {
"blocks": [],
"blocked_by": [],
"requires_coordination": []
},
"signals": {
"requesting_review_from": [],
"ready_to_be_reviewed_by": [],
"blocking": [],
"needs_help_with": []
}
}
}
EOF
# Handoff template
cat > .ai_team/templates/handoff-template.json << 'EOF'
{
"handoff": {
"version": "1.0",
"from": {
"ai_model": "[Your AI Model]",
"session_id": "[session-id]",
"role": "[role]",
"end_time": "2024-01-15T11:15:00Z"
},
"to": {
"ai_model": "[Next AI Model]",
"role": "[role]",
"expected_start": "2024-01-15T11:30:00Z"
},
"completed_work": {
"tasks": [],
"commits": []
},
"in_progress_work": {
"tasks": []
},
"blockers": [],
"dependencies": {
"waiting_for": [],
"provided_to": []
},
"next_steps_for_tester": []
}
}
EOF
# AI_TEAM_STATE template
cat > .ai_team/AI_TEAM_STATE.json << 'EOF'
{
"ai_team_state": {
"version": "1.0",
"last_updated": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
"project": "[PROJECT_NAME]",
"active_sessions": [],
"completed_sessions": [],
"queue": { "waiting_for_work": [] },
"conflicts": { "active": [], "resolved": [] },
"sync_points": {
"last_sync": null,
"next_sync": null,
"sync_interval_minutes": 30,
"critical_checkpoints": []
},
"code_state": {
"main_branch": "main",
"active_branches": []
},
"integrations": {
"pending": [],
"completed": []
}
}
}
EOF
git add .ai_team/
git commit -m "chore: initialize MACP directory structure and templates"cat > scripts/macp-heartbeat.sh << 'EOF'
#!/bin/bash
# Usage: bash scripts/macp-heartbeat.sh "Balanced Claude model" "backend-2024-01-15-001" "TASK-010" "75"
set -e
AI_MODEL=${1:-"Unknown"}
SESSION_ID=${2:-"session-$(date +%Y%m%d-%H%M%S)"}
TASK=${3:-"Unknown"}
PROGRESS=${4:-0}
TOKEN_USED=${5:-0}
TOKEN_TOTAL=${6:-0}
# Create heartbeats directory if not exists
mkdir -p .ai_team/heartbeats
# Log file
HEARTBEAT_FILE=".ai_team/heartbeats/${AI_MODEL// /_,,}_$(date +%Y%m%d).log"
# Append heartbeat
cat >> "$HEARTBEAT_FILE" << HEARTBEAT_END
$(date -u +%Y-%m-%dT%H:%M:%SZ) | $AI_MODEL | $SESSION_ID | $TASK | $PROGRESS% | Tokens: $TOKEN_USED/$TOKEN_TOTAL
HEARTBEAT_END
echo " Heartbeat recorded for $AI_MODEL"
echo " Task: $TASK ($PROGRESS%)"
echo " File: $HEARTBEAT_FILE"
EOF
chmod +x scripts/macp-heartbeat.shcat > scripts/macp-state-update.sh << 'EOF'
#!/bin/bash
# Usage: bash scripts/macp-state-update.sh "Balanced Claude model" "ACTIVE" "TASK-010" "75"
set -e
AI_MODEL=$1
STATUS=$2
TASK=$3
PROGRESS=$4
TOKEN_USED=${5:-0}
# Update AI_TEAM_STATE.json
python3 << PYTHON_END
import json
import os
from datetime import datetime
state_file = ".ai_team/AI_TEAM_STATE.json"
with open(state_file, 'r') as f:
state = json.load(f)
# Update timestamp
state['ai_team_state']['last_updated'] = datetime.utcnow().isoformat() + 'Z'
# Find or create session for this AI
session_found = False
for session in state['ai_team_state']['active_sessions']:
if session['ai_model'] == "$AI_MODEL":
session['status'] = "$STATUS"
session['current_task'] = "$TASK"
session['progress'] = {"current": "$PROGRESS%"}
session['last_heartbeat'] = datetime.utcnow().isoformat() + 'Z'
session['token_usage']['used'] = $TOKEN_USED
session_found = True
break
if not session_found and "$STATUS" == "ACTIVE":
new_session = {
"ai_model": "$AI_MODEL",
"role": "[role]",
"session_id": "[session-id]",
"status": "$STATUS",
"current_task": "$TASK",
"progress": {"current": "$PROGRESS%"},
"token_usage": {"used": $TOKEN_USED},
"last_heartbeat": datetime.utcnow().isoformat() + 'Z'
}
state['ai_team_state']['active_sessions'].append(new_session)
with open(state_file, 'w') as f:
json.dump(state, f, indent=2)
print(f" State updated for {AI_MODEL}")
PYTHON_END
EOF
chmod +x scripts/macp-state-update.shcat > scripts/macp-sync-check.sh << 'EOF'
#!/bin/bash
echo " MACP Synchronization Check"
echo ""
# Check AI_TEAM_STATE.json exists
if [ ! -f ".ai_team/AI_TEAM_STATE.json" ]; then
echo " AI_TEAM_STATE.json not found"
exit 1
fi
echo " AI_TEAM_STATE.json exists"
echo ""
# Check for active sessions
python3 << 'PYTHON_END'
import json
from datetime import datetime, timedelta
with open(".ai_team/AI_TEAM_STATE.json", 'r') as f:
state = json.load(f)
active = state['ai_team_state']['active_sessions']
print(f"Active Sessions: {len(active)}")
print("")
for session in active:
print(f" {session['ai_model']}")
print(f" Task: {session.get('current_task', 'Unknown')}")
print(f" Status: {session.get('status', 'Unknown')}")
print(f" Last Heartbeat: {session.get('last_heartbeat', 'Never')}")
# Check if heartbeat is recent
if 'last_heartbeat' in session:
last_hb = datetime.fromisoformat(session['last_heartbeat'].replace('Z', '+00:00'))
now = datetime.now(last_hb.tzinfo)
diff = (now - last_hb).total_seconds() / 60
if diff > 10:
print(f" No heartbeat for {int(diff)} minutes!")
else:
print(f" Heartbeat recent ({int(diff)} min ago)")
print("")
# Check for conflicts
conflicts = state['ai_team_state']['conflicts']['active']
if conflicts:
print(f" Active Conflicts: {len(conflicts)}")
for conflict in conflicts:
print(f" - {conflict.get('id', 'Unknown')}: {conflict.get('issue', 'Unknown issue')}")
else:
print(" No active conflicts")
PYTHON_END
echo ""
echo " Sync check complete"
EOF
chmod +x scripts/macp-sync-check.shcat > scripts/macp-init.sh << 'EOF'
#!/bin/bash
set -e
echo " Initializing MACP..."
echo ""
# Create directories
echo "Creating directories..."
mkdir -p .ai_team/{handshakes,handoffs,conflicts,heartbeats,session-logs,integration-points,metrics}
echo " Directories created"
echo ""
# Create README
echo "Creating .ai_team/README.md..."
cat > .ai_team/README.md << 'README_END'
# Multi-AI Coordination (MACP)
This directory contains all coordination files for parallel AI development.
## Structure
- **handshakes/**: Initial session handshakes
- **handoffs/**: Session handoff documents
- **conflicts/**: Resolved conflicts and logs
- **heartbeats/**: Session heartbeat logs (local, not git-tracked)
- **session-logs/**: Full session logs
- **integration-points/**: Integration definitions
- **metrics/**: Team metrics and velocity
- **AI_TEAM_STATE.json**: Real-time team state (MAIN FILE)
## Quick Commands
```bash
# Check team status
bash ../scripts/macp-sync-check.sh
# Record heartbeat
bash ../scripts/macp-heartbeat.sh "AI Model" "session-id" "TASK-XXX" "50"
# Update state
bash ../scripts/macp-state-update.sh "AI Model" "ACTIVE" "TASK-XXX" "75"See: ../MACP.md README_END echo " README created" echo ""
echo "Initializing AI_TEAM_STATE.json..." cat > .ai_team/AI_TEAM_STATE.json << 'STATE_END' { "ai_team_state": { "version": "1.0", "last_updated": "2024-01-15T10:00:00Z", "project": "[PROJECT_NAME]", "active_sessions": [], "completed_sessions": [], "queue": { "waiting_for_work": [] }, "conflicts": { "active": [], "resolved": [] }, "sync_points": { "last_sync": null, "next_sync": null, "sync_interval_minutes": 30, "critical_checkpoints": [] }, "code_state": { "main_branch": "main", "active_branches": [] }, "integrations": { "pending": [], "completed": [] } } } STATE_END echo " AI_TEAM_STATE.json initialized" echo ""
echo "Committing to git..." git add .ai_team/ scripts/macp-*.sh git commit -m "chore: initialize MACP infrastructure" echo " Committed to git" echo ""
echo " MACP initialization complete!" echo "" echo "Next steps:" echo "1. Update PROJECT_NAME in AI_TEAM_STATE.json" echo "2. Create your first handshake" echo "3. Run: bash scripts/macp-sync-check.sh" EOF
chmod +x scripts/macp-init.sh
---
## STEP 3: First Setup (Initial Setup) (10 minutes)
### 3.1 Initialize MACP
```bash
# Run initialization script
bash scripts/macp-init.sh
# Output should show:
# Directories created
# README created
# AI_TEAM_STATE.json initialized
# Committed to git
# Open AI_TEAM_STATE.json
nano .ai_team/AI_TEAM_STATE.json
# Change the "project" section:
{
"project": "[PROJECT_NAME]", # Change this to your project name
...
}
git add .ai_team/AI_TEAM_STATE.json
git commit -m "docs: customize MACP project name"Create MACP_ROLES.yaml in the project root:
cat > MACP_ROLES.yaml << 'EOF'
ai_roles:
frontend:
ai_model: "Lightweight Claude model"
responsibility:
- UI components
- Routes
- Frontend logic
token_budget: 100000
priority: HIGH
status: READY
backend:
ai_model: "Balanced Claude model"
responsibility:
- API endpoints
- Business logic
- Services
token_budget: 200000
priority: HIGH
status: READY
database:
ai_model: "Codex / OpenAI GPT model"
responsibility:
- Database schema
- Migrations
- Queries
token_budget: 150000
priority: HIGH
status: READY
testing:
ai_model: "Lightweight Claude model"
responsibility:
- Unit tests
- Integration tests
- QA
token_budget: 80000
priority: MEDIUM
status: READY
devops:
ai_model: "Advanced Claude model"
responsibility:
- Docker
- K8s
- CI/CD
token_budget: 120000
priority: MEDIUM
status: SCHEDULED
git add MACP_ROLES.yaml
git commit -m "docs: define AI roles for MACP"What the Frontend AI should do at the start of its session:
# Frontend Claude creates this file:
# .ai_team/handshakes/frontend-2024-01-15-001.json
cat > .ai_team/handshakes/frontend-2024-01-15-001.json << 'EOF'
{
"handshake": {
"version": "1.0",
"timestamp": "2024-01-15T09:00:00Z",
"initiator": {
"ai_model": "Lightweight Claude model",
"role": "Frontend",
"session_id": "frontend-2024-01-15-001",
"token_budget": {
"allocated": 100000,
"used": 0,
"remaining": 100000
}
},
"project": {
"name": "[PROJECT_NAME]",
"github_repo": "[REPO_URL]",
"current_sprint": "Sprint 1"
},
"status": "READY",
"expected_duration": "2 hours",
"focus_areas": [
"TASK-001: Component library",
"TASK-005: Routing setup"
],
"dependencies": {
"blocks": ["TASK-005 (needs Backend API routes)"],
"blocked_by": [],
"requires_coordination": ["Backend AI agent"]
},
"signals": {
"requesting_review_from": [],
"ready_to_be_reviewed_by": ["Testing AI agent"],
"blocking": [],
"needs_help_with": []
}
}
}
EOF
git add .ai_team/handshakes/frontend-2024-01-15-001.json
git commit -m "feat: Frontend Claude - session start handshake"
git push# Python script to update state
cat > scripts/update-state.py << 'PYTHON_END'
import json
from datetime import datetime
with open('.ai_team/AI_TEAM_STATE.json', 'r') as f:
state = json.load(f)
# Add new session
state['ai_team_state']['active_sessions'].append({
"session_id": "frontend-2024-01-15-001",
"ai_model": "Lightweight Claude model",
"role": "Frontend",
"status": "ACTIVE",
"start_time": "2024-01-15T09:00:00Z",
"current_task": "TASK-001",
"progress": {"subtask_1": "In progress"},
"token_usage": {"allocated": 100000, "used": 0, "remaining": 100000},
"last_heartbeat": datetime.utcnow().isoformat() + "Z"
})
state['ai_team_state']['last_updated'] = datetime.utcnow().isoformat() + "Z"
with open('.ai_team/AI_TEAM_STATE.json', 'w') as f:
json.dump(state, f, indent=2)
print(" State updated")
PYTHON_END
python3 scripts/update-state.py
git add .ai_team/AI_TEAM_STATE.json
git commit -m "chore: update MACP state - Frontend session started"
git push# Frontend Claude, every 30 minutes:
bash scripts/macp-heartbeat.sh "Lightweight Claude model" "frontend-2024-01-15-001" "TASK-001" "60" 35000 100000
# Output:
# Heartbeat recorded for Lightweight Claude model
# Task: TASK-001 (60%)
# File: .ai_team/heartbeats/lightweight_claude_model_20240115.log# Anyone can check team status:
bash scripts/macp-sync-check.sh
# Output:
# MACP Synchronization Check
# AI_TEAM_STATE.json exists
# Active Sessions: 1
# Lightweight Claude model
# Task: TASK-001
# Status: ACTIVE
# Heartbeat recent (2 min ago)
# No active conflicts
# Sync check completeWhen the Frontend AI ends its session:
# Frontend saves to .ai_team/handoffs/ directory:
cat > .ai_team/handoffs/frontend-2024-01-15-001-handoff.json << 'EOF'
{
"handoff": {
"version": "1.0",
"from": {
"ai_model": "Lightweight Claude model",
"session_id": "frontend-2024-01-15-001",
"role": "Frontend",
"session_duration": "2 hours",
"end_time": "2024-01-15T11:00:00Z"
},
"to": {
"ai_model": "Lightweight Claude model (Testing)",
"role": "Testing",
"expected_start": "2024-01-15T11:30:00Z"
},
"completed_work": {
"tasks": [
{
"task_id": "TASK-001",
"title": "Component Library",
"status": " COMPLETED",
"pr_created": true,
"pr_number": 42,
"notes": "All components follow design system. Ready for testing."
}
],
"commits": [
{
"hash": "abc123def456",
"message": "feat(ui): create component library",
"files_changed": 12
}
]
},
"in_progress_work": {
"tasks": [
{
"task_id": "TASK-005",
"title": "Routing Setup",
"status": " IN_PROGRESS",
"progress": "40%",
"notes": "Blocked by Backend API routes (TASK-010)"
}
]
},
"blockers": [
{
"task": "TASK-005",
"blocked_by": "TASK-010 (Backend AI agent - API routes)",
"expected_resolution": "2024-01-15T13:00:00Z"
}
],
"code_quality": {
"tests_written": 24,
"test_coverage": "85%",
"linting_issues": 0,
"security_scan": "CLEAN"
},
"next_steps": [
"1. Testing AI agent: Run tests on TASK-001",
"2. Wait for Backend to complete TASK-010",
"3. Continue TASK-005 integration"
]
}
}
EOF
git add .ai_team/handoffs/
git commit -m "docs: Frontend session handoff - TASK-001 complete"
git pushpython3 << 'END'
import json
with open('.ai_team/AI_TEAM_STATE.json', 'r') as f:
state = json.load(f)
# Move session to completed
sessions = state['ai_team_state']['active_sessions']
session = next((s for s in sessions if s['session_id'] == 'frontend-2024-01-15-001'), None)
if session:
sessions.remove(session)
state['ai_team_state']['completed_sessions'].append({
**session,
"completed_at": "2024-01-15T11:00:00Z",
"handoff_created": True
})
with open('.ai_team/AI_TEAM_STATE.json', 'w') as f:
json.dump(state, f, indent=2)
print(" Session marked as complete")
END
git add .ai_team/AI_TEAM_STATE.json
git commit -m "chore: mark Frontend session as completed"
git push# Send heartbeat (every 30 minutes)
bash scripts/macp-heartbeat.sh "AI Model" "session-id" "TASK-XXX" "75"
# Check team status
bash scripts/macp-sync-check.sh
# Create handshake (start of session)
# Template: .ai_team/templates/handshake-template.json
# Save: .ai_team/handshakes/[model]-[date]-[id].json
# Create handoff (end of session)
# Template: .ai_team/templates/handoff-template.json
# Save: .ai_team/handoffs/[model]-[date]-[id]-handoff.json
# Update state
bash scripts/macp-state-update.sh "AI Model" "ACTIVE" "TASK-XXX" "75" 45000
# Log conflict
# File: .ai_team/conflicts/[type]-conflict-[id].json
# Reference: MACP.md Section 5Checklist:
□ Read .ai_team/AI_TEAM_STATE.json
□ Check active sessions and conflicts
□ Read any pending handoffs from other AIs
□ Identify blockers (anything blocking you?)
□ Identify your blocks (anything you're blocking?)
□ Create handshake.json
□ Push to git
□ Ready to start!Actions:
□ Work on assigned tasks
□ Run heartbeat script
□ Git commit every 30 minutes
□ Check for new conflicts/handshakes
□ Update progress in subtasks
□ Keep TASK_PROGRESS.yaml freshCleanup:
□ Run all tests (checkpoint.sh)
□ Create handoff.json
□ Update AI_TEAM_STATE.json
□ Push to git
□ Notify next AI in queue
□ Document any blockers# Validate JSON
python3 -m json.tool .ai_team/AI_TEAM_STATE.json
# If error, fix manually:
nano .ai_team/AI_TEAM_STATE.json# State files should rarely conflict if done right
# If they do:
# Option 1: Keep both changes
git checkout --theirs .ai_team/AI_TEAM_STATE.json
# Option 2: Manually merge (rare)
nano .ai_team/AI_TEAM_STATE.json# Check file exists
ls -la .ai_team/handshakes/
# If not, other AI hasn't created it yet
# Wait 5 minutes, then check git pull
git pull
ls -la .ai_team/handshakes/# MORNING: Frontend Claude starts
# 1. Initialize
bash scripts/macp-init.sh
# 2. Create handshake
# (Save: .ai_team/handshakes/frontend-2024-01-15-001.json)
# Commit
# 3. Work
# TASK-001: Component library
# 60 min work, then:
# 4. Heartbeat
bash scripts/macp-heartbeat.sh "Lightweight Claude model" "frontend-2024-01-15-001" "TASK-001" "50" 25000 100000
# 5. More work
# TASK-001: continued
# 60 min work
# 6. Heartbeat again
bash scripts/macp-heartbeat.sh "Lightweight Claude model" "frontend-2024-01-15-001" "TASK-001" "100" 35000 100000
# 7. Finalize
# Run tests: bash scripts/checkpoint.sh
# Create handoff
# Push to git
# NOON: Backend AI agent starts
# 1. Read state
cat .ai_team/AI_TEAM_STATE.json
# 2. Read Frontend's handoff
cat .ai_team/handoffs/frontend-2024-01-15-001-handoff.json
# 3. Create handshake
# (Notes: "Frontend blocked on TASK-010, prioritizing")
# 4. Work on TASK-010 (API routes)
# Rest of workflow continues...Before deploying MACP, verify:
□ MACP.md exists and is readable
□ .ai_team/ directory created with subdirectories
□ .gitignore properly configured
□ AI_TEAM_STATE.json exists and valid JSON
□ All scripts executable (chmod +x)
□ Git workflows work (handshakes push/pull)
□ Team understands roles (MACP_ROLES.yaml)
□ Documented in README.md
□ Test with dummy handshake/handoff
For detailed info, see:
- MACP.md - Full protocol specification
- APCP.md - Single AI context protocol
- TASK_PROGRESS.yaml - Task tracking
- MACP_ROLES.yaml - AI role definitions
- README.md - Project overview
MACP is now set up. Your team can:
Work in parallel (Frontend + Backend + Database + Testing) Coordinate automatically (handshakes + state sync) Handle conflicts gracefully (structured resolution) Transition smoothly (detailed handoffs) Monitor progress (heartbeats + metrics) Scale to 3-5 AI models efficiently
**Let's build together! **
Version: 1.0 Created: 2024-01-15 Status: Ready to Use
For support, refer to MACP.md Section 14