Publish agent updates

A signal is a saved, structured update from an agent. Use one to report “ready for review,” an artifact location, or another milestone your workflow needs. You choose its fields and the agent receives an error if its payload does not match.

This example publishes a review request with a pull-request number.

Define the update

Create a folder outside the workspaces your agents edit:

mkdir -p ~/.config/coco/signals

Save this definition as review.requested@1.json in that folder:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "A pull request is ready for review",
  "type": "object",
  "properties": {
    "pr": { "type": "integer", "minimum": 1 }
  },
  "required": ["pr"],
  "additionalProperties": false
}

This JSON Schema accepts { "pr": 42 }. A missing number or a string such as { "pr": "42" } is rejected, allowing the agent to correct it.

Enable it for an agent

Add CoCo’s MCP server to a named profile:

[mcp_servers.coco]
command = "coco-mcp"
args = [
  "--repository", "/absolute/path/to/project",
  "--signal-catalog", "/absolute/path/to/signals",
  "--allow-emit", "review.requested@1"
]

Replace the repository and signal-folder paths. The repository must be registered with CoCo. --allow-emit selects which signal the agent may publish.

Create the workspace:

coco create review/widget --profile reviewer --jump

Ask the agent to review the pull request and emit review.requested@1 with its number when it is ready. The agent can discover the definition with signals.types and publish with signals.emit.

Read the updates

From another terminal in that repository:

coco signal list review/widget
coco signal list --name review.requested -f

The first command shows saved updates from one workspace. The second shows review requests and keeps watching for new ones. Reading leaves them available to other readers.

Use coco signal list -af to follow updates across all repositories. ls is an alias for list.

Act on a signal

Attach a hook to notify you or update another tool when the review request arrives. Another application can also read saved signals through MCP.

Signals are saved locally, including after the workspace is deleted. Keep secrets out of payloads. CoCo validates the fields; you still need to verify the agent’s claim.

See Signal reference for schema rules, version changes, publication permissions, retention, and resumable readers.