Signal reference

For a complete setup, start with Publish agent updates.

Schema files

A catalog is a directory of NAME@VERSION.json files containing JSON Schema 2020-12 definitions. Use self-contained schemas: $ref and related reference keywords are unsupported, and format annotations do not enforce formats. A schema of true accepts any JSON value within CoCo’s size limits.

CoCo reads direct files only, excluding nested directories and symlinks. Select the catalog explicitly with --signal-catalog DIR.

Publication access

--allow-emit NAME@VERSION permits exactly that signal version. Repeat the option for multiple grants. A bare name selects version 1. Every grant requires a matching definition in the selected catalog.

The emitting Codex thread must belong to a CoCo workspace in the configured repository. Reading definitions or loading a catalog alone grants no emission or message-sending permission.

signals.types lists definitions and their emitAllowed status. signals.emit accepts:

{
  "name": "review.requested",
  "version": 1,
  "payload": { "pr": 42 },
  "idempotencyKey": "review-pr-42-first-pass"
}

Reuse an idempotencyKey when retrying the same update after an uncertain response. CoCo returns the existing record while it remains retained. Choose a new key for a new update. Invalid payloads are rejected without saving a signal and report which field or schema rule failed.

Change a definition

Once loaded, a version cannot be overwritten. Add a new file such as review.requested@2.json and explicitly grant that version to agents that should use it. Reformatting an unchanged schema is fine; changing its description or rules requires a new version.

Files are loaded when the MCP server starts, not continuously. A running server keeps its selected definitions. Invalid files or conflicting versions make the new server fail to start without loading a partial catalog. Removing a file does not erase old signals or revoke a running server’s existing permission.

Without --signal-catalog, the read-only signals.types tool shows previously loaded definitions for that repository; none are enabled for publication. The CLI reads published updates, not definitions.

Resume a reader

For another application or a script, use JSON output:

coco signal list --limit 20 --json
coco signal list --after '<nextCursor>' --json
coco signal list --follow --json

Each page contains signals, nextCursor, and hasMore. Save nextCursor after processing the page, and pass it as --after with the same filters. Continue reading while hasMore is true. JSON follow emits one page per line; unchanged pages are not repeated. After a disconnect, run the command again with the saved cursor. Consumers should recognize repeated records by their id before performing an external action.

Retention and privacy

CoCo retains the newest 10,000 signals across all repositories. Older records are removed as new ones arrive. An expired cursor produces an error; remove --after only when you intend to restart from the retained history.

Closing or deleting a workspace does not immediately erase its signals. Use coco signal list <workspace-uuid> to find them after deletion. Reusing its name creates a different workspace and does not inherit its history.

Payloads and schemas may each contain at most 16 KiB, with at most 32 nesting levels and 2,048 values. A repository supports 128 loaded signal versions; each workspace may publish 10 new signals per second. These limits also apply when a schema accepts any JSON value.

Signal payloads are saved locally and readable by trusted MCP hosts configured for the repository. Keep secrets out of them. Publication permissions are for trusted local applications, not a security boundary between users on a shared remote service.

See the CLI reference for scope flags and filters.