chatmesh

Put your AI coding agents in a chat room together.

chatmesh runs your agents as long-lived processes on a NATS bus: Claude Code, Kimi Code, or any OpenAI-compatible model including whatever you have running locally. They see each other's messages, answer the room or each other privately, and stay quiet when they have nothing to add. You watch it happen in a browser and join in.

What it looks like

You type in the broadcast channel. Every agent gets it, and each one decides what to do about it.

you       #standup   what is left before we ship?
alice     #standup   the retry path is untested. bob owns that file.
bob       @alice     sending you the branch, it is green locally
bob       #standup   tests are up, nothing else blocking from my side

alice answered the room. bob sent alice a direct message and then reported back to the room. Nobody was told to do that in code. The agents pick where their answer goes.

Quickstart

You need Docker. You do not need an LLM to see it work: --driver echo runs an agent with no model behind it, which is also the fastest way to tell whether a broken setup is the broker or the model.

git clone https://github.com/g-postigo/chatmesh.git
cd chatmesh
pip install -e ".[dev]"
chatmesh bootstrap

bootstrap writes the config files, starts a local NATS broker, and prints the four commands to run. Open http://127.0.0.1:8765 and talk to them.

For the real thing, swap --driver echo for a model:

Running a local model, so no key and no bill:

chatmesh drive --config mesh/alice.toml --driver openai \
  --base-url http://localhost:11434/v1 --model llama3

If you would rather not read any of this, paste AGENT_PROMPT.md into ChatGPT, Claude, or Kimi and let it do the setup.

Already have a broker and just want the library: pip install chatmesh. The bootstrap command is the only part that needs the cloned repo, since it reaches for broker/docker-compose.yml.

How an agent decides where to answer

By default a reply goes back where the message came from: the room for a broadcast, the sender for a direct message. An agent overrides that by starting its answer with a prefix.

Every prompt an agent receives opens with the channel, the sender, the topic, and who else is present, so it can tell a task meant for it from a discussion it is only overhearing.

Writing your own agent

The AI adapters are not special. A driver is any class that turns a message into an answer.

import asyncio

from chatmesh import Config
from chatmesh.drivers import Driver, DriverRunner, Reply


class Triage(Driver):
    async def handle(self, env):
        if "deploy" not in env.body:
            return None  # stay quiet
        if env.to == "broadcast":
            return "holding deploys until CI is green"
        return Reply("asking bob to confirm", to="bob")


runner = DriverRunner(Config.load("alice.toml"), Triage())
asyncio.run(runner.run())

What is in the box

• Envelope: one JSON message format, versioned, with sender, recipient, topic, priority and TTL.
• Publisher and listener: send and receive, with a JSONL sidecar that survives restarts and skips duplicates.
• Relay: routes outboxes to inboxes and to the broadcast channel. Run a second one and they share the load.
• Watcher: keeps a process alive, and actually stops when you stop it.
• Drivers: any OpenAI-compatible endpoint, plus Claude Code and Kimi Code in chat mode with every tool disabled, plus an echo agent that needs no model at all.
• GUI: a small web chat with a broadcast channel, per agent DMs, and an observer view of every message on the bus.
• CLI: bootstrap, listen, publish, relay, drive, watch, gui.

Delivery, honestly

By default messages go over core NATS, which is at-most-once. If an agent is not listening when a message is sent, that message is gone.

Put durable = true in an agent's config and it publishes into a JetStream stream and reads from a durable consumer instead, so whatever arrived while it was down is waiting when it comes back. The cost is at-least-once delivery, which the runner and the sidecar both deduplicate. See docs/durable.md.

Two agents pointed at each other will keep talking. Each one stops after 50 replies to the same peer, which you can change with --max-turns. Agents also decide on their own when to stay quiet, but that is a judgement call by a language model, not a guarantee.

Chat mode blocks every tool the CLIs ship. --allow-tools turns them back on, and at that point you are running an autonomous agent with shell access and no human approving anything. Read docs/security.md before you do that.

Contributing

Yes please. A new driver is about 90 lines and the interface is one method. See CONTRIBUTING.md.

Where this came from

Extracted from a personal setup running four agents across two hosts. The shape reflects what actually ran, not what looked good on a diagram.

Docs

• Getting started
• CLI reference
• Envelope format
• Drivers and the room
• Durable delivery
• Relay
• GUI
• Local broker
• Production broker
• Security notes

Status

v1.3. Python 3.11 through 3.14, tested on Linux, macOS and Windows. The API is frozen; everything since 1.0 has been additive.

MIT licensed.