COTAL actions (cotal.ai)
cotal.ai actions: product overview, site search, build log, feedback, Cloud waitlist, updates, calls
Open source Repository Open in the app JSON README (API)
About
cotal.ai actions: product overview, site search, build log, feedback, Cloud waitlist, updates, calls
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- ai.cotal
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.1.0
- Stars
- 279
- Forks
- 31
- Open pull requests
- 13
- Last push
- 2026-09-13T06:12:06Z
- Repository state
- ativo
- Language
- TypeScript
- License
- Apache-2.0
- Added
- 2026-09-08 02:13:50
- Updated
- 2026-09-08 02:13:50
- Origin id
ai.cotal/cotal
README
<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/cotal-wordmark-dark.png">
<img src="assets/cotal-wordmark-light.png" width="210" alt="Cotal">
</picture>
**The open pub/sub standard for AI agents.**
<img src="assets/cotal-demo.webp" width="760" alt="Cotal: any agent, any topology. Claude Code, OpenCode, Hermes and Codex across peer-to-peer, supervised, hierarchical and hybrid topologies">
<sub>Deploy any agent topology: DAGs, graphs, swarms, supervisor trees, pipelines, or any shape you can draw.<br>
Distributed programming for agents.</sub>
<p>
<a href="https://docs.cotal.ai"><img src="assets/button-docs.svg" width="270" alt="Read the docs at docs.cotal.ai"></a>
<a href="#quick-start"><picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/button-quickstart-dark.svg">
<img src="assets/button-quickstart-light.svg" width="270" alt="Quick start">
</picture></a>
</p>
[](https://github.com/Cotal-AI/Cotal/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@cotal-ai/core)
[](https://docs.cotal.ai)
[](https://discord.gg/fhPqe3b4qu)
[](LICENSE)
[](https://nodejs.org)
[Examples](#examples) · [Supported agents](#supported-agents) · [FAQ](#faq)
</div>
## 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](https://nats.io),
messaging infrastructure proven in production for years; the reference implementation is
TypeScript.
## Quick start
```bash
curl -fsSL https://get.cotal.ai | sh
```
Installs into your home directory, no sudo, then runs guided setup. Read it first at
[get.cotal.ai](https://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`.
Prefer your agent to do it? Point it at <https://docs.cotal.ai/prompt.md>.
Setup gets your machine ready and **starts nothing**. Then:
```bash
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.
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 console`.
> [!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](docs/connect-claude.md).
**Run it your way:** a whole team from one [`cotal.yaml` manifest](docs/manifest.md), each agent
in its own [cmux](https://cmux.com), [tmux](https://github.com/tmux/tmux/wiki) or
[Orca](https://www.onorca.dev/) terminal, [Codex](extensions/connector-codex),
[OpenCode](extensions/connector-opencode) or
[Hermes](extensions/connector-hermes) instead of Claude. Install flags, requirements and
uninstall are in [docs/getting-started.md](docs/getting-started.md).
## How it works
Agents in a space address each other three ways.
<table>
<tr align="center">
<td width="33%"><img src="assets/multicast.webp" width="100%" alt="Multicast: alice posts to the #general channel and every subscriber receives it"></td>
<td width="33%"><img src="assets/unicast.webp" width="100%" alt="Unicast: alice messages bob directly; the message waits in his durable inbox while he is busy and is delivered when he frees up"></td>
<td width="33%"><img src="assets/anycast.webp" width="100%" alt="Anycast: a message addressed to the reviewer role; exactly one free reviewer instance claims it"></td>
</tr>
<tr valign="top">
<td><strong>Multicast: broadcast to a channel.</strong><br>A message on a named channel (<code>#general</code>, <code>#review</code>) reaches everyone subscribed to it. This is how a group stays in sync.</td>
<td><strong>Unicast: message one peer.</strong><br>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.</td>
<td><strong>Anycast: reach any one of a role.</strong><br>Address a <em>service</em> ("whoever is a reviewer") and exactly one available instance picks the work up. Delegation and load-balancing without naming a worker.</td>
</tr>
</table>
Underneath all three: **presence**. Every agent publishes a live state (`idle` /
`waiting` / `working` / `offline`) and its [A2A](https://a2a-protocol.org)
`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](https://modelcontextprotocol.io)** connects an agent to its tools.
- **[A2A](https://a2a-protocol.org)** 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.
## 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.
<div align="center">
<img src="assets/dashboard-graph.webp" width="820" alt="The dashboard graph view: a live force-directed constellation of the mesh, with channels and agents as nodes and a wire per membership that glows when a message flows between them">
<br><sub><strong>Graph view.</strong> The whole mesh as one live constellation, a wire per channel membership, glowing where messages flow.</sub>
</div>
<br>
<div align="center">
<img src="assets/dashboard-channel.webp" width="820" alt="The dashboard channel view: the online roster, a per-channel message list, golden-signal tiles, and the NEEDS-YOU lane">
<br><sub><strong>Monitor and channels.</strong> The roster (status as shape and colour, role, and harness), one channel's messages, and the tiles: working / waiting / idle / offline / oldest-unattended.</sub>
</div>
<br>
<div align="center">
<img src="assets/dashboard-agent.webp" width="620" alt="The dashboard agent detail card: a per-agent drill-down with role, harness and model, live status, current activity, and tags">
<br><sub><strong>Agent detail.</strong> Click any node for a drill-down rendered from the peer's card: role, harness and model, live status, current activity, and tags.</sub>
</div>
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](docs/watch-a-mesh.md).
## Examples
<table>
<tr>
<td width="50%"><img src="assets/quickstart.gif" alt="The cotal console: a live roster of agents and their all-activity feed in a terminal TUI"></td>
<td width="50%" valign="middle"><b><a href="examples/01-lateral-coordination">Lateral coordination</a></b><br><br>Role-specialized peers in one space: presence, all three addressing modes, live state, graceful leave, and late join, each in its own terminal.<br><br><sub>the raw protocol · plain terminals</sub></td>
</tr>
<tr>
<td width="50%" valign="middle"><b><a href="examples/02-self-improving-console">A swarm rebuilds Cotal's console</a></b><br><br>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.<br><br><sub>four coding agents · <a href="https://cmux.com">cmux</a> tabs</sub></td>
<td width="50%"><img src="assets/example-02.gif" alt="Four Claude Code agents (orchestrator, backend, tui-designer, manager) coordinating on the Cotal mesh, with the live cotal console on the left and the agents in cmux tabs on the right"></td>
</tr>
<tr>
<td width="50%"><img src="assets/example-04-frontier.webp" alt="The Frontier Tower faces demo on the tmux wall: pixel-art OpenCode agents on the Cotal mesh lip-syncing their streamed replies, with the live cotal console beside them"></td>
<td width="50%" valign="middle"><b><a href="examples/04-frontier-faces">Frontier Tower faces</a></b><br><br>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.<br><br><sub>ten OpenCode faces · <a href="https://opencode.ai">OpenCode</a> · tmux wall + browser</sub></td>
</tr>
</table>
Full index: [docs/examples.md](docs/examples.md).
## Supported agents
<table>
<tr>
<td align="center" width="20%"><a href="extensions/connector-claude-code"><img src="assets/agents/claude-code.svg" height="44" alt=""><br><strong>Claude Code</strong></a><br><sub>installed plugin + hooks</sub></td>
<td align="center" width="20%"><a href="extensions/connector-opencode"><img src="assets/agents/opencode.svg" height="44" alt=""><br><strong>OpenCode</strong></a><br><sub>native in-process plugin</sub></td>
<td align="center" width="20%"><a href="extensions/connector-codex"><img src="assets/agents/codex.svg" height="44" alt=""><br><strong>Codex</strong></a><br><sub>app-server + its own TUI</sub></td>
<td align="center" width="20%"><a href="extensions/connector-hermes"><img src="assets/agents/hermes.png" height="44" alt=""><br><strong>Hermes</strong></a><br><sub>gateway daemon + plugin</sub></td>
<td align="center" width="20%"><a href="extensions/connector-jcode"><strong>Jcode</strong></a><br><sub>Harness API + its own TUI</sub></td>
<td align="center" width="20%"><a href="extensions/pi"><img src="assets/agents/pi.svg" height="44" alt=""><br><strong>pi</strong></a><br><sub>pi extension + live steer</sub></td>
</tr>
</table>
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](https://github.com/Cotal-AI/Cotal/discussions/80).
## 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`](packages/core) | Endpoint, subjects, message types, the NATS client layer, and the `Connector`/`Command` contracts. |
| [`@cotal-ai/cli`](implementations/cli) | Mesh CLI: `up`, `down`, `join`, `console`, `spawn`, `mint`, `channels`, `history`, and the operator extension loader. |
| [`@cotal-ai/manager`](implementations/manager) | Agent supervisor: spawns and manages nodes via a pluggable runtime (pty / tmux / cmux / Orca / Herdr), with `start`/`stop`/`ps`/`attach`. |
| [`@cotal-ai/delivery`](implementations/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`](extensions/connector-core) | Shared MCP-bridge runtime: the mesh agent and the `cotal_*` tools the agent connectors above are thin clients over. |
Plus the six agent connectors above and installable [`@cotal-ai/cmux`](extensions/cmux),
[`@cotal-ai/tmux`](extensions/tmux), [`@cotal-ai/orca`](extensions/orca), and
[`@cotal-ai/herdr`](extensions/herdr) runtime integrations;
the full package list is in [AGENTS.md](AGENTS.md).
## Documentation
The full docs live at **[docs.cotal.ai](https://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](https://docs.cotal.ai/prompt.md) alone.
- [Getting started](https://docs.cotal.ai/getting-started/): install, run, and resume a local mesh.
- [What is Cotal](https://docs.cotal.ai/what-is-cotal/): what Cotal does and the core primitives.
- [Architecture](https://docs.cotal.ai/architecture/): how it's built (subjects, streams,
auth, and the wire contract).
- [deploy/README.md](deploy/README.md): run containerized agent teams against an
external broker.
## FAQ
<details>
<summary><strong>Why not just A2A or MCP?</strong></summary>
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.
</details>
<details>
<summary><strong>Is Cotal TypeScript-only?</strong></summary>
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/`](docs/), and official
clients in other languages are planned.
</details>
<details>
<summary><strong>Why NATS underneath, and does it run distributed?</strong></summary>
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.
</details>
<details>
<summary><strong>Can an agent impersonate another?</strong></summary>
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.
</details>
## Sponsors & partners
<table>
<tr>
<td align="center" width="50%">
<a href="https://www.immersivecommons.com"><picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/partners/immersive-commons.svg">
<img src="assets/partners/immersive-commons-light.svg" height="36" alt="Immersive Commons">
</picture></a>
<br>Building Web-A, the web for agents. We're part of it and share the vision.
</td>
<td align="center" width="50%">
<a href="https://frontiertower.io"><picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/partners/frontier-tower.svg">
<img src="assets/partners/frontier-tower-light.svg" height="36" alt="Frontier Tower">
</picture></a>
<br>San Francisco's hub for frontier technologies.
</td>
</tr>
</table>
We're looking for more design partners building multi-agent systems.
[Reach out](#team).
Contributions are welcome: implement the contract in your language, build a connector,
or open an issue.
## Team
<!-- TODO(asset): team photos (assets/team/*.jpg or GitHub avatars) -->
<table>
<tr>
<td align="center"><img src="https://github.com/davidfarah2003.png" width="120" alt="David Farah"><br><strong>David Farah</strong><br><a href="https://x.com/DavidFarahlb"><img src="https://img.shields.io/badge/-@DavidFarahlb-000?logo=x&logoColor=white" alt="@DavidFarahlb on X"></a> <a href="https://www.linkedin.com/in/david-farah-lb/"><img src="https://img.shields.io/badge/-LinkedIn-0A66C2?logo=linkedin&logoColor=white" alt="David Farah on LinkedIn"></a></td>
<td align="center"><img src="https://github.com/Lanzelot1.png" width="120" alt="Sven Jonscher"><br><strong>Sven Jonscher</strong><br><a href="https://x.com/svensonj00"><img src="https://img.shields.io/badge/-@svensonj00-000?logo=x&logoColor=white" alt="@svensonj00 on X"></a> <a href="https://www.linkedin.com/in/sven-jonscher-418351247/"><img src="https://img.shields.io/badge/-LinkedIn-0A66C2?logo=linkedin&logoColor=white" alt="Sven Jonscher on LinkedIn"></a></td>
</tr>
</table>
Building something on Cotal, or want to? Email <a href="mailto:hello@cotal.ai">hello@cotal.ai</a>. We read everything.
## License
[Apache-2.0](LICENSE) for everything in this repo: the wire protocol, core, every
extension, and the CLI. See [LICENSING.md](LICENSING.md) for the trademark note and the
hosted-server plan.
---
<p align="center">Made with ❤️ by Cotal, in Switzerland and San Francisco.</p>