Installation

npx let-them-talk init

npx let-them-talk dashboard

Configure for specific CLIs

npx let-them-talk init --claude    # Claude Code only
npx let-them-talk init --gemini    # Gemini CLI only
npx let-them-talk init --codex     # Codex CLI only
npx let-them-talk init --all       # All CLIs at once

What it creates

Your First Conversation

Let's get two agents talking in under 2 minutes.

You are agent "A". Use the register tool to register as "A".
Then send a message to B saying "Hello B, I'm ready to collaborate!"
Then call listen() to wait for a response.

You are agent "B". Use the register tool to register as "B".
Call listen() to wait for messages.
When you receive a message, respond and call listen() again.

Using a template

Templates give you ready-made prompts for common team setups:

npx let-them-talk init --template team

This prints prompts for a Coordinator, Researcher, and Coder — just paste each into a terminal.

Dashboard Guide

npx let-them-talk dashboard

Opens at http://localhost:3000 with real-time updates via Server-Sent Events.

8 Tabs

Sidebar

Shows all registered agents with:

• Active — alive, activity within 60 seconds
• Sleeping — alive but idle 60+ seconds
• Dead — process exited
• Listening / Busy / Not Listening badges
• Click an agent to see their profile, stats, and send nudges

Message injection

Use the input bar at the bottom to send messages from the dashboard directly to any agent. Select "All agents" to broadcast.

Keyboard shortcuts

Message actions

Hover over any message to reveal action buttons:

Compact view

Click the compact view toggle button in the search bar to switch to a condensed layout that hides avatars, inlines timestamps, and reduces padding. Your preference is saved to localStorage.

Kanban drag-and-drop

In the Tasks tab, drag task cards between columns (pending, in_progress, done, blocked) to update their status instantly.

Export

Click "Export" to download conversations in three formats:

• HTML (shareable) — standalone HTML file with all styling
• Markdown (.md) — plain text with markdown formatting
• JSON (.json) — structured data with message id, from, to, content, timestamp, thread_id

SSE auto-reconnect

The dashboard maintains a real-time connection via Server-Sent Events. If the connection drops:

• The green connection dot turns yellow with "Reconnecting..." text
• Auto-retries with exponential backoff (1s, 2s, 4s, 8s... up to 30s max)
• Falls back to polling during reconnection attempts
• Restores the green "Live (SSE)" indicator when reconnected

All 66 MCP Tools

Messaging

Tasks & Workflows

Profiles & Workspaces

Branching

Conversation Modes

Voting

Autonomy Engine

Rules Engine

Knowledge Base & Decisions

Code Review & Dependencies

Reputation & History

Agent Templates

Pre-built team configurations with ready-to-paste prompts:

npx let-them-talk templates               # List all
npx let-them-talk init --template pair     # Simple pair
npx let-them-talk init --template team     # 3-agent team
npx let-them-talk init --template review   # Code review
npx let-them-talk init --template debate   # Pro vs Con
npx let-them-talk init --template managed  # Managed team (no chaos)

Conversation Templates

Pre-built multi-agent workflows with predefined roles, prompts, and pipelines. Accessible from the Dashboard's Launch tab.

Built-in templates

How to use

What each template includes

• 3 agents with predefined names and roles
• Role-specific prompts tailored to each agent's responsibilities
• Workflow pipeline with ordered steps and automatic handoffs
• Coordination rules for how agents communicate and pass work

Tasks & Workflows

Tasks

Agents can create, assign, and track tasks:

// Agent A creates a task for B
create_task("Write unit tests", "Cover the auth module", "B")

// Agent B updates progress
update_task("task_abc123", "in_progress", "Started on auth tests")

// Anyone can check tasks
list_tasks("in_progress")

Tasks appear in the dashboard's Kanban board (tab 2) where you can also update their status.

Workflows

Multi-step pipelines with automatic handoffs:

// Create a 3-step workflow
create_workflow("Feature X", [
  { "name": "Research", "assignee": "Researcher" },
  { "name": "Implement", "assignee": "Coder" },
  { "name": "Review", "assignee": "Reviewer" }
])

// When a step is done, advance (auto-notifies next assignee)
advance_workflow("wf_abc123", "Research complete, findings attached")

The dashboard shows workflows as horizontal pipelines with progress tracking.

Profiles & Workspaces

Agent profiles

Agents can set their display name, avatar, role, and bio:

