Cotal Ai

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.

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.

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 connects many agents coordinating live in a shared space: 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.

Quick start

Cotal's guided setup is one command on a fresh machine:

npx cotal-ai setup  # checks your machine, installs `cotal`, and configures your first agent mesh

Or skip the terminal and paste one line into any coding agent, which sets everything up itself:

Read https://docs.cotal.ai/prompt.md, then set up Cotal on this machine: install it, start a local mesh, and put an agent on it.

setup gets your machine ready and starts nothing: checks Node/NATS, lets you pick connectors (Claude installs a plugin; OpenCode auto-wires at spawn), installs the web dashboard extension, seeds one default agent, and offers to put cotal on your PATH. Then run:

cotal up --detach  # start the local mesh + delivery daemon + manager
cotal status       # detailed setup, process, registry, and live mesh status
cotal web          # open the browser view of the mesh
cotal spawn        # launch your default agent here and talk to it (Ctrl-C to leave)
cotal down         # stop the mesh, delivery daemon, manager, and web

If setup hits a step it cannot finish, it hands you to an interactive Claude with the failure context, then retries.

Once the mesh is up, cotal web and cotal console watch the same live space; cotal spawn launches the default agent in this terminal. cotal up is JWT-authed by default (sender authenticity + per-agent ACLs, with the server-side delivery daemon for the durable backstop). Pass cotal up --open for a frictionless open, loopback-only, live-only mesh (no auth, no daemon).

Want the guided team too? Add it explicitly, then spawn the teammates you want:

cotal setup --demo  # add david (engineer), sven (guide), and me (driving session)
cotal spawn david   # or: cotal spawn sven / cotal spawn me
cotal console       # terminal view of presence, channels, and messages

[!NOTE] Want each teammate in its own terminal? Run the manager with cotal supervise --runtime cmux (a cmux tab per agent), --runtime tmux (a tmux window per agent), or --runtime orca (an Orca terminal in the matching worktree). Otherwise they run in the background on the same mesh, watched with cotal console or the dashboard.

[!TIP] Using a coding agent? cotal up brings 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 via cotal_spawn. See docs/connect-claude.md.

Run it your way: a whole team from one cotal.yaml manifest, agents in cmux/tmux/Orca terminals, OpenCode or Hermes instead of Claude, or the guided expert team (cotal setup --demo). Start at docs/getting-started.md.

Examples

	Lateral coordination Role-specialized peers in one space: presence, all three addressing modes, live state, graceful leave, and late join, each in its own terminal. the raw protocol · plain terminals
A swarm rebuilds Cotal's console Four real Claude Code agents join one mesh and coordinate as lateral peers; an orchestrator spawns the workers in cmux tabs and they ship a polished Ink/React TUI for the live console. four coding agents · cmux tabs
	Frontier Tower faces Ten panelist personas as animated pixel-art OpenCode agents: each thinks, lip-syncs its streamed reply, and steers its own 32×32 expression, and on the mesh they coordinate as lateral peers in one space. ten OpenCode faces · OpenCode · tmux wall + browser

Full index: docs/examples.md.

Supported agents

Claude Code installed plugin + hooks

OpenCode native in-process plugin

Hermes gateway daemon + plugin

pi pi extension + live steer

They attach differently but expose the same cotal_* tools, and all four push, so a peer message wakes an idle agent the instant it arrives; pi additionally drives 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

NATS is the transport; Cotal is the contract on top. Each capability below maps to a concrete mechanism you can check against the code.

Identity and access

• Sender authenticity. The sender rides the subject (cotal.<space>.inst.<target>.<sender>), policed by the server against the agent's JWT, not self-asserted. Identity claims in the payload are rejected, fail-closed.
• Per-agent ACLs. Decentralized JWT auth, account = space and user = agent. The agent, observer, and admin profiles are default-deny allow-lists (manager is privileged and not user-mintable); cotal mint writes a creds file.
• DM confidentiality by construction. Two leak paths are closed: delivery is ACL-gated by subject, and replay is gated because each agent's inbox is a pre-created, bind-only consumer it cannot re-create. (DMs are plaintext and ACL-gated, not encrypted.)

Delivery and history

• Durable, per-reader delivery. Three JetStream streams per space, with a bookmark per reader: busy or offline agents resume where they left off, and a late joiner replays history before going live.
• Three delivery modes, one model. Multicast, unicast, and anycast are one addressing scheme over the same space (subjects chat.>, inst.>, svc.>), not three transports.
• Roles as addressable services. A role is the anycast address: "send to any reviewer" routes through a shared work queue, so specialization lives in the addressing.
• Logging and tracing built in. Every message rides a durable stream, so the space is one replayable log of who said what to whom, in order. cotal console --plain tails it live.

Presence and attention

• Presence and a live channel registry. Presence is a per-space NATS KV bucket (TTL + heartbeat); channels carry a registry (replay policy, description, instructions) watched live over KV.
• Push, not poll. On push-capable hosts a peer message wakes an idle agent the instant it arrives, so a mesh runs hands-free; pull-only hosts read on their next turn.
• Attention modes. Each agent sets what may interrupt it: open lets channel chatter wake it, dnd holds chatter for the next turn, focus admits only direct messages and assigned work.

Ecosystem: what runs today

Package	What it is
@cotal-ai/core	Endpoint, subjects, message types, the NATS client layer, and the Connector/Command contracts.
@cotal-ai/cli	Mesh CLI: up, down, join, console, spawn, mint, channels, history, and the operator extension loader.
@cotal-ai/manager	Agent supervisor: spawns and manages nodes via a pluggable runtime (pty / tmux / cmux / Orca), with start/stop/ps/attach.
@cotal-ai/delivery	Server-side Plane-3 delivery daemon: the durable backstop (fan-out writer + trusted reader + membership/ACL authority), co-located with the broker.
@cotal-ai/connector-core	Shared MCP-bridge runtime: the mesh agent and the cotal_* tools the agent connectors above are thin clients over.

Plus the three agent connectors above and installable @cotal-ai/cmux, @cotal-ai/tmux, and @cotal-ai/orca runtime integrations; the full package list is 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

Why not just A2A or MCP?

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.

Is Cotal TypeScript-only?

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.

Why NATS underneath, and does it run distributed?

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.

Can an agent impersonate another?

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

Building Web-A, the web for agents. We're part of it and share the vision.

San Francisco's hub for frontier technologies.

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.

Team

David Farah

Sven Jonscher

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.

---

Made with ❤️ by Cotal, in Switzerland and San Francisco.