Propose sensors with the CLI

Sensors from the agent's side

Agents use cocalc sensor with their runtime identity. A sensor is the agent on a schedule, without the model, with the access the approving person gave the agent. People approve, resume and run sensors in the agent's Sensors dialog; there is no CLI command for that. See Watch for events with sensors for that side.

Wait for something: set a watcher

cocalc sensor watch ci --repo sagemathinc/cocalc-ai --pr 992
cocalc sensor watch file --path build.log --match 'BUILD DONE'
cocalc sensor watch at --at 2026-10-16T15:00:00Z --note "check that PR 992 merged"
cocalc sensor watch exit -- make test
cocalc sensor watch agent worker --until failed

watch ci uses the agent's GitHub connector, and is refused when the agent does not have it. Then watch the checks with the project's own gh login: cocalc sensor watch exit -- gh pr checks 992 --repo sagemathinc/cocalc-ai --watch.

watch exit starts the command in a project terminal, which keeps running after the turn ends, and the wake brings its exit code and the end of its output.

watch agent wakes a manager agent when a peer in its Agent Networks finishes a turn, whoever started it: --until ended (any turn, the default), failed (a turn ends without completing) or idle (a turn ends and nothing is running or waiting).

Watchers are CoCalc's own one-shot checks, so they need no approval. The agent ends its turn and gets exactly one turn when it happens, or when the watcher gives up (after 24 hours unless --hours says otherwise). The membership sets how many watchers one person's agents may have at a time in total (unset: five) and, optionally, how many one agent may have. Watchers count toward the same daily wake budget as sensors. A paused watcher can never resume, so it no longer counts; delete watchers you no longer need with cocalc sensor delete <id>.

Watch over time: propose a script

{
  "title": "GitHub: new urgent issues",
  "purpose": "Wake me when an issue labeled urgent is opened in our repository.",
  "language": "python",
  "uses": ["github"],
  "script": "import json, os, subprocess\n...",
  "schedule": {"kind": "interval", "minutes": 30},
  "max_wakes_per_day": 12
}

The script runs like a command in the agent's turn: in the project's software, in the chat's directory, as the approving person, with the connectors listed in uses (cocalc, github, cloudflare) if that person gave them to the agent. It gets COCALC_SENSOR_STATE, a JSON file for remembering what it already reported. To wake the agent it prints one line such as {"wake": true, "summary": "2 new issues", "data": {"issues": [...]}}. A run that prints no wake line is quiet. Daily schedules use {"kind": "daily", "times": ["07:00"], "timezone": "Europe/Berlin"}. cocalc sensor --help prints the full contract.

cocalc sensor test --file spec.json
cocalc sensor propose --file spec.json

test runs the script once and reports whether it would wake the agent. It runs in the agent's own environment; a scheduled run is a fresh container without the project's secrets (/run/secrets, $COCALC_SECRETS), with an empty /tmp, so test warns when the script uses either. After 5 failed runs in a row a sensor pauses itself and its person is notified. propose records the exact spec for review; nothing runs until a person approves it. To change an approved sensor, propose again with --sensor <id>. A spec with "kind": "prompt", a title, a prompt and a schedule proposes a scheduled prompt instead.

Inspect

cocalc sensor list
cocalc sensor show <id>
cocalc sensor pause <id>
cocalc sensor delete <id>

show includes recent runs with their outcome, summary, output and errors.