docs: clarify default team (Claude+Codex) and how to add other agents

Make it idiot-proof: the default is Claude Code + Codex everywhere.
Other agents (Gemini, Aider, custom) are clearly secondary with
explicit instructions on how to use them (prompt, --agents flag, API).
Removes confusing 4-agent listing from opening paragraph.

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

Author: 3 people

README.md

@@ -2,7 +2,7 @@
 
 **Multi-agent collaboration engine** — AI agents that work as one.
 
-Ensemble orchestrates multiple AI agents (Claude Code, Codex, Gemini, 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.
+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.
 
@@ -22,9 +22,7 @@ Ensemble orchestrates multiple AI agents (Claude Code, Codex, Gemini, Aider) int
 ### Prerequisites
 
 - Node.js 18+, Python 3.6+, [tmux](https://github.com/tmux/tmux), curl
-- At least one AI agent CLI installed (`claude`, `codex`, `gemini`, or `aider`)
-
-> **Agent support:** **Claude Code + Codex** is fully tested and production-ready. **Gemini CLI** is supported but experimental — it can join teams and communicate, but may become unresponsive due to rate limits or internal agent delegation in Gemini's TUI. **Aider** support is untested.
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [Codex](https://github.com/openai/codex) CLIs installed
 
 ### Install & Run
 
@@ -92,6 +90,50 @@ Claude spawns a Codex + Claude team, shows their conversation live in your termi
 
 This installs the skill, configures permissions, and verifies prerequisites. See the [full setup guide](https://michelhelsdingen.github.io/ensemble/configuration#claude-code-integration) 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](https://michelhelsdingen.github.io/ensemble/configuration#adding-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`:**
+```bash
+# First agent = lead, rest = workers
+./scripts/collab-launch.sh "$(pwd)" "Security audit" codex,claude,gemini
+```
+
+**3. Specify agents in the API call:**
+```bash
+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

docs/configuration.md

@@ -97,12 +97,29 @@ The agent must support `team-say` and `team-read` shell commands in its PATH for
 
 ### Supported agents
 
-| Agent | Status | Notes |
-|---|---|---|
-| **Claude Code** | Fully tested | Reliable, supports `sendKeys` input |
-| **Codex** | Fully tested | Requires `pasteFromFile` input and `--full-auto` flag |
-| **Gemini CLI** | Experimental | Uses `pasteFromFile` with `--yolo` flag. May become unresponsive due to free-tier rate limits or Gemini's internal agent delegation. If Gemini hits a rate limit, an interactive dialog appears in the TUI that blocks further message processing. Works best with a paid API key configured via `/auth`. |
-| **Aider** | Untested | Basic config included in `agents.json` |
+The default team is **Claude Code (lead) + Codex (worker)**. This is the fully tested combination.
+
+| Agent | Status | Default? | Notes |
+|---|---|---|---|
+| **Claude Code** | Fully tested | Yes (worker) | Uses `sendKeys` input |
+| **Codex** | Fully tested | Yes (lead) | Uses `pasteFromFile` input, `--full-auto` flag |
+| **Gemini CLI** | Experimental | No | Uses `pasteFromFile`, `--yolo` flag. May stop responding due to free-tier rate limits or internal TUI issues. Use a paid API key (`gemini /auth`) for best results. |
+| **Aider** | Untested | No | Basic config included in `agents.json` |
+| **Any CLI tool** | Custom | No | See [Adding a custom agent](#adding-a-custom-agent) |
+
+#### How to use a non-default agent
+
+You don't need to change any config. Just tell ensemble which agents you want:
+
+```bash
+# Via collab-launch.sh (first agent = lead, rest = workers)
+./scripts/collab-launch.sh "$(pwd)" "Security audit" codex,claude,gemini
+
+# Via /collab in Claude Code — name the agents in your prompt
+/collab "Review auth with gemini and claude"
+
+# Via API — specify the agents array
+```
 
 ### Input methods
 

docs/getting-started.md

@@ -15,7 +15,7 @@ title: Getting Started
 | **Python 3.6+** | Used by collab scripts for message parsing |
 | **curl** | Used in scripts and examples |
 | **macOS or Linux** | tmux and shell scripts require a Unix environment |
-| **At least one AI agent CLI** | e.g. `claude`, `codex`, `aider`, `gemini` |
+| **Claude Code + Codex CLIs** | The default agent pair ([Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex)) |
 
 > **Platform support:** Ensemble runs on macOS and Linux only. Windows (including WSL) is not tested or supported.
 
@@ -34,32 +34,24 @@ tmux -V
 
 ### Install AI agent CLIs
 
-Ensemble supports any CLI-based AI agent. You need at least one installed:
+You need **both Claude Code and Codex** installed (the default team):
 
 ```bash
-# Claude Code (Anthropic) — recommended
+# Claude Code (Anthropic)
 npm install -g @anthropic-ai/claude-code
 
 # Codex (OpenAI)
 npm install -g @openai/codex
-
-# Gemini CLI (Google) — experimental
-npm install -g @anthropic-ai/gemini-cli  # or follow https://github.com/anthropics/gemini-cli
-
-# Aider (Python-based) — untested
-pip install aider-chat
 ```
 
-> **Tested combinations:** Claude Code + Codex is fully tested and production-ready. Gemini CLI can join teams and communicate, but is experimental — it may become unresponsive due to free-tier rate limits or internal agent delegation issues. Aider support is untested.
+> **Want to use other agents?** Ensemble is agent-agnostic — you can add Gemini CLI (experimental), Aider, or any CLI tool via `agents.json`. See [Configuration → Supported Agents](configuration#supported-agents) for details.
 
 Each agent CLI manages its own API keys. Make sure they're configured before running ensemble:
 
 | Agent | Auth setup | Where to get a key |
 |---|---|---|
 | **Claude Code** | Run `claude auth login` (opens browser) or set `ANTHROPIC_API_KEY` | [console.anthropic.com](https://console.anthropic.com/) |
 | **Codex** | Set `OPENAI_API_KEY` in your shell profile | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) |
-| **Gemini CLI** | Run `gemini /auth` to configure API key, or use free tier (rate-limited) | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) |
-| **Aider** | Set `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` | See links above |
 
 ```bash
 # Example: add to your ~/.zshrc or ~/.bashrc

docs/index.md

@@ -8,9 +8,11 @@ title: Home
 
 **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.
+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.
 
 > **Status:** Experimental developer tool. Not a production framework (yet).
+>
+> **Default team:** Claude Code (lead) + Codex (worker). You can [add other agents](configuration#supported-agents) like Gemini (experimental) or any custom CLI tool.
 
 ---
 
@@ -56,11 +58,10 @@ See [Configuration → Claude Code integration](configuration#claude-code-integr
 
 ## Key features
 
-- **Team orchestration** — Spawn multi-agent teams with a single API call
+- **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
+- **Extensible** — Add any CLI-based AI agent via `agents.json`
 - **Multi-host support** — Run agents across local and remote machines
-- **Git worktrees** — Each agent works in its own isolated branch
-- **Staged workflows** — Multi-phase plan/execute/verify workflows
 - **Auto-disband** — Intelligent completion detection ends teams when work is done
 - **Telegram notifications** — Get notified when teams finish