multiagents

Multi-agent orchestration platform for Claude Code, Codex CLI, and Gemini CLI. Enables AI agents to discover each other, communicate in real-time, coordinate file edits, and work as a team on shared codebases.

Built on MCP (Model Context Protocol).

What It Does

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ Claude Code  │     │  Codex CLI  │     │ Gemini CLI  │
│ (Engineer)   │     │ (Reviewer)  │     │ (Designer)  │
└──────┬───────┘     └──────┬──────┘     └──────┬──────┘
       │   MCP (stdio)      │  CodexDriver       │
       └────────────┬───────┴────────────────────┘
                    │
            ┌───────▼────────┐
            │  Broker Daemon  │  SQLite + HTTP on localhost:7899
            │  (singleton)    │
            └───────┬────────┘
                    │
            ┌───────▼────────┐
            │  Orchestrator   │  MCP server for Claude Desktop
            │  (team manager) │  Spawns agents, forwards messages,
            └────────────────┘  monitors progress, auto-restarts

Peer discovery: agents find each other via list_peers
Real-time messaging: instant for Claude (channel push), <3s for Codex (mid-turn steer), 1-3s for Gemini (piggyback)
Role assignment: assign_role, rename_peer at runtime
File coordination: exclusive locks + ownership zones prevent conflicts
Task lifecycle: idle → working → done_pending_review → addressing_feedback → approved → released
Review loops: signal_done → submit_feedback → fix → re-review → approve
Shared knowledge: persistent key-value store for architectural decisions, discovered patterns, and project context — prevents context drift across agents
Persistent sessions: survive agent restarts, full message history
TUI dashboard: real-time monitoring with 5 tabs (agents, messages, stats, plan, files)
Auto-restart: crashed agents respawn with handoff context
Graceful shutdown: broker and orchestrator kill all managed processes on exit

Quick Start

# Install globally
bun install -g multiagents

# Setup (detects CLIs, configures MCP servers, starts broker)
multiagents setup

# Restart your Claude Code / Codex / Gemini sessions to load MCP tools

# Monitor
multiagents dashboard

From Claude Desktop (Orchestrator)

Ask Claude to create a team:

"Create a team of 3 agents: a Claude engineer, a Codex reviewer, and a Gemini designer. Build a calculator web app in TypeScript."

The orchestrator handles everything: spawning agents, assigning roles, creating slots, launching the dashboard, and forwarding messages between agents.

Agent Support

Agent	Delivery Mechanism	Latency	Config
Claude Code	Channel push notifications	Instant	`~/.claude/settings.json`
Codex CLI	CodexDriver (`codex app-server`)	<3s mid-turn, 3-9s between turns	`~/.codex/config.toml`
Gemini CLI	Piggyback on MCP tool responses	1-3s	`~/.gemini/settings.json`

Codex Integration (CodexDriver)

Codex CLI uses the app-server protocol — a JSON-RPC stdio interface with threads, turns, and rich notifications. The orchestrator uses a CodexDriver that:

Spawns a persistent codex app-server process with JSON-RPC handshake
Creates a thread (thread/start) and drives turns (turn/start) for task execution
Injects messages mid-turn via turn/steer — no waiting for the current turn to finish
Interrupts stuck turns via turn/interrupt when agents go idle for >60s
Auto-approves all server-initiated requests (command execution, file changes, MCP elicitations)
Tracks token usage from turn/completed notifications

The orchestrator drives Codex turns: the forwarding loop polls the broker every 3s. If Codex has an active turn, messages are steered in instantly. If idle, a new turn is started via driver.reply().

Task State Machine

Every agent slot has a task_state that governs the review/approval workflow:

                    ┌──────────── (reviewer/QA roles) ────────────┐
                    │                                              ▼
idle ──► working ──► done_pending_review ──► addressing_feedback  approved ──► released
                         │                         │                ▲
                         │                         └────────────────┘
                         └──────────► approved ─────────────────────┘

