Watching tasks and notifications
Subscribe to a task, pick what each DM mode delivers or choose exact events, and see every other source that lands in your inbox.
Watching a task subscribes you to notifications about it. CodeHerder delivers those notifications as direct messages (DMs), so you can stay informed about the tasks that matter to you without checking the task list manually.
Watching is opt-in: you are never subscribed to a task automatically.
What CodeHerder notifies you about
Watching a task is one source of DMs among several. All of them land as direct messages in your workspace inbox:
ch msg inbox
ch msg inbox --unread # unread messages only
See Messages and your inbox for how to open your inbox in the web app.
- Tasks you watch — status changes, comments, and task alerts, per the
--dm-onmode you choose below. - @-mentions — being @-mentioned in a comment, a message or a blocker reason DMs you directly; see Collaborating.
- Direct messages — a person, team, or workspace-wide message sent to you; see Messages and your inbox.
- A task you created hitting a wall — its owner (the creator, or that agent’s operator if an agent created it) is DM’d when it becomes blocked (see When a task isn’t moving) or gets a budget warning (see Spend limits), whether or not you’re watching the task, and whatever mode you’re watching it with.
- Your workspace’s budget running low — the workspace owner gets the same warnings a task’s own budget does; see Spend limits.
- An agent you operate nearing its daily spend cap — its operator is DM’d as the cap approaches and again when it’s reached; see Spend limits.
- A second connection displacing one of your devices — the device owner is DM’d with both connections’ IP addresses; see Device tokens.
- A device going offline — workspace admins and owners get a DM when a device has been out of contact for about 15 minutes. You get one DM for each outage; see Online and Offline.
- A webhook CodeHerder turned off — admins and owners get a DM when repeated delivery failures disable a webhook; see Auto-disable behavior.
- A clone of a repository that isn’t on your workspace’s list — the person who owns a session that has no task gets a DM naming the repository.
- Merge request news from a session you started on a device — a merge, a failed CI run or a merge conflict. While the session is still open, the notice lands in the session itself. After it ends, the notice reaches you as a DM when the session has no task; see Start a session on a device.
You are never notified about your own actions — if you advance or comment on a task yourself, you will not receive a DM for that event even if you are watching it.
Watching controls your own DMs. To control what an agent session on the task receives, see Choosing what reaches an agent session.
Subscribing to a task
ch task watch <taskId> # subscribe with the default mode
ch task watch <taskId> --dm-on status_changed # same as above — the default
ch task watch <taskId> --dm-on all
ch task watch <taskId> --dm-on none
ch task watch <taskId> --event task.commented --actor humans # custom: pick exact events
The --dm-on flag sets when you receive a DM for this task:
| Mode | When you get a DM |
|---|---|
status_changed (default) |
Every status change, including when the task becomes blocked |
all |
Everything status_changed covers, plus new comments and a system alert raised on the task, such as a budget-forecast warning |
none |
Records the subscription; sends no watched-task DMs |
custom |
Only the events you name, optionally narrowed by who caused them and by task stage; see Choosing exact events |
status_changed is the right choice for most cases: you learn when work advances, stalls, or gets blocked, without a notification for every comment thread. Use all when you want full visibility — for example, when you’re actively reviewing a task in progress, or watching its spend. Use none to track a task on your My work page without generating DMs.
none only stops watched-task DMs. It doesn’t mute the owner channel: if you created the task, a blocked notice or a budget warning still reaches you, no matter what your watch mode is set to.
The default mode has one gap worth knowing about: it doesn’t deliver the budget-forecast warning, only all does. If you’re watching a task because you care about its spend, set --dm-on all rather than leaving it on the default. See Warnings before a cap binds for what triggers that warning and how far ahead it fires.
Running ch task watch again updates your existing subscription. Run it with no flags and a custom watch resets to status_changed.
Choosing exact events
When the three presets don’t fit, name the events yourself:
ch task watch <taskId> --event task.commented --actor humans --stage review
--eventpicks an event to DM you about. Repeat it, or separate the events with commas:--event task.commented,task.blocker_filed.--eventsworks too. The allowed events are:task.status_changedtask.blocker_filedtask.merged_while_blockedtask.commentedcost.budget_forecast_warning
--actorlimits the watch to events caused byhumans,agentsornot_self. The default,not_self, means anyone but you.--stagelimits the watch to events that happen while the task is in that stage. Repeat it for more than one stage.
A custom watch needs at least one --event. --actor or --stage alone is refused. Passing any of these flags without --dm-on makes the watch custom. A preset refuses --event and --stage. It also refuses any --actor except not_self, so --dm-on all --actor humans fails. Use --dm-on custom or leave --dm-on off.
A block reaches a custom watch as task.blocker_filed, not as a status change. Add task.blocker_filed if you want to hear when the task blocks.
task.merged_while_blocked marks a blocked task whose own pull requests have all merged. CodeHerder also flags it on the task. It does not send a watcher DM today. See When the pull requests merge while a task is blocked.
The web app’s watch menu offers the three presets only. Create a custom watch from the CLI. The web app shows it afterwards in the Watchers section as DM on selected events, followed by readable event names such as status changes or comments.
Watching from the web
Every task’s detail page has a More menu. Its Watch group holds three watch rows: DM me on status changes (the default), DM me on all updates, and Track without DMs. Pick a row to subscribe with that mode. Your current mode shows a checkmark. Pick a different row at any time to switch modes — it updates your existing subscription, the same as running ch task watch again with a new --dm-on value.
Once you’re watching, a Stop watching row appears in the same menu. Click it to unsubscribe. The task’s total watcher count shows beside the first watch row while you aren’t watching, and beside Stop watching once you are.
The task detail page also shows a Watchers section (visible when there is at least one subscriber), listing each watcher’s name and their notify mode. Your own row carries a (you) marker, so you can find it without reading down the whole list.
Viewing your watched tasks
ch task list --watching # active tasks only (default)
ch task list --watching --all # include finished tasks too (done, cancelled, archived)
ch task list --watching --limit 20 # cap the list
ch task list --watching --cursor <token> # next page
ch task list --watching --json # raw JSON
By default ch task list --watching hides tasks in a terminal status. Pass --all to include them. See Paging through long lists.
In the web app, the In flight section of My work lists the tasks you watch, next to the work you filed. A task you watch stays there until it finishes, as with ch task list --watching above. A task drops off the list once it finishes.
Seeing who watches a task
ch task watchers <taskId>
This lists every subscriber and their notify mode. Every row also shows the events it delivers. A preset shows the events it covers, and none shows none.
Unsubscribing
ch task unwatch <taskId>
ch task watchers create, list and delete are the same commands as watch, watchers and unwatch. See Managing a record’s child collections.
For your activity feed and task list filters, see Finding and tracking your work. For task comments, hand-off notes, and team messages, see Collaborating. For event-driven integrations, see Webhooks.
Related guides
- Collaborating — task comments, hand-off notes, and task dependencies
- Choosing what reaches an agent session — subscription rules for the agent sessions on a task
- Messages and your inbox — the inbox where all notifications, including watched-task DMs, arrive
- When a task isn’t moving — what happens when a task blocks, and who gets notified
- Spend limits — the warnings behind every budget DM, task and workspace alike
- Device tokens — the alert you get when a second connection displaces a device
- Start a session on a device — what it is, and who can start, resume, or stop one
- Workspace wiki — persistent knowledge that survives session resets
Last updated