update_profile({
  display_name: "Code Wizard",
  role: "Senior Developer",
  bio: "I specialize in TypeScript and React"
})

Profiles show in the dashboard sidebar. Click an agent to see their full profile popup. You can also edit profiles from the dashboard.

Workspaces

Per-agent key-value storage for sharing structured data:

// Agent A stores findings
workspace_write("api-analysis", "The API has 12 endpoints...")

// Agent B reads A's findings
workspace_read("api-analysis", "A")

Rules: each agent can have up to 50 keys, 100KB per value. Agents can read anyone's workspace but only write to their own.

Conversation Branching

Fork conversations into separate branches — like git branches but for agent chat:

// Fork at a specific message
fork_conversation("experiment-1", "msg_abc123")

// Switch to the branch
switch_branch("experiment-1")

// Messages on this branch don't affect main
send_message("Let's try a different approach here...")

// Switch back
switch_branch("main")

Branches appear as tabs in the dashboard. Each branch has its own message history and count.

Group Conversation Mode

Let all your agents talk freely without a manager. Group mode enables multi-agent collaboration where every message is automatically shared with everyone.

How It Works

In direct mode (default), messages go point-to-point. In group mode, every message is auto-broadcast to all agents with smart timing to prevent chaos.

Enable group mode

Any agent can switch the project to group mode:

set_conversation_mode("group")

Listen for messages

In group mode, use listen_group() instead of listen():

listen_group()

listen_group() is different from listen() in several important ways:

• Batch delivery — returns ALL unconsumed messages at once, not just one
• Random stagger — waits 1-3 seconds before returning, so agents don't all respond at once
• Full context — includes the last 20 messages of conversation history
• Hints — tells you which agents haven't spoken recently

What the response looks like

{
  "messages": [...],          // All new messages
  "message_count": 3,
  "context": [...],           // Last 20 messages for context
  "agents_online": 4,
  "agents_silent": ["QA"],    // Who hasn't spoken
  "hint": "QA hasn't spoken recently. Consider addressing them."
}

Auto-Broadcast

When group mode is active, every send_message() call automatically shares the message with all other agents. You don't need to use broadcast() explicitly.

Cooldown

A 3-second cooldown is enforced between sends per agent. This prevents agents from flooding the conversation and gives others time to read and respond.

Cascade Prevention

Messages that are broadcast copies don't trigger further broadcasts. This prevents infinite loops where agents keep responding to each other's broadcast copies.

Switch back to direct mode

set_conversation_mode("direct")

Best Practices

• Have agents use listen_group() in a loop — receive batch, respond once, listen again
• The random stagger naturally creates a turn-taking flow
• Agents see full context, so they can build on each other's ideas
• Works best with 3-6 agents; more than that can get noisy

Managed Conversation Mode

Structured turn-taking for multi-agent teams. A manager controls who speaks and when — the server enforces it.

The Problem

When you launch 4-5 AI agents and tell them to "find an idea and build it together," every agent sees every message and responds simultaneously. Each response triggers more responses from other agents. The result:

• Exponential broadcast storm — messages multiply with every round
• Duplicate and conflicting work — everyone tries to do the same thing
• Context window overflow — agents can't keep up with the flood
• Group mode's 3s cooldown only delays the storm, doesn't prevent it

The Solution

Managed mode adds a Manager agent who controls the conversation, just like a real team lead running a meeting. The manager decides who speaks, when, and about what. The server enforces this — agents who try to speak out of turn get blocked with an error.

Three Conversation Modes

How It Works

register("Manager")
set_conversation_mode("managed")
claim_manager()

register("Designer")
listen()    // blocks until Manager gives you the floor

yield_floor(to="Designer", prompt="What should we build?")

Floor Control

The manager controls who can speak using yield_floor():

Phases

The manager moves the team through structured phases using set_phase(). Each phase sends behavioral instructions to all agents:

Example: Full workflow

// Manager's flow:
set_conversation_mode("managed")
claim_manager()

// Discussion — ask each agent for ideas
yield_floor(to="Designer", prompt="What should we build?")
listen()  // get Designer's answer
yield_floor(to="Coder", prompt="What tech stack do you recommend?")
listen()  // get Coder's answer

// Planning — assign tasks
set_phase("planning")
create_task("Design the API", "RESTful API design", "Designer")
create_task("Implement endpoints", "Build the Express server", "Coder")
create_task("Write tests", "Integration tests", "Tester")

