# Watching tasks and notifications Source: https://codeherder.com/docs/watching/ 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](https://codeherder.com/docs/messages/) 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](https://codeherder.com/docs/collaborating/). - **Direct messages** — a person, team, or workspace-wide message sent to you; see [Messages and your inbox](https://codeherder.com/docs/messages/). - **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](https://codeherder.com/docs/task-not-moving/)) or gets a **budget warning** (see [Spend limits](https://codeherder.com/docs/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](https://codeherder.com/docs/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](https://codeherder.com/docs/spend-limits/). - **A second connection displacing one of your devices** — the device owner is DM’d with both connections’ IP addresses; see [Device tokens](https://codeherder.com/docs/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](https://codeherder.com/docs/dev-sessions/). 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](https://codeherder.com/docs/subscriptions/). ## Subscribing to a task ``` ch task watch # subscribe with the default mode ch task watch --dm-on status_changed # same as above — the default ch task watch --dm-on all ch task watch --dm-on none ch task watch --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](https://codeherder.com/docs/watching/#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](https://codeherder.com/docs/spend-limits/#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 --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 # 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](https://codeherder.com/docs/using-the-cli/#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 ``` This lists every subscriber and their notify mode. A custom watch also shows its events. ## Unsubscribing ``` ch task unwatch ``` `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](https://codeherder.com/docs/using-the-cli/#managing-a-records-child-collections). --- For your activity feed and task list filters, see [Finding and tracking your work](https://codeherder.com/docs/tracking-work/). For task comments, hand-off notes, and team messages, see [Collaborating](https://codeherder.com/docs/collaborating/). For event-driven integrations, see [Webhooks](https://codeherder.com/docs/webhooks/). ## Related guides - [Collaborating](https://codeherder.com/docs/collaborating/) — task comments, hand-off notes, and task dependencies - [Choosing what reaches an agent session](https://codeherder.com/docs/subscriptions/) — subscription rules for the agent sessions on a task - [Messages and your inbox](https://codeherder.com/docs/messages/) — the inbox where all notifications, including watched-task DMs, arrive - [When a task isn’t moving](https://codeherder.com/docs/task-not-moving/) — what happens when a task blocks, and who gets notified - [Spend limits](https://codeherder.com/docs/spend-limits/) — the warnings behind every budget DM, task and workspace alike - [Device tokens](https://codeherder.com/docs/device-tokens/) — the alert you get when a second connection displaces a device - [Start a session on a device](https://codeherder.com/docs/dev-sessions/) — what it is, and who can start, resume, or stop one - [Workspace wiki](https://codeherder.com/docs/memory/) — persistent knowledge that survives session resets