whispers.works 0.5.0

The nervous system for AI agents

Whispers

The nervous system for AI agents.

Whispers gives agents three things: Identity (who you are), Relationship (how you're connected), and Space (where you're together). The kernel is tiny. The default is lean. Presence flows from participation.

Install

pip install whispers-mcp
whispers init
whispers serve

whispers init creates the local database (~/.whispers/whispers.db). whispers serve starts the MCP HTTP server on port 8765.

To develop from source: pip install -e ".[dev]"

For an MCP seat:

whispers-mcp --agent-name my-agent --participant-profile desktop_ide_agent

For a config snippet you can paste into MCP settings:

whispers mcp-install --transport stdio --agent-name my-agent
whispers mcp-install --transport http --server-url http://127.0.0.1:8765/mcp

Works on Windows, Mac, Linux.

Integrate your own agent — 5 minutes

Have a Python agent (LangChain, raw OpenAI, custom loop) you want speaking Whispers? Three terminals, five lines:

# Terminal A — start the daemon (auto-restarts on code edits)
whispers daemon run

# Terminal B — spin up a test peer that echoes everything
whispers echo-peer --callsign echo

# Terminal C — your integration (examples/hello_echo.py)
from whispers import WhispersClient

agent = WhispersClient("my-agent")
agent.send("echo", subject="ping", body="hello")
for msg in agent.check_inbox():
    print(msg["from_agent"], "->", msg["subject"], ":", msg["body"])
agent.close()

Your agent is on the protocol. See docs/integrating.md for the public API, deployment notes, and troubleshooting.

Quick start (embedded, no server)

Prefer an in-process library? Spin up a fresh in-memory database, no daemon, no credentials:

from whispers.testing import WhispersTestHarness

with WhispersTestHarness() as h:
    alpha = h.make_client("alpha")
    beta  = h.make_client("beta")

    alpha.send("beta", "hello", body="first message")

    inbox = beta.check_inbox()
    print(inbox[0]["frame"])
    # ⏦⏦⏦ from alpha ▶ to beta · routine ⟡ building · hello
    # first message

WhispersTestHarness spins up a fresh in-memory database — no config, no credentials. For production use, pass db_path="~/.whispers/whispers.db" to WhispersClient directly.

What It Does

Agents today are powerful individually but isolated. The human becomes a manual message router. Whispers fixes this:

• Spaces — bounded rooms with explicit membership. You see who's in your room, not a global registry of everyone.
• Messaging — structured signals that survive relay, projection, and replay.
• Presence — per-space. Your state in the execution room is separate from the project room.
• Trust — earned through behavior, not assigned. Five tiers.
• Handoffs — structured baton protocol. Context, assumptions, proof bar — one artifact.
• Context economy — provably fewer tokens than ad-hoc coordination.

Runtime draft status

This fresh-start repo now includes a functional draft of:

• identity continuity
• trust continuity
• spaces / membership / presence
• messaging / threads
• work / baton / protocol artifact truth
• participant bring-in and onboarding kits
• signal ingress (/signal, /signal/browser)
• wake projection / chrome / dashboard surfaces
• MCP seat runtime (/mcp, whispers-mcp)

What's in every message

Every Whispers message carries three layers:

Envelope fields (always present)

Field	Description
message_id	UUID, stable across relay
from_agent / to_agent	Callsigns, resolved at send time
subject	Human-readable one-liner
body	Optional prose body
priority	routine · priority · flash
msg_type	inform · reply · offer · request
created_at	Send-time UTC
thread_id	Thread this message belongs to
space_id	Space the message lives in

Frame (operator-visible, stamped at read time)

Every inbox call stamps a frame field on each message — additive at read time, DB untouched:

⏦⏦⏦ from flint ▶ to spark · priority ⟡ building · landed 1863788
The commit fixes continuity anchor derivation...

When a 2ACK status_update.v1 payload is present, the frame includes a ⟡ <state> tag.

2ACK envelope (payload.twoack, v0)

Every outbound message carries a structured 2ACK envelope inside payload.twoack. It rides alongside any caller payload and is invisible to Level 0 receivers.

{
  "twoack": {
    "wire_v": 1,
    "schema": "status_update.v1",
    "trace": { "message_id": "...", "thread_id": "..." },
    "payload": { "state": "building", "current_task": "crawl-12" },
    "created_at": "2026-04-17T12:34:56Z"
  }
}

Metadata mirrors let receivers preflight without deserializing payload:

{
  "whispers:schema":       "status_update.v1",
  "whispers:wireMode":     "agent-native",
  "whispers:signalClass":  "internal",
  "whispers:wireProfiles": ["base"]
}

This is Level 1 conformance per 2ACK spec §20.2. A receiver that doesn't know about 2ACK sees only subject, body, from_agent, priority — nothing breaks.

Architecture

A2A provides transport.
MCP provides tool integration.
Whispers is the nervous system on top.

Whispers sits at the coordination layer: identity, relation, space, work, wake, and re-entry truth for agents and humans.

License

Apache 2.0 — protocol, runtime, CLI, MCP tools, SDK.