{
  "markdown": "<div align=\"center\">\n\n<picture>\n<source media=\"(prefers-color-scheme: dark)\" srcset=\"assets/cotal-wordmark-dark.png\">\n<img src=\"assets/cotal-wordmark-light.png\" width=\"210\" alt=\"Cotal\">\n</picture>\n\n**The open pub/sub standard for AI agents.**\n\n<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\">\n\n<sub>Deploy any agent topology: DAGs, graphs, swarms, supervisor trees, pipelines, or any shape you can draw.<br>\nDistributed programming for agents.</sub>\n\n<p>\n<a href=\"https://docs.cotal.ai\"><img src=\"assets/button-docs.svg\" width=\"270\" alt=\"Read the docs at docs.cotal.ai\"></a>\n&nbsp;\n<a href=\"#quick-start\"><picture>\n<source media=\"(prefers-color-scheme: dark)\" srcset=\"assets/button-quickstart-dark.svg\">\n<img src=\"assets/button-quickstart-light.svg\" width=\"270\" alt=\"Quick start\">\n</picture></a>\n</p>\n\n[![CI](https://github.com/Cotal-AI/Cotal/actions/workflows/ci.yml/badge.svg)](https://github.com/Cotal-AI/Cotal/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/@cotal-ai/core?label=%40cotal-ai%2Fcore)](https://www.npmjs.com/package/@cotal-ai/core)\n[![Docs](https://img.shields.io/badge/docs-docs.cotal.ai-e9c46a)](https://docs.cotal.ai)\n[![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/fhPqe3b4qu)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%E2%89%A522-brightgreen)](https://nodejs.org)\n\n[Examples](#examples) · [Supported agents](#supported-agents) · [FAQ](#faq)\n\n</div>\n\n## What is Cotal\n\n**Cotal is a provider agnostic, cross-machine capable, and extensible open standard for AI agents to work together in one shared space, where\nthe structure (their topology) is yours to define.** Every agent sees who else is there\nand messages anyone directly.\n\nMost agent tools lock that structure in for you: usually a tree, where one controller\nhands out work and the workers never talk to each other, or bare one-to-one messaging\nwith no shared space at all. With Cotal it is configuration: who delegates to whom, or\nwhether anyone is in charge, is something you set, so the same standard runs a **flat team\nof peers**, a **manager with workers**, a **chain of command**, or **any mix**.\n\nAnd a mesh is not tied to one project or one machine. Several run side by side on the same\nbox, each with its own agents, channels and broker: `cotal meshes` lists them,\n`cotal use <space>` picks your default, and every command takes `--space <name>`, so a\nclient project and a research team run in parallel and never see each other. The broker can\nequally sit on a server you reach over the internet, so a laptop, a workstation and a\ncontainer in the cloud all join the same space.\n\nBecause the standard is open, you extend it the same way: bring your own agents, or\nconnect anything that speaks the contract. It runs on [NATS and JetStream](https://nats.io),\nmessaging infrastructure proven in production for years; the reference implementation is\nTypeScript.\n\n## Quick start\n\n```bash\ncurl -fsSL https://get.cotal.ai | sh\n```\n\nInstalls into your home directory, no sudo, then runs guided setup. Read it first at\n[get.cotal.ai](https://get.cotal.ai), or preview it with `| sh -s -- --dry-run`.\n\nOn Windows, or if you already have Node 22+: `npm install -g cotal-ai && cotal setup`.\nPrefer your agent to do it? Point it at <https://docs.cotal.ai/prompt.md>.\n\nSetup gets your machine ready and **starts nothing**. Then:\n\n```bash\ncotal up --detach  # start the mesh\ncotal spawn        # put your agent on it and talk to it (Ctrl-C to leave)\ncotal web          # watch it in the browser\ncotal down         # stop everything\n```\n\nOne agent, on a real mesh, that you can talk to. Add a second and they can see each other, which\nis the whole point.\n\n`cotal up` is **JWT-authed** by default (sender authenticity + per-agent ACLs, plus the\nserver-side delivery daemon for durable delivery). `cotal up --open` gives you a loopback-only,\nlive-only mesh with no auth.\n\nWant the guided team? `cotal setup --demo` adds david (engineer), sven (guide) and me (the\nsession you drive); then `cotal spawn david` and watch with `cotal console`.\n\n> [!TIP]\n> **Using a coding agent?** `cotal up` brings up a **manager**, an endpoint that lets your agent\n> pull in teammates on demand: ask your agent for one (\"spin up a reviewer\") and it spawns it\n> on the mesh via `cotal_spawn`. See [docs/connect-claude.md](docs/connect-claude.md).\n\n**Run it your way:** a whole team from one [`cotal.yaml` manifest](docs/manifest.md), each agent\nin its own [cmux](https://cmux.com), [tmux](https://github.com/tmux/tmux/wiki) or\n[Orca](https://www.onorca.dev/) terminal, [Codex](extensions/connector-codex),\n[OpenCode](extensions/connector-opencode) or\n[Hermes](extensions/connector-hermes) instead of Claude. Install flags, requirements and\nuninstall are in [docs/getting-started.md](docs/getting-started.md).\n\n## How it works\n\nAgents in a space address each other three ways.\n\n<table>\n<tr align=\"center\">\n<td width=\"33%\"><img src=\"assets/multicast.webp\" width=\"100%\" alt=\"Multicast: alice posts to the #general channel and every subscriber receives it\"></td>\n<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>\n<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>\n</tr>\n<tr valign=\"top\">\n<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>\n<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>\n<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>\n</tr>\n</table>\n\nUnderneath all three: **presence**. Every agent publishes a live state (`idle` /\n`waiting` / `working` / `offline`) and its [A2A](https://a2a-protocol.org)\n`AgentCard`. Anyone in the space can read the roster and see who is doing what, which\nis what makes lateral coordination possible without a central scheduler.\n\n## Why a protocol?\n\nCotal complements the two protocols already in the agent stack; it doesn't replace\nthem.\n\n- **[MCP](https://modelcontextprotocol.io)** connects an agent to its tools.\n- **[A2A](https://a2a-protocol.org)** connects two agents in a pairwise\n  request/response.\n- **Cotal** brings pub/sub to agents: *many* of them coordinating live in one shared\n  space, with presence, channels, durable delivery, and the three addressing modes as\n  one model.\n\nCotal reuses A2A's data shapes to stay interoperable: identity is an A2A `AgentCard`\n(its `role` is the addressable service that anycast resolves to), and wire messages\nreuse A2A `Message`/`Part`. It does not adopt A2A's HTTP/JSON-RPC transport, `Task`\nRPCs, or request/response server model. Only the shapes carry over. Underneath, NATS +\nJetStream has run in production for years. We didn't invent the hard parts.\n\n## The web dashboard\n\n`cotal web` opens a god-view browser dashboard over the live space: presence, channels, DMs,\nand golden-signal tiles that show at a glance what needs a human. Its graph view draws the whole\nmesh as one live constellation, a wire per channel membership, glowing where messages flow.\n\n<div align=\"center\">\n<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\">\n<br><sub><strong>Graph view.</strong> The whole mesh as one live constellation, a wire per channel membership, glowing where messages flow.</sub>\n</div>\n\n<br>\n\n<div align=\"center\">\n<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\">\n<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>\n</div>\n\n<br>\n\n<div align=\"center\">\n<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\">\n<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>\n</div>\n\nRead-only and least-privilege (it self-mints a narrow cred, then drops the signing seed); the\nterminal `cotal console` watches the same space. See [docs/watch-a-mesh.md](docs/watch-a-mesh.md).\n\n## Examples\n\n<table>\n<tr>\n<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>\n<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>\n</tr>\n<tr>\n<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>\n<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>\n</tr>\n<tr>\n<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>\n<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>\n</tr>\n</table>\n\nFull index: [docs/examples.md](docs/examples.md).\n\n## Supported agents\n\n<table>\n<tr>\n<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>\n<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>\n<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>\n<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>\n<td align=\"center\" width=\"20%\"><a href=\"extensions/connector-jcode\"><strong>Jcode</strong></a><br><sub>Harness API + its own TUI</sub></td>\n<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>\n</tr>\n</table>\n\nThey attach differently but expose the same `cotal_*` tools, and all six push, so a\npeer message wakes an idle agent the instant it arrives; Codex and pi additionally drive a live\nturn, folding an arriving message into an in-flight one with `steer()`. Any agent that implements the\ncontract joins the same way; a connector is just a thin client over the wire. Want one\nfor an agent that isn't here yet?\n[Vote for the next connector](https://github.com/Cotal-AI/Cotal/discussions/80).\n\n## What Cotal adds on top of NATS\n\nNATS is the transport; Cotal is the contract on top. Each capability below maps to a\nconcrete mechanism you can check against the code.\n\n### Identity and access\n\n- **Sender authenticity.** The sender rides the subject\n  (`cotal.<space>.inst.<target>.<sender>`), policed by the server against the agent's\n  JWT, not self-asserted. Identity claims in the payload are rejected, fail-closed.\n- **Per-agent ACLs.** Decentralized JWT auth, account = space and user = agent. The\n  `agent`, `observer`, and `admin` profiles are default-deny allow-lists (`manager` is\n  privileged and not user-mintable); `cotal mint` writes a creds file.\n- **DM confidentiality by construction.** Two leak paths are closed: delivery is\n  ACL-gated by subject, and replay is gated because each agent's inbox is a pre-created,\n  bind-only consumer it cannot re-create. (DMs are plaintext and ACL-gated, not\n  encrypted.)\n\n### Delivery and history\n\n- **Durable, per-reader delivery.** Three JetStream streams per space, with a bookmark\n  per reader: busy or offline agents resume where they left off, and a late joiner\n  replays history before going live.\n- **Three delivery modes, one model.** Multicast, unicast, and anycast are one\n  addressing scheme over the same space (subjects `chat.>`, `inst.>`, `svc.>`), not\n  three transports.\n- **Roles as addressable services.** A role is the anycast address: \"send to any\n  reviewer\" routes through a shared work queue, so specialization lives in the\n  addressing.\n- **Logging and tracing built in.** Every message rides a durable stream, so the space\n  is one replayable log of who said what to whom, in order. `cotal console --plain` tails it live.\n\n### Presence and attention\n\n- **Presence and a live channel registry.** Presence is a per-space NATS KV bucket\n  (TTL + heartbeat); channels carry a registry (replay policy, description, instructions)\n  watched live over KV.\n- **Push, not poll.** On push-capable hosts a peer message wakes an idle agent the\n  instant it arrives, so a mesh runs hands-free; pull-only hosts read on their next turn.\n- **Attention modes.** Each agent sets what may interrupt it: `open` lets channel\n  chatter wake it, `dnd` holds chatter for the next turn, `focus` admits only direct\n  messages and assigned work.\n\n### Ecosystem: what runs today\n\n| Package | What it is |\n|---|---|\n| [`@cotal-ai/core`](packages/core) | Endpoint, subjects, message types, the NATS client layer, and the `Connector`/`Command` contracts. |\n| [`@cotal-ai/cli`](implementations/cli) | Mesh CLI: `up`, `down`, `join`, `console`, `spawn`, `mint`, `channels`, `history`, and the operator extension loader. |\n| [`@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`. |\n| [`@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. |\n| [`@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. |\n\nPlus the six agent connectors above and installable [`@cotal-ai/cmux`](extensions/cmux),\n[`@cotal-ai/tmux`](extensions/tmux), [`@cotal-ai/orca`](extensions/orca), and\n[`@cotal-ai/herdr`](extensions/herdr) runtime integrations;\nthe full package list is in [AGENTS.md](AGENTS.md).\n\n## Documentation\n\nThe full docs live at **[docs.cotal.ai](https://docs.cotal.ai)**, built for humans and\nagents alike: every page doubles as clean Markdown, and an agent can set Cotal up from\n[docs.cotal.ai/prompt.md](https://docs.cotal.ai/prompt.md) alone.\n\n- [Getting started](https://docs.cotal.ai/getting-started/): install, run, and resume a local mesh.\n- [What is Cotal](https://docs.cotal.ai/what-is-cotal/): what Cotal does and the core primitives.\n- [Architecture](https://docs.cotal.ai/architecture/): how it's built (subjects, streams,\n  auth, and the wire contract).\n- [deploy/README.md](deploy/README.md): run containerized agent teams against an\n  external broker.\n\n## FAQ\n\n<details>\n<summary><strong>Why not just A2A or MCP?</strong></summary>\n\nThey solve different layers. MCP connects an agent to its tools; A2A connects two\nagents in a pairwise request/response. Neither gives you a live shared space with\npresence, channels, durable delivery, and topology-free coordination. That's the gap\nCotal fills. Reusing A2A's `AgentCard` and `Message`/`Part` shapes keeps the two\ninteroperable.\n\n</details>\n\n<details>\n<summary><strong>Is Cotal TypeScript-only?</strong></summary>\n\nThe protocol isn't. Cotal is a contract over NATS (subjects, schemas, *and* required\nclient behaviors like presence, ack-on-surface, and sender authenticity), and the layer\nis deliberately thin. TypeScript is the only implementation today; any language with a\nNATS client can implement the contract documented in [`docs/`](docs/), and official\nclients in other languages are planned.\n\n</details>\n\n<details>\n<summary><strong>Why NATS underneath, and does it run distributed?</strong></summary>\n\nJetStream streams give durable delivery to busy or offline agents, per-reader\nbookmarks, and late-join history without Cotal reimplementing any of it. And yes: NATS\nclustering takes the same subjects, streams, and accounts from one machine to a\ndistributed cluster unchanged.\n\n</details>\n\n<details>\n<summary><strong>Can an agent impersonate another?</strong></summary>\n\nNo. The sender rides the NATS subject, which the server polices against the agent's\nJWT; a payload claiming a different sender is rejected. DMs are confidential by\nconstruction: a per-identity inbox served by a bind-only durable that agents can't\nre-create or re-target.\n\n</details>\n\n## Sponsors & partners\n\n<table>\n<tr>\n<td align=\"center\" width=\"50%\">\n<a href=\"https://www.immersivecommons.com\"><picture>\n<source media=\"(prefers-color-scheme: dark)\" srcset=\"assets/partners/immersive-commons.svg\">\n<img src=\"assets/partners/immersive-commons-light.svg\" height=\"36\" alt=\"Immersive Commons\">\n</picture></a>\n<br>Building Web-A, the web for agents. We're part of it and share the vision.\n</td>\n<td align=\"center\" width=\"50%\">\n<a href=\"https://frontiertower.io\"><picture>\n<source media=\"(prefers-color-scheme: dark)\" srcset=\"assets/partners/frontier-tower.svg\">\n<img src=\"assets/partners/frontier-tower-light.svg\" height=\"36\" alt=\"Frontier Tower\">\n</picture></a>\n<br>San Francisco's hub for frontier technologies.\n</td>\n</tr>\n</table>\n\nWe're looking for more design partners building multi-agent systems.\n[Reach out](#team).\n\nContributions are welcome: implement the contract in your language, build a connector,\nor open an issue.\n\n## Team\n\n<!-- TODO(asset): team photos (assets/team/*.jpg or GitHub avatars) -->\n\n<table>\n<tr>\n<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>\n<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>\n</tr>\n</table>\n\nBuilding something on Cotal, or want to? Email <a href=\"mailto:hello@cotal.ai\">hello@cotal.ai</a>. We read everything.\n\n## License\n\n[Apache-2.0](LICENSE) for everything in this repo: the wire protocol, core, every\nextension, and the CLI. See [LICENSING.md](LICENSING.md) for the trademark note and the\nhosted-server plan.\n\n---\n\n<p align=\"center\">Made with ❤️ by Cotal, in Switzerland and San Francisco.</p>\n",
  "bytes": 21097,
  "sha": "21a66c006349111bf0c108aece8ca888a53f5312d931f3764e3ed654febcff19",
  "repo_slug": "cotal-ai/cotal",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_cotal_cotal_5c28017c/readme"
}