ensemble

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

Ensemble orchestrates AI agents into collaborative teams. Out of the box it pairs Claude Code + Codex — they 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
• Claude Code and Codex CLIs installed

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.

Supported Agents

The default team is Claude Code (lead) + Codex (worker). This is the tested, production-ready combination.

Agent	Status	How to use
Claude Code + Codex	Fully tested	Default — just run /collab or collab-launch.sh
Gemini CLI	Experimental	Add explicitly (see below)
Aider	Untested	Add explicitly (see below)
Any CLI tool	Via agents.json	Add a custom agent

Using a different team composition

Three ways to change which agents are on your team:

1. Name them in your /collab prompt:

/collab "Review the auth module with gemini and claude"

2. Use the --agents flag with collab-launch.sh:

# First agent = lead, rest = workers
./scripts/collab-launch.sh "$(pwd)" "Security audit" codex,claude,gemini

3. Specify agents in the API call:

curl -X POST http://localhost:23000/api/ensemble/teams \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-team",
    "description": "Security audit",
    "agents": [
      { "program": "codex", "role": "lead" },
      { "program": "claude", "role": "worker" },
      { "program": "gemini", "role": "worker" }
    ],
    "workingDirectory": "'$(pwd)'"
  }'

Note on Gemini: Gemini CLI can join teams and send messages, but is experimental. It may stop responding due to free-tier rate limits or internal agent delegation issues in Gemini's TUI. For best results, configure a paid API key via gemini /auth.

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