Content
# A2A - Agent-to-Agent Communication Protocol
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
**A2A** is a tmux-based multi-agent orchestration system for [Claude Code](https://claude.ai/code). It enables real-time communication between AI agents running in different tmux panes, with features like auto-healing, dynamic scaling, and smart routing.
## ✨ Features
- 🚀 **One-Command Bootstrap** - Start entire multi-agent system with a single command
- 💚 **Health Monitoring** - Real-time agent health checks with auto-recovery
- 💾 **State Management** - Distributed state store with event sourcing
- 📊 **Real-Time Dashboard** - Terminal-based monitoring UI
- ⚖️ **Dynamic Scaling** - Auto-scale workers based on load (2-8 agents)
- 🧠 **Smart Routing** - Task classification and optimal agent assignment
- 🔄 **PUSH Protocol** - Workers report to Conductor (no polling)
## 🏗️ Architecture
```
┌─────────────────────────────────────────────┐
│ Conductor (指揮郎) │
│ Receives PUSH reports from workers │
└─────────────────────────────────────────────┘
↑ PUSH Task Assignment ↓
┌─────────────────────────────────────────────┐
│ Workers: │
│ 楓 (CodeGen) → 桜 (Review) → 椿 (PR) │
│ ↓ │
│ 牡丹 (Deploy) │
└─────────────────────────────────────────────┘
```
## 📦 Installation
```bash
# Clone the repository
git clone https://github.com/ShunsukeHayashi/a2a.git
cd a2a
# Install dependencies
npm install
# Make scripts executable
chmod +x scripts/*.sh bin/a2a.js
```
## 🚀 Quick Start
### 1. Bootstrap the System
```bash
# Start all agents (creates tmux session with 5 panes)
./scripts/a2a_bootstrap.sh --attach
# Or use npm script
npm run bootstrap
```
### 2. Monitor Health
```bash
# One-time health check
./scripts/a2a_health.sh
# Continuous monitoring (30s interval)
./scripts/a2a_health.sh --watch
# Auto-heal mode (restart failed agents)
./scripts/a2a_health.sh --auto-heal
```
### 3. Launch Dashboard
```bash
npm run dashboard
```
### 4. Scale Workers
```bash
# Check current scale
./scripts/a2a_scale.sh status
# Scale up/down
./scripts/a2a_scale.sh up 2
./scripts/a2a_scale.sh down 1
# Auto-scaling mode
./scripts/a2a_scale.sh auto
```
## 📖 P0.2 Communication Protocol
All inter-agent communication follows the P0.2 protocol:
```bash
# Message format
tmux send-keys -t $PANE_ID 'MESSAGE' && sleep 0.5 && tmux send-keys -t $PANE_ID Enter
```
### Message Format
```
[Agent] Status: Content
```
Status types:
- `開始` (Started)
- `進行中` (Working)
- `完了` (Complete)
- `エラー` (Error)
- `待機` (Waiting)
### Agent Relay
```
[FromAgent→ToAgent] Action: Detail
```
## 🔧 Configuration
### Environment Variables
```bash
# Source after bootstrap
source ~/.miyabi/a2a_env.sh
# Or set manually
export MIYABI_CONDUCTOR_PANE="%101"
export MIYABI_CODEGEN_PANE="%102"
export MIYABI_REVIEW_PANE="%103"
export MIYABI_PR_PANE="%104"
export MIYABI_DEPLOY_PANE="%105"
export A2A_SESSION_NAME="a2a"
```
### State File
State is persisted at `~/.miyabi/a2a_state.json`
```bash
# View state
npm run state -- status
# View metrics
npm run state -- metrics
# Create snapshot
npm run state -- snapshot
```
## 🧠 Smart Routing
Tasks are automatically classified and routed:
```bash
# Classify a task
npm run router -- classify "Fix login bug" bug P1
# Get routing decision
npm run router -- route "Add dark mode" feature P2
```
### Routing Rules
| Task Type | Complexity | Route |
|-----------|------------|-------|
| Hotfix P0 | Any | CodeGen → Deploy (fast-track) |
| Docs | Any | CodeGen → PR (skip review) |
| Trivial | Any | CodeGen → PR → Deploy |
| Complex | High | CodeGen → Review × 2 → PR → Deploy |
| Standard | Medium | CodeGen → Review → PR → Deploy |
## 🤖 Agent Roles
| Agent | Japanese | Role |
|-------|----------|------|
| Conductor | 指揮郎 (しきろう) | Task orchestration, progress tracking |
| CodeGen | 楓 (かえで) | Code implementation |
| Review | 桜 (さくら) | Code review, quality check |
| PR | 椿 (つばき) | Pull request management |
| Deploy | 牡丹 (ぼたん) | Deployment, health checks |
## 📁 Project Structure
```
a2a/
├── bin/
│ └── a2a.js # CLI entry point
├── scripts/
│ ├── a2a_bootstrap.sh # System startup
│ ├── a2a_health.sh # Health monitoring
│ └── a2a_scale.sh # Dynamic scaling
├── src/
│ ├── index.ts # Module exports
│ ├── state.ts # State management
│ ├── router.ts # Smart routing
│ └── dashboard.ts # Monitoring UI
├── a2a.sh # Core communication library
├── CLAUDE.md # Agent instructions
└── package.json
```
## 🔌 Integration with Claude Code
Add to your project's `CLAUDE.md`:
```markdown
## A2A Communication
This project uses A2A for multi-agent orchestration.
Source the environment:
\`\`\`bash
source ~/.miyabi/a2a_env.sh
\`\`\`
Send messages to Conductor:
\`\`\`bash
tmux send-keys -t $MIYABI_CONDUCTOR_PANE '[Agent] 完了: Task done' && sleep 0.5 && tmux send-keys -t $MIYABI_CONDUCTOR_PANE Enter
\`\`\`
```
## 📜 License
MIT License - see [LICENSE](LICENSE) file.
## 🤝 Contributing
Contributions are welcome! Please read our contributing guidelines before submitting PRs.
## 🙏 Acknowledgments
Built for use with [Claude Code](https://claude.ai/code) by Anthropic.
---
**Made with 🤖 by the Miyabi Team**