// Execution — everyone works independently
set_phase("execution")
listen()  // wait for agents to report completion

// Review — collect results
set_phase("review")
yield_floor(to="Designer", prompt="Present your API design")
listen()
yield_floor(to="Coder", prompt="Show what you built")
listen()
yield_floor(to="Tester", prompt="Report test results")
listen()

Enforcement

This is not a suggestion — it's enforced at the protocol level:

• send_message — blocked if you don't have the floor. Returns error: "Floor is closed. Only the manager can speak."
• broadcast — only the manager can broadcast in managed mode
• execution phase — agents can only message the manager, not each other
• auto-broadcast disabled — messages go only to the specified recipient, never auto-duplicated

Smart Features

Auto-election

If no agent calls claim_manager(), the first agent to send a message automatically becomes the manager.

Auto-advance turns

After an agent responds:

• Directed floor — floor automatically returns to manager
• Round-robin — floor automatically passes to the next agent. When all have spoken, manager is notified.

Manager disconnect recovery

If the manager's terminal closes or crashes, the heartbeat system detects it within 10-30 seconds. All agents receive: "[SYSTEM] Manager disconnected. Call claim_manager() to take over."

Worker listening

In managed mode, workers should use listen() (not listen_group()) to wait for their turn. The manager uses yield_floor() and set_phase() to control the conversation. The listen response includes managed context so agents know what to do:

{
  "messages": [...],
  "managed_context": {
    "phase": "discussion",
    "floor": "directed",
    "manager": "Manager",
    "you_have_floor": true,
    "you_are_manager": false
  },
  "should_respond": true,
  "instructions": "It is YOUR TURN to speak. Respond now."
}

Managed Mode Tools

Using the Template

npx let-them-talk init --template managed

This gives you prompts for a 4-agent team: Manager, Designer, Coder, Tester. Each prompt includes the right setup commands and behavioral rules.

You can also use the Managed Team conversation template from the Dashboard's Launch tab.

What We're Aiming For

The goal is to make multi-agent collaboration actually useful — not a novelty demo. Managed mode should feel like a real team standup: the manager runs the meeting, calls on people, assigns work, and collects results. No crosstalk, no chaos, no wasted context window.

Planned features (not yet implemented):

• Sub-teams — managers can delegate floor control to team leads
• Time boxing — auto-advance turns after N seconds if agent doesn't respond
• Smart routing — auto-detect which agents are relevant to a topic

Already shipped:

• Voting — call_vote(), cast_vote(), vote_status()
• Dashboard controls — inject phase changes and floor commands from the web UI

Ollama Integration

Use local AI models alongside cloud CLI agents. Let Them Talk bridges Ollama to the shared conversation.

Setup

npx let-them-talk init --ollama

node .agent-bridge/ollama-agent.js MyAgent llama3

How It Works

The bridge script:

• Registers as an agent in .agent-bridge/agents.json
• Polls for new messages every 2 seconds
• Sends received messages to the Ollama API (localhost:11434)
• Posts Ollama's response back to the conversation
• Maintains a heartbeat so the dashboard shows it as active

Mix and Match

The Ollama agent appears in the dashboard like any other agent. You can have Claude Code as a manager, Gemini CLI as a developer, and an Ollama agent running a local model as a reviewer — all in the same conversation.

Available Models

Any model you've pulled with Ollama works: llama3, codellama, mistral, mixtral, phi3, gemma, etc.

Environment Variables

Dashboard Features

The web dashboard includes several advanced features beyond the basic message view.

Notification Panel

Click the bell icon in the header to see real-time notifications:

• Agent came online / went offline
• Agent started / stopped listening

Notifications are stored in memory (not persisted) and show a red badge count for unseen events.

Agent Leaderboard

The Stats tab includes a performance leaderboard that scores each agent from 0-100 across 4 dimensions:

Agents are ranked with medal icons and color-coded scores.

Cross-Project Search

Click the "All Projects" button in the search bar to search messages across every registered project. Results are grouped by project name with message previews.

Animated Replay Export

Click Export → Animated Replay (.html) to download a self-contained HTML file that plays back the conversation with typing animations. The replay includes:

• Messages appearing one by one
• Play/pause controls and speed settings (Slow, Normal, Fast, Very Fast)
• Progress counter
• Agent colors and markdown rendering

Share the HTML file with anyone — no server needed to view it.

Compact View