idle → working: Auto-transitions when agent calls set_summary or produces first output
working → done_pending_review: Agent calls signal_done
working → approved: Reviewer/QA agents auto-approve on signal_done (they don't need external review)
done_pending_review → addressing_feedback: Reviewer calls submit_feedback(actionable=true)
addressing_feedback → done_pending_review: Agent fixes issues and calls signal_done again
done_pending_review → approved: Reviewer calls approve
approved → released: Orchestrator calls release_agent

Agents cannot disconnect until explicitly released. This ensures the review loop completes.

MCP Tools (Available to All Agents)

Tool	Description
`list_peers`	Discover agents (filter by scope, type)
`send_message`	Send text message to a peer
`check_messages`	Poll for new messages
`set_summary`	Update your status (visible to peers and dashboard)
`check_team_status`	See all agents: roles, states, summaries
`get_plan` / `update_plan`	Track team progress against the plan
`signal_done`	Signal task completion (triggers review)
`submit_feedback`	Send review feedback (actionable or informational)
`approve`	Approve a teammate's work
`assign_role` / `rename_peer`	Assign roles and names
`acquire_file` / `release_file`	File lock management
`view_file_locks`	See active locks and ownership zones
`get_history`	Query session message history
`store_knowledge`	Store shared knowledge (decisions, patterns, conventions)
`query_knowledge`	Query knowledge entries by key or category
`remove_knowledge`	Remove outdated knowledge entries

Orchestrator Tools (Claude Desktop)

Tool	Description
`create_team`	Spawn a team with roles, file ownership, and a plan
`get_team_status`	Live status of all agents with completion tracking
`broadcast_to_team`	Message all agents at once
`direct_agent`	Message a specific agent by name/role
`add_agent` / `remove_agent`	Add or remove agents mid-session
`control_session`	Pause/resume all or individual agents
`adjust_guardrail`	View or change session limits
`release_agent` / `release_all`	Release agents to disconnect
`get_session_log`	Full message history
`list_sessions` / `resume_session`	List and resume previous sessions
`end_session` / `delete_session`	Archive or permanently delete
`cleanup_dead_slots`	Remove stale disconnected slots
`get_guide`	Built-in documentation and tutorials

Sessions

Sessions persist across agent restarts:

multiagents session create "Auth Feature"    # Create session
multiagents session list                     # List all sessions
multiagents session resume auth-feature      # Resume (respawns agents)
multiagents session pause                    # Pause all agents
multiagents session delete auth-feature      # Permanently delete

File Coordination

Ownership Zones (static, zero overhead):

create_team assigns: Engineer owns src/**, Reviewer owns tests/**

File Locks (dynamic, for shared files):

Engineer: acquire_file("package.json", "adding dependency")
→ Lock acquired, auto-expires in 5 minutes

Shared Knowledge Store

Agents share a persistent key-value store to prevent context drift — the #1 failure mode in multi-agent systems.

Engineer:  store_knowledge("auth-pattern", "JWT with refresh rotation", category="decision")
Designer:  query_knowledge()  →  sees the decision before designing auth UI
Reviewer:  query_knowledge(category="decision")  →  reviews against team decisions

Categories: decision, convention, discovery, blocker, context

Knowledge persists across agent restarts and is scoped to the session. Agents are instructed to query knowledge on startup and store decisions as they work.

Guardrails

Session monitoring stats and enforced limits:

Guardrail	Default	Scope	Action
Restart Limit	5	Per agent	Stop (prevents flapping)
Session Duration	Monitor	Session	Observe
Total Messages	Monitor	Session	Observe
Active Agents	Monitor	Session	Observe
Longest Idle	Monitor	Per agent	Observe

Adjustable from the TUI dashboard (+/- keys) or via adjust_guardrail tool.

Web Dashboard

multiagents web [session-id]

Real-time web dashboard on localhost:7900 with live WebSocket updates. Auto-opens in browser when a team is created via the orchestrator. 6-tab interface:

Agents: agent cards with connection status, task state, role, summaries, token usage
Messages: live message feed with type badges and sender names
Plan: task progress with completion bar and assignee labels
Knowledge: shared knowledge entries with categories and provenance
Files: file locks and ownership zones
Stats: session metrics (connected agents, working, tokens) and guardrail bars

Dark theme, responsive layout, keyboard shortcuts (1-6 to switch tabs).

TUI Dashboard

multiagents dashboard [session-id]

5-tab terminal interface (same data, ANSI rendering):

[1] Agents: connection status, task state, summaries
[2] Messages: auto-scrolling message log with filtering
[3] Stats: guardrail monitoring and adjustment
[4] Plan: progress tracking with completion percentage
[5] Files: file locks and ownership zones

Keys: 1-5 switch tabs, j/k scroll, p pause all, r resume all, +/- adjust guardrails, q quit.

CLI Commands

multiagents setup                     Interactive setup wizard
multiagents web [session-id]         Web dashboard (localhost:7900)
multiagents dashboard [session-id]    TUI dashboard
multiagents session <sub>             Session management (create/list/resume/pause/delete)
multiagents send <target> <msg>       Send message to agent
multiagents peers                     List connected agents
multiagents status                    Broker health + peers
multiagents broker start|stop|status  Manage broker daemon
multiagents install-mcp               Configure MCP servers
multiagents help [command]            Detailed help

Architecture

multiagents/
├── broker.ts               SQLite broker daemon (sessions, slots, locks, messages, knowledge, guardrails)
├── server.ts               MCP server entry point (dispatches to adapter by --agent-type)
├── cli.ts                  CLI entry point
├── shared/
│   ├── types.ts            Type definitions (Peer, Slot, Session, Message, TaskState...)
│   ├── broker-client.ts    HTTP client for broker API
│   ├── constants.ts        Ports, intervals, thresholds
│   ├── summarize.ts        Auto-summary generation
│   └── utils.ts            Shared utilities
├── adapters/
│   ├── base-adapter.ts     Abstract MCP adapter (tools, registration, polling)
│   ├── claude-adapter.ts   Claude Code adapter (channel push delivery)
│   ├── codex-adapter.ts    Codex adapter (piggyback + file inbox delivery)
│   ├── gemini-adapter.ts   Gemini adapter (piggyback + file inbox delivery)
│   └── role-practices.ts   Role-specific best practices injection
├── orchestrator/
│   ├── orchestrator-server.ts  Orchestrator MCP server (team management)
│   ├── codex-driver.ts     CodexDriver: persistent codex app-server via JSON-RPC (steer/interrupt)
│   ├── launcher.ts         Agent spawning (CLI args, MCP configs, CodexDriver)
│   ├── monitor.ts          Process monitoring (stdout parsing, token tracking)
│   ├── recovery.ts         Crash recovery (flap detection, respawn with context)
│   ├── progress.ts         Team status aggregation
│   ├── session-control.ts  Pause/resume/broadcast
│   ├── guardrails.ts       Guardrail enforcement
│   └── guide.ts            Built-in documentation
└── cli/
    ├── commands.ts         CLI command router
    ├── dashboard.ts        TUI dashboard (ANSI, no dependencies)
    ├── session.ts          Session management commands
    ├── setup.ts            Interactive setup wizard
    └── install-mcp.ts      MCP server configuration

Process Lifecycle

Graceful Shutdown

Broker (SIGINT/SIGTERM): kills all registered peer processes, closes SQLite cleanly
Orchestrator (SIGINT/SIGTERM): kills all managed agent processes and CodexDriver instances
Adapters (SIGINT/SIGTERM): unregister from broker, release file locks

Orphan Prevention

Broker's cleanStalePeers runs every 30s: removes dead peer records, kills orphan processes without sessions
CodexDriver uses .multiagents/.driver-mode sentinel file to prevent internal MCP adapters from creating ghost slots
Session delete/end handlers kill both regular processes and CodexDriver instances
Flap detection stops auto-restart after 3 crashes in 5 minutes

Environment Variables

Variable	Default	Purpose
`MULTIAGENTS_PORT`	`7899`	Broker HTTP port
`MULTIAGENTS_DB`	`~/.multiagents/peers.db`	SQLite database path
`MULTIAGENTS_SESSION`	-	Session ID (set by orchestrator)
`MULTIAGENTS_SLOT`	-	Slot ID (set by orchestrator)
`MULTIAGENTS_ROLE`	-	Agent role (set by orchestrator)
`MULTIAGENTS_NAME`	-	Agent display name (set by orchestrator)
`MULTIAGENTS_DRIVER_MODE`	-	Skip adapter registration (set by CodexDriver)

Requirements

Bun runtime (v1.1+)
At least one of: Claude Code, Codex CLI, or Gemini CLI

License

MIT

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

multiagents

What It Does

Quick Start

From Claude Desktop (Orchestrator)

Agent Support

Codex Integration (CodexDriver)

Task State Machine

MCP Tools (Available to All Agents)

Orchestrator Tools (Claude Desktop)

Sessions

File Coordination

Shared Knowledge Store

Guardrails

Web Dashboard

TUI Dashboard

CLI Commands

Architecture

Process Lifecycle

Graceful Shutdown

Orphan Prevention

Environment Variables

Requirements

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

multiagents

What It Does

Quick Start

From Claude Desktop (Orchestrator)

Agent Support

Codex Integration (CodexDriver)

Task State Machine

MCP Tools (Available to All Agents)

Orchestrator Tools (Claude Desktop)

Sessions

File Coordination

Shared Knowledge Store

Guardrails

Web Dashboard

TUI Dashboard

CLI Commands

Architecture

Process Lifecycle

Graceful Shutdown

Orphan Prevention

Environment Variables

Requirements

License