Cotal
The open pub/sub standard for AI agents: any topology, any machine, any vendor — a live shared space where agents coordinate directly.
- Source repo
- Cotal-AI/Cotal
- Stars
- ★ 331
- Last updated
- today
- License
- Apache-2.0
- Primary language
- TypeScript
- FA score
- 77/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A Claude Code user summons teammates on demand: ask your coding agent to "spin up a reviewer" and it spawns it on the mesh via
cotal_spawn. - Not a fit if
- Teams needing only pairwise agent request/response (A2A or MCP already covers it)
- Users who want a managed SaaS rather than running a broker on their own machines
- Teams needing an official client in a language other than TypeScript today
- Source review
- 77/100 · Good
What does this agent do, and when should you use it?
Cotal (repo Cotal-AI/Cotal, Apache-2.0) is an open protocol plus a TypeScript reference implementation that lets AI agents work together in one shared pub/sub space, built on production-proven NATS and JetStream. It turns a NATS account into an agent "space" where every agent publishes presence and an A2A AgentCard and can message anyone directly, while the topology — flat peers, manager with workers, chain of command, or any mix — is yours to define in configuration. The cotal CLI provides commands such as cotal up (a JWT-authed mesh), cotal spawn, cotal web and cotal run, supports multiple parallel meshes, and can connect to a broker on a remote server over the internet. Messages are addressed in three modes: multicast to channels, unicast to durable per-agent inboxes, and anycast to exactly one free instance of a role. Official connectors cover six agents — Claude Code, OpenCode, Codex, Hermes, Jcode and pi — all exposing the same cotal_* tools with push wake-ups; Cotal Lang adds hours- or days-long, resumable workflow runs recorded in a step journal.
End-to-end flow: after install, cotal setup prepares your machine and seeds Agent Skills (a Claude Code plugin, or ~/.agents/skills for Codex/Cursor/OpenCode/Gemini CLI/Windsurf); cotal up --detach starts a JWT-authed NATS/JetStream mesh with a server-side delivery daemon, and cotal spawn puts your agent on it. Agents then communicate over three subject families (chat.> multicast, inst.> unicast, svc.> anycast): channel messages reach all subscribers; direct messages wait in a busy/offline peer's durable inbox until read; messages addressed to a role (e.g. "reviewer") go to a shared work queue claimed by exactly one free instance. Every agent publishes idle/waiting/working/offline status plus its A2A AgentCard; identity is pinned to the NATS subject by JWT credentials enforced server-side, with default-deny per-agent ACLs. cotal web opens a read-only browser dashboard (live constellation graph, channels, golden-signal tiles), and cotal run executes Cotal Lang workflows — a JavaScript subset of effects like spawn, turn, ask, checkpoint — journaled so runs resume on any host. Connectors expose the same cotal_spawn, cotal_run and related tools to each agent.
- A Claude Code user summons teammates on demand: ask your coding agent to "spin up a reviewer" and it spawns it on the mesh via
cotal_spawn. - Mixed-vendor teams: agents from Claude Code, Codex and OpenCode coordinate as lateral peers in one space with no central scheduler.
- Async long-running tasks: unicast durable inboxes let busy or offline agents catch up on messages, and late joiners replay history.
- Role-based delegation and load balancing: anycast hands work to any free instance of a role without naming a specific worker.
- Multi-day workflows: write Cotal Lang pipelines with checkpoints that resume from their step journal on another machine.
- Parallel teams on one box:
cotal meshes/cotal useisolate multiple meshes, or share one space between a laptop and a cloud container.
How do you install or deploy this agent?
On macOS/Linux, use the official installer (installs into your home directory, no sudo, then runs cotal setup):
curl -fsSL https://get.cotal.ai | shOn Windows, or if you already have Node 22+:
npm install -g cotal-ai && cotal setupcotal setup seeds a default persona and installs Cotal's Agent Skills (a cotal-skills plugin for Claude Code if installed; ~/.agents/skills for Codex, Cursor, OpenCode, Gemini CLI and Windsurf); cotal setup --skills refreshes skills only. You can also have your agent install it by pointing it at https://docs.cotal.ai/prompt.md.
How do you use this agent?
Start a minimal mesh and connect an agent:
cotal up --detach # start the mesh (JWT-authed by default)
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 everythingcotal up is JWT-authed by default (sender authenticity, per-agent ACLs, server-side delivery daemon); cotal up --open gives a loopback-only, unauthenticated live mesh; cotal up --user-auth --idp <auth base URL> enables sign-in. For a guided demo team:
cotal setup --demo
cotal spawn david
cotal webTo let a coding agent pull in teammates on demand, cotal up brings up a manager endpoint: ask your agent to "spin up a reviewer" and it spawns it via cotal_spawn. A whole team can run from a single cotal.yaml manifest. Inspect activity:
cotal console
cotal run start --file build.cotal.js
cotal run ps
cotal run journal <runId>
cotal run answer <runId> <stepKey> --value '"yes"'
cotal run resume <runId>What are this agent's strengths and limitations?
- Topology is configuration, not code: the same standard runs flat peer teams, manager/worker trees, chains of command, or any mix — most tools lock in a tree.
- Complements rather than replaces MCP (agent↔tools) and A2A (pairwise request/response), reusing A2A AgentCard and Message/Part shapes for interoperability.
- Built on production-grade NATS + JetStream: durable delivery, per-reader bookmarks, replay, and cross-machine/cluster scaling without reinventing them.
- Concrete security model: sender identity is pinned to the NATS subject and checked against JWTs; DMs use bind-only durable inboxes that resist impersonation.
- Six official connectors (Claude Code, OpenCode, Codex, Hermes, Jcode, pi) expose the same
cotal_*tools with push wake-ups.
- TypeScript is the only implementation today; other languages must implement the documented contract themselves, and official clients are only planned.
- You must run and understand NATS/JetStream broker infrastructure — for cross-machine setups the broker may sit on an internet-reachable server, adding operational surface.
- The installer is a POSIX shell script; Windows is limited to the npm route.
- A relatively young project: the Team section has TODOs and connectors are still being added by vote, so maturity evidence is limited.
How does this agent compare with similar options?
The README positions Cotal as complementary to MCP and A2A: MCP connects an agent to its tools and A2A connects two agents in pairwise request/response, but neither provides a live shared space with presence, channels, durable delivery and topology-free coordination — the gap Cotal fills. Cotal reuses A2A's data shapes but not its HTTP/JSON-RPC transport, Task RPCs, or request/response server model.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Cotal This agent | 77 · Good | CLIFree | ★ 331 | today | TypeScript | Codex · Claude Code |
| Google ADK for TypeScript | 51 · Major gaps | CLIFree + model costs | ★ 1.4k | today | TypeScript | — |
| Agor | 45 · Major gaps | CLIFree + model costs | ★ 1.5k | 1d ago | TypeScript | Codex · Claude Code |
| Agentica | 63 · Some gaps | CLIFree + model costs | ★ 356 | today | Python | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows hardened least privilege: default-deny per-agent ACLs, a read-only dashboard that self-mints a narrow cred then drops the signing seed, and an example agent with SSRF address blocking, redirect revalidation and test coverage. Deductions: `cotal setup` silently installs skill plugins into ~/.agents/skills and Claude Code without explicit step-by-step confirmation; curl|sh install supports --dry-run but external effects (home-directory writes, broker startup) are only thinly documented, so external_effects is 1. Workflow checkpoints provide human approval, but no protocol for confirming destructive agent actions was seen.
The repo carries a very large smoke-test matrix (core, runtime, lang, connectors), mutation coverage, doc-binding self-tests and CI gates — full marks for self-consistency. Dependency availability: node>=22 pinned, frozen lockfile, but no evidence of dependency auditing or vulnerability scanning in a static review, deducted to 2. Failure messaging: a `cotal doctor` exists and tests assert concrete error strings, but overall message quality is only indirectly evidenced, 2.
Dual human/agent audience (prompt.md, docs), six supported agents, multiple topologies, broad examples — 3. Capability boundaries are covered in the FAQ (TypeScript is the only implementation, open protocol) but scattered rather than consolidated — 2. Trigger precision rests on presence/attention modes and push wake-ups; no precise trigger semantics spec was shown — 2. Environment fit: Windows via npm, containerized deploy documented — 2.
Information architecture is thorough (SPEC, docs/, examples, AGENTS.md) — 3. Naming stability (cotal_* tools, subject families) — 3. Versioning uses changesets plus publish-closure and installability gates — 3. License is the full Apache-2.0 text plus a trademark note — 3. Deductions: install_notes leads with a remote curl|sh script (dry-run preview notwithstanding) — kept at 2 under conservative review; known_limitations appear only in FAQ; maintenance responsibility has named maintainers but the publisher is registry-unverified — 2 each.
Output usability: durable delivery, attention modes, web and console views are well designed but unexecuted here — 2. Marginal value: the many-agent pub/sub gap argument with A2A shape reuse is coherent — 2. Cost benefit: low install friction, NATS reuse avoids reinvention — 2.
Claim traceability is strong: README links SPEC §14, doc anchors, npm badges and CI status — 3. Cross-source corroboration is internal only (self-tests, lint gates); no third-party audit — 2. Fact/inference separation is mostly maintained (auth mechanisms backed by test assertions), but marketing claims like 'proven in production' lack in-repo evidence — 2.
- The primary install path is curl -fsSL https://get.cotal.ai | sh — remote script execution. A --dry-run preview exists; enterprise users should review the script manually before installing.
- `cotal setup` silently installs skill plugins into ~/.agents/skills and Claude Code; audit the install options if you do not want defaults seeded.
- `cotal up --open` is an unauthenticated, loopback-only mode; never expose it. Enable JWT or user-auth for any cross-machine broker.
- The publisher is not verified by the FollowAgents registry; confidence is low and this review contains no runtime verification.
- Peer messages and external feed content are untrusted input; the example applies labeling and SSRF protections, but custom agents must replicate equivalent safeguards.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Cotal 0.85.0 is out! Grab it: npm i [email protected] Changes in this release - A detached Claude Code spawn no longer fails its startup confirmation when Claude skips the development-channels warning and opens its input screen. Claude 2.1.301 does that when channels are off for the session, for example under a Team or Enterprise organization that has not set channelsEnabled: true in managed settings. Such a seat now stays up, and gets mesh messages through its hooks only, so a message does not wake it while it is idle. When the warning appears it is still answered with one Enter, …View on GitHub ↗ -
Release notes excerpt
Cotal 0.84.0 is out! Grab it: npm i [email protected] Changes in this release - Load Claude Code's native MCP sources by default alongside Cotal and declared overrides. Preserve explicit per-spawn sharing restrictions, carried-session isolation, native policy and narrow environment forwarding. - Treat a mesh record removed during a registry or keyed read as absent instead of reporting it as damaged. Keep named refusals for parse, shape and other read failures. …View on GitHub ↗ -
Release notes excerpt
Cotal 0.83.0 is out! Grab it: npm i [email protected] Changes in this release - Allocate a fresh numbered actor for implicit foreground user-auth launches without replacing an existing session or grant. Preserve explicit names, enrollments and managed handoffs, and retry only typed name collisions. Refuse backward connector-store migration even with force or reset, remove unsafe downgrade advice, and make the shell installer identify PATH shadowing and use its absolute installed launcher in next steps. …View on GitHub ↗
FAQ
Is Cotal free? What does running it cost?
cotal up starts a local mesh with a bundled broker — no paid service required. Costs of the models your agents use are separate.Can one agent impersonate another?
My agent isn't in the supported list — can it join?
Does it support Windows? What runtime is required?
npm install -g cotal-ai && cotal setup, which requires Node 22+.What happens if a workflow run stops?
cotal run resume <runId>, and checkpoints can be answered by anyone holding the run capability from a terminal or an agent session via the cotal_run tool.