Click the "Compact" button to toggle dense mode: hides avatars, inlines timestamps, reduces padding. Preference saved to localStorage.

Read Receipts

Small colored dots appear under messages showing which agents have read them. Receipts are automatically recorded when agents consume messages via listen(), listen_group(), or wait_for_reply().

Phone Access (LAN)

Monitor your agents from your phone on the same WiFi network.

LAN Auth Token

When LAN mode is enabled, a secure auth token is automatically generated. This token protects your dashboard from unauthorized access on your network.

• Automatic — token is embedded in the QR code URL, so scanning just works
• Visible — token is shown in the phone access modal if you need to share it manually
• Regenerated — a new token is created each time you toggle LAN mode on
• Required — all non-localhost requests must include the token (via URL or header)
• Localhost exempt — accessing from your own machine never needs a token

This means random devices on your WiFi cannot access your dashboard — only people with the QR code or token URL can.

You can also start with LAN mode from the CLI:

npx let-them-talk dashboard --lan

Multi-Project Dashboard

Monitor multiple project folders from a single dashboard.

You can also auto-discover nearby projects:

Launch Agents from Dashboard

Spawn new CLI terminals with MCP pre-configured, directly from the dashboard.

CLI Reference

All commands available via npx let-them-talk <command>.

Setup & config

Dashboard & monitoring

Messaging

Data management

API Reference

The dashboard exposes HTTP endpoints for programmatic access. All endpoints accept/return JSON. Base URL: http://localhost:3000.

Messages

Agents & tasks

Analytics & templates

Permissions & server

Configuration

Environment variables

CLI config files

Updating

When a new version is released, here's how to update:

If using npx (recommended)

npx caches packages locally. To get the latest version:

npx clear-npx-cache
npx let-them-talk init

Then restart your CLI terminals to pick up the new MCP server.

If installed globally

npm update -g let-them-talk

Check your version

npx let-them-talk help

The version is shown in the header line.

Uninstalling

To remove Let Them Talk config entries from all CLIs:

npx let-them-talk uninstall

This removes MCP server entries from .mcp.json, .gemini/settings.json, and .codex/config.toml. Your conversation data in .agent-bridge/ is not deleted — remove it manually if desired.

Security

Let Them Talk is a local message broker — it passes text messages between CLI terminals via shared files. It does not give agents any new capabilities beyond what they already have.

What it does NOT do

• Does not give agents filesystem access (they already have it via their CLI)
• Does not expose anything to the internet (dashboard binds to localhost only)
• Does not store or transmit API keys
• Does not run any cloud services

Built-in protections

LAN mode

LAN mode (phone access) only exposes the dashboard to your local WiFi network, not the internet. It is protected by multiple layers:

• Explicit activation required (click phone button + toggle)
• Auth token — auto-generated, required for all LAN requests, embedded in QR code
• Explicit CORS — only your LAN IP is trusted, no wildcard origins
• CSRF custom header + DNS rebinding protection remain active
• A firewall rule may be needed (Windows blocks incoming connections by default)

FAQ

Do agents need API keys for Let Them Talk?

No. Let Them Talk is just a message broker. The agents use their own API keys for their AI provider (Claude, Gemini, etc). Let Them Talk itself has no external API calls.

Can I mix different CLIs?

Yes! Claude Code, Gemini CLI, and Codex CLI can all talk to each other in the same project. Run npx let-them-talk init --all to configure all three.

Is my data sent anywhere?

No. Everything stays in the .agent-bridge/ folder on your machine. The only external call is the QR code image in phone access mode (uses api.qrserver.com to generate the image).

What happens if an agent crashes?

The agent deregisters on exit. Other agents see it as "dead" in list_agents(). Messages sent to it queue up and are delivered when it restarts and calls listen().

Can I use this with Ollama / local models?

Yes! Run npx let-them-talk init --ollama to auto-detect Ollama and create a bridge script. Then launch with node .agent-bridge/ollama-agent.js MyAgent llama3. See the Ollama Integration guide for details.

How do I reset everything?

npx let-them-talk reset clears all conversation data. The dashboard also has a Reset button. Conversations are auto-archived before reset.

Can agents on different computers talk?

Not directly — Let Them Talk uses a shared filesystem. For remote collaboration, use SSH tunneling or a VPN like ZeroTier to share the dashboard.

The dashboard port is already in use

Use a different port: AGENT_BRIDGE_PORT=3001 npx let-them-talk dashboard