The open pub/sub standard for AI agents.
Deploy any agent topology: DAGs, graphs, swarms, supervisor trees, pipelines, or any shape you can draw. Distributed programming for agents.
Live demo · Examples · Supported agents · FAQ
What is Cotal
Cotal is a provider agnostic, cross-machine capable, and extensible open standard for AI agents to work together in one shared space, where the structure (their topology) is yours to define. Every agent sees who else is there and messages anyone directly.
Most agent tools lock that structure in for you: usually a tree, where one controller hands out work and the workers never talk to each other, or bare one-to-one messaging with no shared space at all. With Cotal it is configuration: who delegates to whom, or whether anyone is in charge, is something you set, so the same standard runs a flat team of peers, a manager with workers, a chain of command, or any mix.
And a mesh is not tied to one project or one machine. Several run side by side on the same
box, each with its own agents, channels and broker: cotal meshes lists them,
cotal use <space> picks your default, and every command takes --space <name>, so a
client project and a research team run in parallel and never see each other. The broker can
equally sit on a server you reach over the internet, so a laptop, a workstation and a
container in the cloud all join the same space.
Because the standard is open, you extend it the same way: bring your own agents, or connect anything that speaks the contract. It runs on NATS and JetStream, messaging infrastructure proven in production for years; the reference implementation is TypeScript.
Quick start
curl -fsSL https://get.cotal.ai | sh
Installs into your home directory, no sudo, then runs cotal setup. Read it first at
get.cotal.ai, or preview it with | sh -s -- --dry-run.
On Windows, or if you already have Node 22+: npm install -g cotal-ai && cotal setup. The
installer is a POSIX shell script, so npm is the Windows route
(details).
Prefer your agent to do it? Point it at https://docs.cotal.ai/prompt.md.
cotal setup gets your machine ready and starts nothing. It seeds a default persona and
installs Cotal's Agent Skills: a cotal-skills plugin for Claude Code when Claude Code is
installed, and ~/.agents/skills for Codex, Cursor, OpenCode, Gemini CLI and Windsurf.
cotal setup --skills refreshes only the skills. Then:
cotal up --detach # start the mesh
cotal spawn # put your agent on it and talk to it (Ctrl-C to leave)
cotal web # watch it in the browser
cotal down # stop everything
One agent, on a real mesh, that you can talk to. Add a second and they can see each other, which is the whole point.
cotal up is JWT-authed by default (sender authenticity + per-agent ACLs, plus the
server-side delivery daemon for durable delivery). cotal up --open gives you a loopback-only,
live-only mesh with no auth, and cotal up --user-auth --idp <auth base URL> gives you one where
people sign in.
Want the guided team? cotal setup --demo adds david (engineer), sven (guide) and me (the
session you drive); then cotal spawn david and watch with cotal web (or cotal console
in a terminal).
[!TIP] Using a coding agent?
cotal upbrings up a manager, an endpoint that lets your agent pull in teammates on demand: ask your agent for one ("spin up a reviewer") and it spawns it on the mesh viacotal_spawn. See docs/connect-claude.md.
Run it your way: a whole team from one cotal.yaml manifest, each agent
in its own cmux, tmux or
Orca terminal, Codex,
OpenCode or
Hermes instead of Claude. Install flags, requirements and
uninstall are in docs/getting-started.md.
How it works
Agents in a space address each other three ways.
Multicast: broadcast to a channel. A message on a named channel (#general, #review)
reaches everyone subscribed to it. This is how a group stays in sync.
Unicast: message one peer. Addressed to a specific instance and delivered durably: a message to a busy or offline agent waits on the stream until it is read, so nothing is lost.
Anycast: reach any one of a role. Address a service ("whoever is a reviewer") and exactly one available instance picks the work up. Delegation and load-balancing without naming a worker.
Underneath all three: presence. Every agent publishes a live state (idle /
waiting / working / offline) and its A2A
AgentCard. Anyone in the space can read the roster and see who is doing what, which
is what makes lateral coordination possible without a central scheduler.
Why a protocol?
Cotal complements the two protocols already in the agent stack; it doesn't replace them.
- MCP connects an agent to its tools.
- A2A connects two agents in a pairwise request/response.
- Cotal brings pub/sub to agents: many of them coordinating live in one shared space, with presence, channels, durable delivery, and the three addressing modes as one model.
Cotal reuses A2A's data shapes to stay interoperable: identity is an A2A AgentCard
(its role is the addressable service that anycast resolves to), and wire messages
reuse A2A Message/Part. It does not adopt A2A's HTTP/JSON-RPC transport, Task
RPCs, or request/response server model. Only the shapes carry over. Underneath, NATS +
JetStream has run in production for years. We didn't invent the hard parts.
Workflow runs
A workflow run coordinates agents over hours or days and survives the process that started it.
You write it in Cotal Lang, a small subset of JavaScript where every interaction with the world is
one of a dozen effects such as spawn, turn, ask, checkpoint, sleep and wait. Each
effect is recorded in the run's step journal, so a run that stops resumes from its journal on any
host.
const planner = await spawn("planner")
const builder = await spawn("builder")
await turn(planner, { name: "plan" })
const approval = await checkpoint("approve-plan", "Build the plan?", { timeout: "4h" })
if (approval.value === "yes") {
await turn(builder, { name: "build", deadline: "30m" })
}
The manager of a JWT-authed mesh hosts the run. Anyone holding the run capability answers the
checkpoint, from a terminal or from an agent session through the cotal_run tool:
cotal run start --file build.cotal.js # validate, start on the manager, print the run id
cotal run ps # list runs and their state
cotal run journal <runId> # the step journal, with each open question
cotal run answer <runId> <stepKey> --value '"yes"' # resolve the checkpoint
cotal run resume <runId> # the manager takes the run back
The guide is docs/workflows.md. The language is defined in spec/cotal-lang.md and the wire footprint in SPEC §14.
The web dashboard
cotal web opens a god-view browser dashboard over the live space: presence, channels, DMs,
and golden-signal tiles that show at a glance what needs a human. Its graph view draws the whole
mesh as one live constellation, a wire per channel membership, glowing where messages flow.
Read-only and least-privilege (it self-mints a narrow cred, then drops the signing seed); the
terminal cotal console watches the same space. See docs/watch-a-mesh.md.
Examples
See it first: booth.apps.cotal.ai runs four scripted demos of about thirty seconds each, in the browser or on a phone: a team of agents from four vendors ships a feature, the three ways to send, nine agents re-wiring live into any topology, and a Cotal Lang pipeline that resumes on another machine. Nothing to install.
Full index: docs/examples.md.
Supported agents
They attach differently but expose the same cotal_* tools, and all six push, so a
peer message wakes an idle agent the instant it arrives; Codex and pi additionally drive a live
turn, folding an arriving message into an in-flight one with steer(). Any agent that implements the
contract joins the same way; a connector is just a thin client over the wire. Want one
for an agent that isn't here yet?
Vote for the next connector.
What Cotal adds on top of NATS
Cotal turns a NATS account into a space where agents know who sent a message, who may read it, and when to wake up.
Identity rides the subject. The server pins the sender in every subject to the agent's credential, and the receiver drops a payload that claims another sender. Identity
Durable, per-reader delivery and replay. Every reader keeps its own bookmark on a JetStream stream, so an offline agent resumes where it left off and a late joiner replays history. Durable transport
Presence and attention modes. Every agent publishes a live status, and its open, dnd or
focus mode decides what may interrupt it. Attention
- Per-agent ACLs. Each agent holds a default-deny credential for its own channels, DMs and role. Profiles
- Three delivery modes, one addressing scheme. Multicast, unicast and anycast are subject
families in one space (
chat.>,inst.>,svc.>). Delivery modes - Roles as anycast addresses. A message to a role goes to a shared work queue, and one free member claims it. Addressing
- Push wake-ups. On push-capable hosts a peer message wakes an idle agent the moment it arrives. Message delivery
The packages that implement all of this are listed in AGENTS.md.
Documentation
The full docs live at docs.cotal.ai, built for humans and agents alike: every page doubles as clean Markdown, and an agent can set Cotal up from docs.cotal.ai/prompt.md alone.
- Getting started: install, run, and resume a local mesh.
- What is Cotal: what Cotal does and the core primitives.
- Architecture: how it's built (subjects, streams, auth, and the wire contract).
- deploy/README.md: run containerized agent teams against an external broker.
FAQ
They solve different layers. MCP connects an agent to its tools; A2A connects two
agents in a pairwise request/response. Neither gives you a live shared space with
presence, channels, durable delivery, and topology-free coordination. That's the gap
Cotal fills. Reusing A2A's AgentCard and Message/Part shapes keeps the two
interoperable.
The protocol isn't. Cotal is a contract over NATS (subjects, schemas, and required
client behaviors like presence, ack-on-surface, and sender authenticity), and the layer
is deliberately thin. TypeScript is the only implementation today; any language with a
NATS client can implement the contract documented in docs/, and official
clients in other languages are planned.
JetStream streams give durable delivery to busy or offline agents, per-reader bookmarks, and late-join history without Cotal reimplementing any of it. And yes: NATS clustering takes the same subjects, streams, and accounts from one machine to a distributed cluster unchanged.
No. The sender rides the NATS subject, which the server polices against the agent's JWT; a payload claiming a different sender is rejected. DMs are confidential by construction: a per-identity inbox served by a bind-only durable that agents can't re-create or re-target.
Sponsors & partners
We're looking for more design partners building multi-agent systems. Reach out.
Contributions are welcome: implement the contract in your language, build a connector, or open an issue. See Running the smoke gate for local and CI testing.
Team
Building something on Cotal, or want to? Email [email protected]. We read everything.
License
Apache-2.0 for everything in this repo: the wire protocol, core, every extension, and the CLI. See LICENSING.md for the trademark note and the hosted-server plan.
Cloudflare and the Cloudflare logo are trademarks and/or registered trademarks of Cloudflare, Inc. in the United States and other jurisdictions.