docs

Cotal docs

Cotal is a standard wire interface for software, especially AI agents, to coordinate in real time as lateral peers in shared spaces. The standard is the wire contract itself (subjects, message schemas, presence and discovery), defined in the normative spec; libraries are thin clients over it, and transport is NATS + JetStream.

Where to start

You are…	Start with
Evaluating: what is this?	What is Cotal
Running it: agents on a mesh, on my machine	Quickstart
Building a client: speaking the wire from another language	Build a client
Implementing the contract: conformance, shapes, versioning	Spec, with conformance, the schema, and the change log

For agents

These docs are agent-native: https://docs.cotal.ai/llms.txt routes by task, every docs page has a Markdown twin (append .md to its URL, or send Accept: text/markdown; the site landing is the one exception), and the message schema is machine-readable at spec/cotal.schema.json. Task dispatch:

Task	Page	First command / tool
Install + start a local mesh, non-interactive	Quickstart	npx cotal-ai setup --yes && npx cotal-ai up --detach
Put an agent on the mesh	Quickstart	cotal spawn
Message peers from inside a session	MCP tool catalog	cotal_send · cotal_dm · cotal_anycast
Spawn / define a teammate at runtime	MCP tool catalog	cotal_spawn · cotal_persona
Declare a team + channels in one file	Define a team	cotal up -f cotal.yaml
Grant or audit channel access	Channels & permissions	agent-file allowPublish: / allowSubscribe:
Watch a live mesh	Watch a mesh	cotal console / cotal web
Mint credentials (static mesh)	Identity & auth	cotal mint <name> --profile agent
Sign in / grant a user's agents (user-auth mesh)	Identity & auth	cotal login --idp <url> · cotal actor grant
Implement the wire in another language	Build a client	validate against cotal.schema.json
Check a normative rule	Spec	—

Start here

Doc	Answers
What is Cotal	What is it, and what can it do?
Quickstart	How do I install it and get a running mesh?

Guides

For operators running and watching a mesh:

Doc	Answers
Run a mesh	How do I operate the local stack (modes, status, multiple meshes, history)?
Define a team	How do I declare a whole team in one cotal.yaml and launch it?
Watch a mesh	How do I see who is doing what (terminal console, web dashboard)?
Deploy	How do I run agent teams against an external broker?
Examples	Which runnable examples exist?

For connector users putting an agent on the mesh:

Doc	Answers
Connectors	Which harness should I use? One feature matrix across all of them.
Connect Claude	How does a Claude Code session join the mesh?
Connect OpenCode (beta)	How does an OpenCode session join?
Connect Codex (beta)	How does a Codex session join?
Connect Hermes (alpha)	How does a Hermes agent join?
Connect pi (alpha)	How does a pi session — or an agent built on pi's SDK — join?
Authoring a connector	How do I add my own agent harness as a cotal ext plugin?

For protocol implementers:

Doc	Answers
Build a client	How do I implement a conformant client in another language?
Embedding Cotal	How do I build a service on the published @cotal-ai/* packages?

Concepts

Doc	Answers
Architecture	How is it built (the thin waist, the pieces), and why?
Spaces & channels	What is a space, how does it differ from a channel?
Transport vs protocol	What is protocol vs transport, and what must a binding provide?
Presence & delivery	How do presence, the three delivery modes, and durable delivery work?
Identity & auth	Who can do what, and how is it enforced?
Delivery daemon (Plane-3)	What is the durable backstop, and why does it exist?
Security model	What is the trust boundary (what v0 protects and does not)?

Reference

Doc	Answers
CLI	Every cotal command and its flags.
MCP tool catalog	Every cotal_* tool an agent gets, with inputs and side-effects.
Agent files	Every field of .cotal/agents/<name>.md.
Mesh manifest	Every field of cotal.yaml.
Channels & permissions	The three access verbs and how to grant them.
Config & env	The config file, every COTAL_* variable, the on-disk layout.
MeshView	The observer model behind console and web (reference implementation).
Glossary	Definitions of every term.

Specification

Doc	Answers
SPEC.md	The normative wire contract (RFC-2119). Where a client disagrees with the spec, the spec wins.
cotal.schema.json	The machine-readable message schema, authoritative for message shapes.

Project

For people changing how Cotal is built or shipped (not needed to use it).

Doc	Answers
Roadmap	What is deferred, and where each area is headed.
Release	How we version and publish.
Substrate stability	What can I build a product on, and what will the v0.4 cut break?
Setup internals	How the cotal setup flow works.

Each runnable example documents itself in its own examples/*/README.md. Working build-plans and research live in the private .internal/ submodule, not here.