agentwisper

Overview

agentwisper is a message broker that lets AI agents coordinate through the Model Context Protocol. Any MCP client — Claude Code, Codex, or a custom agent — registers with the broker, discovers active peers, and exchanges messages with no custom protocol or shared runtime. Agents group into persistent squads with role-based membership for long-running work, or ad-hoc teams for cross-squad tasks, and communicate through direct point-to-point messaging, RPC request/response, or topic-based pub/sub. The broker buffers messages for offline agents and restores identity on reconnect, so an agent can drop and resume without losing state or subscriptions. It runs as a single process backed by SQLite in WAL mode and exposes 26 MCP tools across 6 categories over streamable-http, with no external services or message queues to operate.

Installation

pip install agentwisper

Then start the broker:

agentwisper-broker start

Architecture

                    MCP (streamable-http)
                         |
                    +----+----+
                    |   MCP   |
                    |  Server |
                    +----+----+
                         |
+------------------------+------------------------+
|                  Broker Core                      |
|  +----------+ +-----------+ +----------------+   |
|  |  Router  | |   Agent   | |     Squad      |   |
|  | P2P/RPC/ | | Registry  | |   Manager      |   |
|  |  PubSub  | |           | |                |   |
|  +----+-----+ +-----+-----+ +------+---------+   |
|                                                   |
|  +---------------------------------------------+ |
|  |        Persistence Layer (SQLite WAL)        | |
|  |  messages | agents | squads | subscriptions | |
|  +---------------------------------------------+ |
+---------------------------------------------------+
         |              |              |
    Claude Code      Codex       Custom Agent

Features

• Central Broker -- single-process message broker with SQLite WAL persistence
• 26 MCP Tools -- agent management, squad operations, ad-hoc teams, messaging, subscriptions, health
• Communication Patterns -- P2P direct messaging, RPC request/response, Pub/Sub topic subscriptions
• Squad Model -- persistent named groups with role-based membership and shared state
• Ad-hoc Teams -- lightweight temporary groups created from multiple squads
• Message Polling & Wait -- agents poll or block-wait for messages with anyio.Event zero-latency notification
• Retention Policy -- automatic cleanup of expired messages and stale agents

Quick Start

# Install dependencies
uv sync

# Start the broker on port 8000
uv run agentwisper-broker start

For the full walkthrough, see QUICKSTART.md.

Client Configuration

Claude Code (recommended: plugin)

Install the agentwisper plugin:

claude plugin add <marketplace>/agentwisper

This provides 14 slash commands (/agentwisper:register, /agentwisper:send, etc.) and connects to the broker automatically.

Claude Code (manual HTTP config)

Add to .claude/settings.json or .mcp.json:

{
  "mcpServers": {
    "agentwisper-broker": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Codex

codex mcp add agentwisper-broker --transport streamable_http --url "http://localhost:8000/mcp"

MCP Tools Reference

Agent Management (5 tools)

Squad Management (8 tools)

Ad-hoc Team (4 tools)

Messaging (6 tools)

Subscription (2 tools)

Health (1 tool)

Configuration

Environment variables use the AGENTWHISPER_ prefix:

Communication Patterns

P2P (Point-to-Point)

Direct message from one agent to another. Best for targeted requests and responses.

Agent A                          Broker                          Agent B
  |                                |                                |
  |--- message_send(to=B) ------->|                                |
  |                                |-- store message -------------->|
  |                                |                                |
  |                                |<-------- message_poll() -------|
  |                                |--- deliver message ----------->|
  |                                |                                |

RPC (Request-Response)

Synchronous request/response with timeout. Caller blocks until responder replies.

Agent A                          Broker                          Agent B
  |                                |                                |
  |--- message_send(type=rpc) ---->|                                |
  |                                |-- store RPC request ----------->|
  |                                |                                |
  |                                |<--- message_poll() -------------|
  |                                |--- deliver request ----------->|
  |                                |                                |
  |                                |<--- message_send() ------------|
  |<-- RPC response ---------------|                                |
  |                                |                                |

Pub/Sub (Publish-Subscribe)

Topic-based broadcasting. Subscribers receive messages posted to topics they follow.

Publisher                        Broker                          Subscriber
  |                                |                                |
  |--- message_broadcast(topic=X)->|                                |
  |                                |-- lookup subscribers --------->|
  |                                |                                |
  |                                |       Subscriber A             Subscriber B
  |                                |-- deliver --------->|          |<-- deliver
  |                                |                                |

Squad and Team Model

Development

# Run all tests
uv run pytest

# Run specific test layer
uv run pytest tests/test_broker/

# Smoke test (MCP client integration)
uv run python tests/smoke_test.py

# System test (lifecycle & messaging)
uv run python tests/system_test.py

Project Structure

agentwisper/
  src/
    common/              # Types, config
    persistence/         # Database, stores
    broker/              # Registry, managers, router, core
    mcp_server/          # FastMCP tools (26 tools)
    cli/                 # Click CLI entry point
  tests/                 # Test suite (261 tests, incl. 13 integration)
  samples/               # Demo scripts and slash commands

License

Licensed under the Apache License 2.0.