🎼 AWKit Symphony

Multi-Agent Orchestration for AI Coding Assistants

Symphony coordinates multiple AI agents working on the same codebase — managing tasks, preventing file conflicts, and providing real-time visibility through a dashboard.

✨ Features

| Feature | Description | |---------|-------------| | Task Management | Create, assign, track tasks with priority & acceptance criteria | | Git Isolation | Auto worktree/clone per task — agents work on separate branches | | File Locking | Pessimistic locking prevents two agents from editing the same file | | Merge Pipeline | Auto-rebase + fast-forward merge when tasks complete | | MCP Server | 14 tools for IDE integration via Model Context Protocol | | Dashboard | Real-time Kanban board, agent status, events feed | | Context Bus | Event pub/sub — agents notify each other of changes |

🚀 Quick Start

# Install
cd symphony
npm install

# Start dashboard (port 3100)
npm run dev

# Or use CLI
node cli/index.js status
node cli/index.js task list

📋 CLI Commands

# System
symphony status                        # Show system status
symphony start                         # Start dashboard server
symphony dashboard                     # Open dashboard in browser

# Tasks
symphony task list [-s ready]          # List tasks (filter by status)
symphony task create "Feature X" -p 1  # Create task (priority 1-3)
symphony task show <id>                # Show task details

# Workspaces
symphony workspace list                # List active workspaces
symphony workspace create <task-id>    # Create workspace for task
symphony workspace merge <task-id>     # Auto-merge completed task
symphony workspace clean               # Remove merged workspaces

# File Locks
symphony lock list                     # Show active locks
symphony lock release <file>           # Force-release stuck lock

# MCP Server
symphony mcp-serve [-n "Agent Name"]   # Start MCP server (stdio)

🔌 MCP Integration

Add to your IDE's MCP config:

{
  "mcpServers": {
    "symphony": {
      "command": "node",
      "args": ["/path/to/symphony/mcp/server.js"],
      "env": {
        "SYMPHONY_AGENT_NAME": "my-agent"
      }
    }
  }
}

Available MCP Tools (14)

| Tool | Description | |------|-------------| | symphony_available_tasks | List available tasks | | symphony_claim_task | Claim a task (get workspace + branch) | | symphony_report_progress | Report progress (0-100%) | | symphony_complete_task | Complete task + trigger merge | | symphony_abandon_task | Abandon a task | | symphony_check_files | Check file lock status | | symphony_lock_files | Lock files for editing | | symphony_unlock_files | Release file locks | | symphony_broadcast | Broadcast event to other agents | | symphony_events | Query context bus events | | symphony_status | Get system status | | symphony_create_task | Create a new task | | symphony_workspace_status | Get workspace info + diff stats | | symphony_merge_task | Run auto-merge pipeline |

🏗️ Architecture

symphony/
├── core/                    # Engine
│   ├── db.js                # SQLite (WAL mode)
│   ├── task-manager.js      # Task CRUD + state machine
│   ├── workspace-manager.js # Git worktree lifecycle
│   ├── merge-pipeline.js    # Auto-rebase + merge
│   ├── file-lock-manager.js # Pessimistic file locking
│   ├── context-bus.js       # Event pub/sub
│   └── orchestrator.js      # Agent dispatch + state
├── mcp/                     # MCP Server
│   ├── server.js            # stdio transport
│   ├── index.js             # Tool registry (14 tools)
│   └── tools/               # Tool implementations
├── cli/                     # CLI
│   └── index.js             # Commander.js commands
├── app/                     # Dashboard (Next.js)
│   ├── page.js              # Kanban + status + events
│   └── api/                 # REST API routes
└── lib/
    └── core.mjs             # ESM bridge for Turbopack

⚙️ Configuration

Edit symphony.config.js:

module.exports = {
    port: 3100,
    maxAgents: 3,
    workspace: {
        type: 'hybrid',       // 'worktree' | 'clone' | 'hybrid'
        cloneThreshold: 30,   // files > 30 → full clone
    },
    git: {
        autoMerge: true,
        targetBranch: 'main',
        branchPrefix: 'symphony/',
    },
    locks: {
        strategy: 'pessimistic',
        autoRelease: 3600,    // seconds
    },
};

📊 Dashboard

The dashboard runs on http://localhost:3100 and provides:

• Kanban Board — Tasks by status (Ready → In Progress → Review → Done)
• Agent Panel — Connected agents with live status
• Events Feed — Real-time context bus events
• Lock Panel — Active file locks with force-release
• Stats Bar — Task counts and system health

🔄 Task Lifecycle

Ready → Claimed → In Progress → Review → Done
  │                                        │
  └─── Abandoned ◀────────────────────────┘

1. Create task via CLI or dashboard
2. Agent claims via MCP → gets isolated workspace + branch
3. Agent works → reports progress, locks files, broadcasts events
4. Agent completes → triggers auto-merge pipeline
5. Merge → rebase onto main, fast-forward, cleanup workspace

📦 Tech Stack

• Runtime: Node.js
• Database: SQLite (via better-sqlite3, WAL mode)
• Dashboard: Next.js 16 + React 19
• MCP: @modelcontextprotocol/sdk
• CLI: Commander.js
• Git: Native git commands (worktree, rebase, merge)