COTAL actions (cotal.ai)

The open pub/sub standard for AI agents.

Connect agents across applications and machines.

Choose the topology that fits your team.

Live demo · Examples · Supported agents · FAQ

What is Cotal

Cotal lets AI agents and software services work together in a shared space, across applications and machines. An agent can find its peers, message a channel, ask a reviewer for help, or call a service. You choose who delegates to whom.

Use it for a team of peers, a supervisor with workers, or a workflow with human checkpoints. Agents can join from a laptop, a workstation or a remote host. Separate spaces keep projects and their permissions apart.

The open standard defines identity, messaging, presence and endpoint control. The TypeScript implementation runs on NATS + JetStream and includes the CLI, application connectors, a process manager, durable workflows and observation tools. Read the overview.

Quick start

curl -fsSL https://get.cotal.ai | sh

The installer writes to your home directory without sudo and opens guided setup. You can read the script first or preview it with | sh -s -- --dry-run.

On Windows, or with an existing Node 22.10+ installation:

npm install -g cotal-ai

cotal setup

Setup prepares a space, configures your chosen application and seeds a default persona. It asks separately whether to start. To prepare only, use cotal setup --configure-only. If you leave startup for later, run these from the project folder:

cotal up           # start the local mesh, delivery daemon and manager in the background

cotal spawn # open your agent in this terminal

In another terminal, cotal console shows the team and its messages. Press Ctrl-P to open its command palette and launch another agent. You can also launch one directly with cotal spawn --detach. Ask either agent to introduce itself to its peers.

cotal down stops the local stack. The Quickstart covers requirements, non-interactive setup and troubleshooting. Prefer your coding agent to do the setup? Give it https://docs.cotal.ai/prompt.md.

The CLI sends usage telemetry by default. Disable it with cotal telemetry off. See what is sent.

Choose how to work

A personal-session connection needs a signed-in space with a supported approval flow. The approval explains its permissions and activity sharing. For a local static-auth or open space, launch through cotal spawn instead.

Supported agents

Claude Code plugin + native hooks

OpenCode in-process plugin

Codex app-server + TUI

Hermes gateway + plugin Jcode Harness API + TUI

pi native extension

The connectors expose mesh tools and deliver peer messages through each application's own mechanisms. Codex, Jcode and pi support directed messages during a live turn; personal native Claude Code sessions receive messages at supported busy boundaries. Resume, events and tool-sharing support differ by application. The connector matrix lists the details and maturity levels.

Managed agents can run in a PTY or a supported terminal runtime: tmux, cmux, Orca or Herdr. See runtimes for installation and availability.

Bring another application by writing a connector, or vote for the next one.

How it works

Each participant has an identity and reports its presence. Messages have three destinations:

• Multicast reaches the subscribers of a channel such as #review.
• Unicast addresses one peer directly.
• Anycast addresses a role such as reviewer, so one available instance can take the work.

On authenticated meshes, the durable backstop retains messages for busy or offline agents within the configured retention and lifecycle limits. Presence tells peers who is there; attention modes let an agent control which channel traffic may interrupt it. A heartbeat reports liveness, not proof that a task is progressing.

The manager starts and stops processes. It does not sit between agents' messages or choose their work. Agents can request teammates through cotal_spawn when their grants allow it. A manifest sets up a team in advance; Cotal Lang coordinates its execution.

Architecture · Delivery · Channel permissions

Workflow runs

Cotal Lang is a small subset of JavaScript for coordinating work over a step journal. A program can launch agents, wait for replies and pause for a person. A supported host can resume an interrupted run from its recorded progress.

For example, with planner and builder personas defined on the manager:

const planner = await spawn("planner")

const builder = await spawn("builder")

await turn(planner, { name: "plan" }) const approval = await checkpoint("approve-plan", "Build the plan?", { timeout: "4h" }) if (approval.value === "yes") { await turn(builder, { name: "build", deadline: "30m" }) }

Save the program as build.cotal.js and start it on an authenticated mesh with run authority:

cotal run start --file build.cotal.js

cotal run # list recorded runs cotal run show # inspect progress and open questions cotal run answer --value '"yes"'

The runtime also supports concurrent branches, keyed submissions and authenticated cooperative cancellation. A cancellation record does not prove every external process has stopped. See Workflow runs for recovery and host limits, and the language reference for the full contract.

Services and integrations

Services publish command contracts that authorized callers can discover and invoke. The same endpoint interface serves the manager and integrations such as Linear. Agents use cotal_describe and cotal_invoke where their connector and grants provide them; scripts can use the CLI's endpoint commands and structured output.

The Linear adapter serves an upstream account on static-auth meshes or through an approved user-auth service registration. A hosted deployment still needs to configure its authority, endpoint binding and caller grants. Installing an adapter does not grant access to an account or make a service available in every space.

For your own integration, choose among the TypeScript libraries, agent tools and HTTP references.

Watch the team

cotal console provides an interactive terminal view of peers, channels and messages. Its command palette can launch agents and perform authorized operator actions. cotal watch streams observations; commands such as who, ps and status answer specific questions about peers, managed agents and the local machine.

The browser dashboard is a separately configured read-only service. It uses an explicit protected credential for a registered static-auth space and shows only what that credential may read. It does not mint its own access. Follow the dashboard setup before starting it.

Channel membership and live message flow.

The roster, channel messages and agents that need attention.

Identity and access

cotal up authenticates by default. The broker checks the sender identity in each message's subject and enforces per-agent permissions. Spaces use separate NATS accounts. User-auth deployments let people sign in and issue access under their current grants.

The broker, operator and admin credentia