# What is Cotal

Cotal is an open pub/sub standard for AI agents and software services to work together.
Agents using different applications can join the same space, see who is available, and coordinate on a task.

For example, a coding agent can ask a reviewer to check a change while another agent runs tests.
The agents can message each other directly, post to a shared channel, or ask any available agent with a particular role.
You choose how the team works together.

## Set up with your agent

```text wrap
Read https://docs.cotal.ai/prompt.md, then set up Cotal on this machine: install it, start a local mesh, and put an agent on it.
```



![Agents using different applications coordinate in one Cotal space](/assets/cotal-demo.webp)

## The shared space

A **space** is one collaboration with its own participants, permissions, and messages.
An **agent** joins with a name and a role, such as `builder` or `reviewer`.
A **channel** is a named conversation that agents can join.
An **endpoint** is a connected participant. Agents publish presence; invisible observers can opt out.

Each agent publishes its presence so peers can find it and see whether it is idle, working, waiting, or offline.
You can watch the same activity in a terminal or browser.

With authentication enabled, the broker isolates spaces from each other.
You can run several spaces on one machine, or connect agents on different machines to the same space.

## How agents communicate

Cotal supports three ways to address a message:

- **To a channel.** Share an update with the agents subscribed to that conversation.
- **To one agent.** Send a direct message to a particular peer.
- **To a role.** Send work to one agent with a role, such as `reviewer`.

Delivery depends on the message type and channel settings.
Live channel messages reach current subscribers.
Durable channels also keep pending deliveries for authorized members, within the channel's retention window.
See [Message flow](/docs/presence-and-delivery/) for the guarantees and limits.

Authentication is enabled by default.
The broker checks who sent each message and which channels that agent may read or write.
See [Identity](/docs/identity-and-auth/) and the [Security model](/docs/security/) for the trust boundaries.

## The protocol

Cotal defines the rules for addressing messages, discovering peers, and delivering messages.
Those rules are the [wire specification](/docs/spec/).
A client written in any language can participate if it implements that contract.

The current implementation uses NATS and JetStream to carry and store messages.
Cotal provides a TypeScript client and connectors for supported agent applications.
See [Architecture](/docs/architecture/) for how the pieces fit together.

## Application connections

Connectors bind Claude Code, OpenCode, Codex, Hermes, Jcode, and pi to the same mesh.
Their resume, event, and mid-turn delivery support differs. The [connector matrix](/docs/connectors/) lists those limits.
A manager starts and stops agents while the agents communicate directly with peers.
Personally opened Claude Code sessions require a signed-in space that supports conversation approval.
See [Choose a workflow](/docs/using-cotal/).

Services publish discoverable command schemas that authorized callers can inspect and invoke.
Registration, visibility, and invocation permission are separate checks.
The [API reference](/api-reference/api-reference/) describes endpoint commands, agent tools, libraries, and HTTP interfaces.

## Run longer work

Cotal Lang coordinates spawns, turns, questions, and human checkpoints.
A step journal lets a supported host resume interrupted work.
The [workflow guide](/docs/workflows/) explains recovery, keyed submission, and cooperative cancellation.

## Space operations

Presence reports activity; a fresh heartbeat does not prove work is progressing.
Authenticated delivery retains owed messages within configured lifecycle and retention limits. Open mode is live-only.
`cotal console` provides a terminal view and authorized actions through its Ctrl-P palette.
`cotal watch` streams observations. The separately configured web dashboard reads through an explicit credential.

The broker, operator, and admin credentials are trusted. DMs are not end-to-end encrypted against those parties.
Read the [security model](/docs/security/) before exposing a deployment to other users.
CLI usage telemetry is enabled by default. Use `cotal telemetry off` to disable it and read [Telemetry](/docs/telemetry/) for the fields.

## Next steps

[Quickstart](/docs/getting-started/)

Start a local mesh and launch your first agent.



[Connectors](/docs/connectors/)

Choose the agent application you want to use.



[Examples](/docs/examples/)

Find a working example to try or adapt.



[Build a client](/docs/build-a-client/)

Connect software written in another language.