AI
Watch for events with sensors
Schedule prompts for an agent, and let it watch for events with one-shot watchers or approved scripts that wake it.
Start with Open Codex chat if you have not used an agent before.
What a sensor is
A sensor is an agent on a schedule, without the model. It does a cheap check, or nothing at all, until something is worth a turn, then wakes the agent with a normal turn. It runs with the access you gave the agent in its Connectors menu (CoCalc access, GitHub, Cloudflare), and no more. If you know what your agent can do, you know what its sensors can do.
There are three kinds:
- Scheduled prompts: a prompt sent to the agent on a schedule, such as a weekday 07:00 briefing. You set these up yourself.
- Watchers: CoCalc's own one-shot checks that an agent sets for itself (for example "wake me when the CI checks on this pull request finish", or "run this build in a terminal and wake me when it exits"). They need no approval; they wake the agent once, or give up after a day.
- Scripts: a small program the agent writes to watch something over time, such as new GitHub issues. You approve the exact script first.
Sensors work with Codex, Claude Code and other agents registered in a project. They need a project with internet access, which comes with a paid membership. Your membership also sets how many sensors a project may run, how often they may run, how many watchers your agents may have at once (in total and per agent), and how many agent turns all of your sensors and watchers may start in any 24 hours (each sensor can also set a lower limit of its own). Each wake is a turn paid by the person who set up or approved the sensor.
Schedule a prompt
Open the chat's Connectors menu (the plug button next to the message box), choose Sensors, then Schedule a prompt. Give it a title and the prompt, choose Daily at (times in your time zone) or Every some minutes, and optionally Weekdays only. Each scheduled turn starts with "[Scheduled prompt]", so the agent knows why it is running.
Approve a script
Ask the agent for what you want watched, for example "tell me when someone opens a GitHub issue labeled urgent, checking every 30 minutes". The agent writes the script, tests it, and proposes it. In the Sensors dialog the proposal shows its purpose, schedule, limits, the access it uses and the complete script.
- A script runs like one of the agent's commands: in this project's software, as you, with only the connectors it lists, if you turned them on for the agent. Read it before you click Approve and run.
- Reject discards the proposal.
- Any change the agent proposes later needs approval again. The approved version keeps running until you approve the change.
- If the project's software (its RootFS image) changes, script sensors pause until you review and resume them.
A script's data comes from outside sources, so its wakes say that they are not from a person and that the data is information, not instructions.
If the agent has not started on a sensor's wake yet (it may be busy with another turn), the sensor holds its later wakes and sends them together in the next one: one turn with everything, not a queue of turns. A scheduled prompt is skipped while the previous one still waits.
Watch and control sensors
The same dialog shows each sensor's status, last run and outcome, the next run, and how many times it woke the agent today (UTC).
- Run now runs it once, outside its schedule.
- Pause stops scheduled runs; Resume starts them again. Whoever resumes a sensor takes over its approval, so its runs and wakes are then theirs. Watchers run once and can't be resumed; ask the agent to set a new one.
- Run log lists recent runs with their output and errors, and which connectors each run was given. The agent can read its own sensors' logs too.
- Delete removes the sensor and its log.
A sensor pauses itself after five failed runs in a row, when its approver loses access to the project, when a connector it uses is turned off, or when the project loses internet access. The dialog shows the reason, and the person it runs as gets a notification.
Scheduled thread automations
Sensors replace the earlier scheduled thread automations, which no longer run. Schedule a prompt for the same job instead.