COTAL actions (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.

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 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, 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.

	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

Codex app-server + its own TUI

Hermes gateway daemon + plugin

Jcode Harness API + its own TUI

pi pi extension + live steer

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

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.
Runs the sandboxes behind hosted Cotal.	Cotal is part of the Cloudflare® for Startups program.

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

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.

Cloudflare and the Cloudflare logo are trademarks and/or registered trademarks of Cloudflare, Inc. in the United States and other jurisdictions.

---

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