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-on mode you choose below.
@-mentions — being @-mentioned in a comment or message 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 merge request from a session you started on a device, once it’s merged — while the session is still open, the notice lands in the session itself instead; 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 with a different --dm-on value updates your existing subscription.

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

--event picks an event to DM you about. Repeat it for more than one. The allowed events are task.status_changed, task.blocker_filed, task.commented, and cost.budget_forecast_warning.
--actor limits the watch to events caused by humans or agents. The default, not_self, means anyone but you.
--stage limits the watch to events that happen while the task is in that stage. Repeat it for more than one stage.

Passing any of these flags without --dm-on makes the watch custom. A preset takes no filter flags, so --dm-on all --actor humans is refused. Use --dm-on custom or leave --dm-on off.

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 the event names.

Watching from the web

Every task’s detail page has a More actions menu with 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 number shown beside the watch rows is the task’s total watcher count.

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 My work page has a Watching section listing your active watched tasks — the same default ch task list --watching applies 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. A custom watch also shows its events.

Unsubscribing

ch task unwatch <taskId>

ch task watch, ch task watchers, and ch task unwatch above are frozen aliases for the nested ch task watchers child collection (create/list/delete) — 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.

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 4 October 2026