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

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.

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. 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.