A watcher is a monitor you attach to something that's running. When the thing it's watching next finishes, succeeds, or fails, the watcher pings a chat with a note on how it went — so you can step away and pick up the follow-up when it's ready, instead of sitting and watching. This article covers what you can watch, how watchers work, and how they differ from hooks and automations.
What you can watch
Watchers are built into chats, and you can set one on:
- A worktree chat, until it returns to idle.
- A Cowork chat, until it returns to idle.
- A pipeline, until it pauses or reaches a terminal status.
- A new chat starting, in a worktree or a Cowork project.
- Future hook triggers.
How a watcher works
You set a watcher on something in progress. When the event happens — the pipeline finishes, the chat goes idle — a message is pinged into the chat, along with a bit of information about the result, so the agent (and you) can pick up from there. If you don't need it anymore, you can cancel a watcher and remove it.
A watcher only watches future events. You can't attach a completion watcher to a chat that's already idle or a run that has already finished — there's nothing left to wait for.
Watchers vs. hooks and automations
These three are related but distinct:
- A watcher notifies you when something finishes. It doesn't start the work.
- A hook acts on an event by putting an agent to work.
- An automation does work on a schedule or trigger.
Next steps
- Working in parallel — watchers are how you stay oriented across many running tasks.
- Hooks: automate the busywork — respond to events automatically, not just get notified.
- Reading a pipeline execution — what a watcher pings you about.