ensemble

Multi-agent collaboration engine — AI agents that work as one.

Ensemble orchestrates multiple AI agents (Claude Code, Codex, Aider) into collaborative teams that communicate, share findings, and solve problems together in real time. Built on tmux-based session management for transparent, observable agent interactions.

Status: Experimental developer tool. macOS and Linux only.

Features

• Team orchestration — Spawn multi-agent teams with a single command
• Real-time messaging — Agents communicate via a structured message bus
• TUI monitor — Watch agent collaboration live from your terminal
• Auto-disband — Intelligent completion detection ends teams when work is done
• Multi-host support — Run agents across local and remote machines
• CLI & HTTP API — Full control via command line or REST endpoints

Full documentation →

Quick Start

Prerequisites

• Node.js 18+, Python 3.6+, tmux, curl
• At least one AI agent CLI installed (claude, codex, or aider)

Note: Currently only Claude Code + Codex is actively tested. Aider and Gemini support is experimental.

Install & Run

git clone https://github.com/michelhelsdingen/ensemble.git
cd ensemble
npm install

# Start the server (keep this running)
npm run dev

Verify (in a second terminal)

curl http://localhost:23000/api/v1/health
# → {"status":"healthy","version":"1.0.0"}

Create your first team

# Via CLI
npx ensemble status

# Via API — create a team of two agents
curl -X POST http://localhost:23000/api/ensemble/teams \
  -H "Content-Type: application/json" \
  -d '{
    "name": "review-team",
    "description": "Review the authentication module",
    "agents": [
      { "program": "claude", "role": "lead" },
      { "program": "codex", "role": "worker" }
    ],
    "workingDirectory": "'$(pwd)'"
  }'

# Watch the collaboration live
npx ensemble monitor --latest

# Steer the team
npx ensemble steer <team-id> "focus on the auth module"

Or use the all-in-one collab script:

./scripts/collab-launch.sh "$(pwd)" "Review the authentication module"

Claude Code: /collab command

Ensemble ships with a skill for Claude Code. Once installed, just type:

/collab "Review the auth module for security issues"

Claude spawns a Codex + Claude team, shows their conversation live in your terminal, and presents a summary when done. One-command setup:

./scripts/setup-claude-code.sh

This installs the skill, configures permissions, and verifies prerequisites. See the full setup guide for details.

How It Works

1. Create a team — Define agents and their task via API or CLI
2. Agents spawn — Each agent gets a tmux session with the task prompt
3. Communication — Agents use team-say/team-read scripts to exchange messages
4. Monitor — Watch the collaboration unfold in real-time via the TUI monitor
5. Auto-disband — When agents signal completion, results are summarized and persisted

Configuration

Copy .env.example to .env and adjust as needed. Key variables:

Variable	Default	Description
ENSEMBLE_PORT	23000	Server port
ENSEMBLE_URL	http://localhost:23000	CLI target URL
ENSEMBLE_DATA_DIR	~/.ensemble	Data directory
ENSEMBLE_CORS_ORIGIN	localhost only	Allowed CORS origins

See full configuration docs for all options including Telegram notifications, multi-host setup, and agent customization.

Documentation

• Getting Started — Prerequisites, install, first team
• Configuration — Environment variables, agents, hosts
• API Reference — All HTTP endpoints
• CLI Reference — Commands and monitor keybindings
• Collab Scripts — Shell scripts for automation
• Architecture — How it all fits together

License

MIT