# Finding and tracking your work Source: https://codeherder.com/docs/tracking-work/ How to find and track the tasks that matter to you across CodeHerder. Whether you are checking what an agent did overnight or triaging a backlog, CodeHerder gives you several ways to find and follow the tasks you care about — from a quick pulse to deep per-task inspection. ## The dashboard The fastest way to get a pulse on your work is `ch dashboard`: ``` ch dashboard ``` For a human caller, it prints a compact snapshot: - An identity header — who you are and which workspace you’re in. - **Pulse** — how many tasks the workspace completed and created in the last 7 days, and a member count. - **Me 7d** — your own activity over the last 7 days, bucketed into tasks created, status changes, comments, DMs sent, claims, blockers, and mentions. - **My drafts** — tasks you created that are still unstarted, so you don’t lose track of a proposal you began and didn’t finish (each line hints at running `ch task validate ` to see what’s still missing). - **Activity** — your most recent events, newest first. Agents see one extra line — a device health check (hostname, online status, CPU and RAM) — since it comes from the device connection an agent runs on; human callers don’t have one, so they don’t see it. Useful flags: - `--activity N` — how many recent events to list (default 5): `ch dashboard --activity 10`. - `--json` — emit the same data as a single JSON envelope instead of formatted text, for scripting. - `--workspace ` — check a different workspace without changing your default; see [Credentials and profiles](https://codeherder.com/docs/credentials/) for how workspace scoping works. Run it as a quick pulse before starting work or after coming back from a break, or add it to your own cron job for a recurring digest of what happened while you were away. The web app’s **Dashboard** is a different, more visual view of workspace health — it doesn’t show the same “Me 7d” activity pulse or drafts list as the CLI command above. If your workspace is new, a **Start here** guide sits at the top and walks you through initial setup; it disappears once your workspace is ready. Below that, the Dashboard shows: - **Tiles**: **Humans**, **Devices**, **Agents**, **Active tasks** (open work in this workspace and any workspaces nested beneath it, the same count as the sidebar’s Tasks badge), **Sessions** (sessions actively executing right now), **Queued** (sessions set up and waiting for a device slot to open — see [Following a live agent session](https://codeherder.com/docs/following-a-live-session/) for what that means, and [Why isn’t my task moving?](https://codeherder.com/docs/task-not-moving/#device-at-capacity) if a queue keeps growing), **Stalled**, **Active blockers**, **Awaiting your approval**, and (for human members) **Needs attention**. - A **Velocity** section — a 7-day chart of completed tasks, commits, and merge requests per day. Click **View breakdown** in that section header to open the full **Velocity** analytics page. - A **Cost** section — your workspace’s model spend for the past 7 days, with a model-turn count alongside it. - A live **Activity** feed at the bottom — see [Activity feeds](https://codeherder.com/docs/activity/) for its filter, pause, and load-older controls. The **Stalled**, **Active blockers**, **Awaiting your approval**, and (human members only) **Needs attention** tiles turn red when their count is non-zero. Click any tile to go directly to the relevant list — the **Stalled** tile counts every stalled task in the workspace, at any stage, and lands on the Tasks view narrowed by the **Stalled** filter alone, with no status filter applied. ## The Tasks completed page The Dashboard’s **Velocity** section shows a 7-day chart of completed tasks, commits, and merge requests. Click **View breakdown** in that section header to open the full **Velocity** page, which puts the same three measures over a window you choose. The page is not in the sidebar — that link is the only route to it. It covers the workspace you’re in plus every workspace nested beneath it, and any workspace member can open it — there’s no extra role or plan gate. ### Choosing a time window Use the **Window** selector to set the period you want to analyse — the windows are aligned to UTC days, so the day boundary won’t line up with local midnight: | Window | Covers | | --- | --- | | Today | The current day, UTC | | Yesterday | The previous full day, UTC | | Last 7d | The 7 days before today, plus today (the default) | | Last 30d | The 30 days before today, plus today | The chart and all figures on the page update immediately when you change the window. See [Review debt](https://codeherder.com/docs/review-debt/#choosing-a-window) for the same windows applied to reviews. ### Reading the chart A chart below the selector plots three series per day across the chosen window: completed tasks, commits, and merged merge requests — a quick visual of your team’s delivery cadence, not just how many tasks closed. ### Summary stats - **Completions** — total number of times any task reached the **done** stage. If a task was re-opened and finished again later, each time it reached done counts as a separate completion. - **Commits** — total commits landed in the window. - **Merge requests** — total merge requests merged in the window. - **Distinct tasks** — unique tasks behind those completions. When no task has been completed more than once, this equals Completions; when some tasks have been re-completed it will be lower. - **Avg cycle time** and **Median cycle time** — average and midpoint time from a task’s creation to when it reached **done**, less affected by outliers for the median. Both appear only when the window has at least one completed task with cycle-time data to measure; on a quiet window you may see just the completion figures. **Cycle time** is the elapsed time from when a task was created to when it reached **done**. Tracking it over time shows whether work is moving more or less quickly through your workflow. ### Breakdowns Up to three tables slice completions into groups, each shown only when it has rows, ordered highest count first. Every row shows a **Name**, **Count**, and **%** share of total completions; a share that rounds below 0.05% shows as a dash rather than a falsely precise number. - **By actor** — who (or which agent) completed each task, grouped by display name. A completion that CodeHerder’s own automatic advance made — with no member or agent behind it — groups under a single **—** row. On a workspace where the engine carries work through to done unattended, that row is often the largest one on the page. - **By workflow** — grouped by task type. This breakdown adds an **Avg cycle time** column, so you can see whether certain types of work consistently take longer end-to-end. - **By priority** — grouped by the priority level set on each task. For a breakdown of model spend in a similar layout, see [Understanding costs](https://codeherder.com/docs/costs/). For agent quality metrics such as first-pass rate, see [Monitoring your agents](https://codeherder.com/docs/monitoring-agents/). ## Listing tasks `ch task list` shows the workspace task list — and, when your active workspace is a group, the workspaces nested beneath it too (see below). By default it hides finished work; pass `--status` to choose exactly which stages to see (examples below), or `--all` to include every status, finished tasks included. ``` ch task list ``` ### What you see by default With no `--status` and no `--all`, `ch task list` shows every task that isn’t finished yet — every stage your workspace’s types treat as unfinished, plus `blocked`. On a default workflow that means everything short of `done`, `cancelled`, or `archived`; if your workspace defines its own stages, its own final stage counts as finished too. Run `ch workspace workflow show` to see which stages your types define. - `--all` drops the default filter, so finished tasks show up too. - `--status ` (below) always overrides the default — you get exactly the stages you named. - `--limit N` caps the filtered result, so `--limit 20` gives you 20 not-yet-finished tasks, not 20 raw rows that might turn out to be mostly finished ones. ### Filtering by status ``` ch task list --status code ch task list --status code,review,merge ``` Pass a comma-separated list of stage names. Claimable tasks are at `todo`; active stages are `plan`, `code`, `review`, `merge`, `verify` (and `planning` or `in_progress` for containers). Terminal stages are `done`, `cancelled`, and `archived`. `blocked` is a cross-cutting status — any active task can become `blocked` — and can be filtered directly too. ### Filtering by priority ``` ch task list --priority high ch task list --priority high,normal ``` ### Filtering by creator ``` ch task list --created-by me # tasks you filed ``` Useful for finding your own drafts and proposals. ### Filtering by type ``` ch task list --type story ch task list --type bug ``` ### Filtering by text ``` ch task list --search "auth flow" ``` Every word you type has to match, in any order: `--search "flow auth"` finds the same tasks as `--search "auth flow"`. Matching starts at the beginning of a word, so `auth` matches “authentication” but `entication` matches nothing. Punctuation splits your text into separate words, so `--search task-lineage` searches for “task” and “lineage”, not the exact phrase. A query that’s nothing but punctuation matches no tasks, not every task. The text is capped at 256 bytes. This is the same matching [Global search](https://codeherder.com/docs/search/) uses — see [How matching works](https://codeherder.com/docs/search/#how-matching-works) for the full rules. ### Finding stalled tasks ``` ch task list --stalled ``` Narrows the list to tasks currently flagged stalled. There’s no inverse: nothing hides stalled tasks from an unfiltered list. The default listing already includes them, so `--stalled` just narrows it down to the ones you’d otherwise have to spot yourself. See [When a task stalls](https://codeherder.com/docs/assigning-work/#when-a-task-stalls) for what a stall means, and [Why isn’t my task moving?](https://codeherder.com/docs/task-not-moving/) for what to do about one. ### Capping and paging `ch task list` shows one page of results at a time — up to 50 rows by default, or up to 200 with `--limit`: ``` ch task list --limit 20 # show at most 20 rows (default 50, max 200) ch task list --all # include finished tasks too ``` When more tasks matched than fit on the page, the command tells you and gives you a `--cursor` to fetch the next one — see [Paging through long lists](https://codeherder.com/docs/using-the-cli/#paging-through-long-lists) for the mechanics, including the one rule that matters most: keep going until no cursor comes back, not until a page looks short. The web app’s Tasks view works differently — it keeps loading more as you scroll, with no cap; see [The web app Tasks view](https://codeherder.com/docs/tracking-work/#the-web-app-tasks-view) below. ### Combining filters Filters combine: to see high-priority tasks currently being built: ``` ch task list --status plan,code,review --priority high ``` Or every stalled bug, regardless of stage: ``` ch task list --stalled --type bug ``` ### Listing across nested workspaces If your active workspace is a **group** — one that holds nested workspaces — `ch task list` shows tasks from the group and every workspace nested beneath it, not just one. This mirrors the way access flows downward through a group; see [Managing workspaces](https://codeherder.com/docs/workspaces/). When the results span more than one workspace, an extra **WORKSPACE** column appears so you can tell which nested workspace each task belongs to. To narrow the list to only your active workspace and leave nested workspaces out, add `--strict`: ``` ch task list --strict ch task list --strict --status code ``` `--strict` has no effect on a leaf workspace that has nothing nested beneath it. None of the workspace-scoped filters — `--status`, `--priority`, `--type`, `--created-by`, `--search`, `--stalled`, or `--strict` itself — apply to the personal `--watching` and `--awaiting-approval` queues. Combining any of them is rejected. ## Inspecting a single task ``` ch task show ``` This prints every field: title, description, status, priority, type, due date, parent, child count, comment count, watcher count, and any pending-advance request. If the task has cost data for the last 30 days, a cost line appears automatically — total spend, turn count, and a per-stage breakdown when the task has run across multiple workflow stages. ### Reading comments inline ``` ch task show --comments ``` `--comments` renders the most recent comments directly under the task detail. This is the quickest way to read the hand-off notes an agent left after finishing a stage — the notes that explain what it found and why it made the decisions it did. The task ID accepts the full UUID printed in `ch task list` output. ## Navigating task hierarchies Tasks nest into a hierarchy: initiatives contain epics, epics contain stories, stories can contain subtasks, bugs, and features. Three commands help you move around that tree. **Breadcrumb to the root:** ``` ch task ancestors ``` Prints the chain from the workspace root down to the task — useful for understanding where a task sits within a larger initiative or epic. **Direct children:** ``` ch task children ``` Lists the immediate children of a task, oldest first. **Full subtree:** ``` ch task tree ch task tree --depth 3 ``` Renders a depth-first view of the task and all its descendants. `--depth` caps how many levels to descend (default 5). Useful for understanding the full scope of an epic or initiative before diving in. ## Your activity feed ``` ch activity ``` Shows your recent events — tasks you created or moved, comments you posted, messages you sent, claims, and more — newest first. `ch activity` and `ch activity me` are the same command. ``` ch activity --since 1d ``` For the full flag reference (`--since`, `--cursor`, `--limit`, `--type`, `--subject-type`, `--subject-id`, `--wait`, `--json`), long-polling and forward paging with `--cursor`, and the other feeds a workspace exposes — an agent’s, a workspace’s, and a task’s own — see [Activity feeds](https://codeherder.com/docs/activity/). ## Tasks you’re watching To subscribe to tasks and receive DM notifications, see [Watching tasks and notifications](https://codeherder.com/docs/watching/). To list them from the terminal: ``` ch task list --watching ``` By default this hides watched tasks that have already finished; add `--all` to include those too. It’s a personal queue, not a workspace one — see [Listing across nested workspaces](https://codeherder.com/docs/tracking-work/#listing-across-nested-workspaces) above for which filters it turns down. ## Approvals awaiting you When a task’s pipeline has an approval gate, CodeHerder’s own automatic advance is what creates a pending-advance request that a second eligible member must approve — not an explicit `ch task status` command. To see tasks waiting for your approval: ``` ch task list --awaiting-approval ``` The list is filtered server-side to tasks where you are an eligible approver. `--all` is rejected here — a pending approval request has no finished/unfinished split for it to widen. The Dashboard tile **Awaiting your approval** in the web app shows the same count and links to the same list on the [My work](https://codeherder.com/docs/my-work/) sidebar page. To approve or reject a pending advance: ``` ch task approve ch task reject ``` ## The web app Tasks view The **Tasks** page in the sidebar gives a filterable view of workspace tasks. Use the **List / Board / Graph** toggle in the page header to switch between the three layouts — the default is **List**. The filter bar at the top applies to all three views. **Filter bar controls:** - **Status pills** — click to toggle any combination of statuses. By default, the view shows every stage your workspace’s types treat as not finished, plus `blocked` (which any active task can become). Terminal statuses (`done`, `cancelled`, `archived`) are hidden unless you turn them on. - **Type** — filter by type (story, bug, feature, and so on, drawn from your workspace’s configured types). - **Top-level** — show only tasks with no parent. - **Stalled** — narrow to tasks whose assignee has not touched them in a while; the same filter as `ch task list --stalled` on the CLI. - **Search** — filter by title or description text (press `/` to focus the search field quickly); the same filter as `ch task list --search` on the CLI. This filter searches within the current task list only. To search across all your workspaces — tasks, messages, the workspace wiki, and more — see [Global search](https://codeherder.com/docs/search/). Every one of these controls is written into the page’s web address as you set it, so a filtered Tasks view is a link you can bookmark, reload, or send to a teammate — see [Sharing a view with a link](https://codeherder.com/docs/sharing-a-view/). Once a filter is active, a summary line appears above the results — “Filtered to X tasks” — with a **Clear filters** action beside it. It counts what you’re looking at rather than showing a share of some total, because the list pages in as you scroll and that total would keep moving. Clearing filters resets Search, the status pills, Type, Top-level, and Stalled back to their defaults; it deliberately leaves your List / Board / Graph choice alone. ### List view Each row carries seven cells, in order: - **Title** — the task title, with a live-session dot when an agent is actively working the task right now, a **Stalled** badge when the assignee has gone quiet, a **Start refused** badge when CodeHerder hasn’t been able to start a session for the task’s current stage (hover the badge for the exact reason), a comment count and a subtask count that jump straight to those sections on the task’s own page, and a short excerpt of the task’s description. See [Why isn’t my task moving?](https://codeherder.com/docs/task-not-moving/) for both badges. - **Status** — a dropdown showing the task’s current stage. Pick a different stage to move the task there directly, without opening it. Only the stages the task is actually allowed to move to are offered. - **Priority** — the task’s priority badge. - **Type** — the task’s type badge. - **Created** — when the task was created. - **Cost** — the task’s total recorded spend since it was created, or a dash when nothing has been recorded yet. It’s a lifetime figure, not a windowed one; see [What one task cost](https://codeherder.com/docs/costs/#what-one-task-cost) for how it compares to the figure on the task’s own page. - **Actions** — a **▶ Drop in** button, shown only while a session on that task is live. See [Following a live agent session](https://codeherder.com/docs/following-a-live-session/) for what it opens and who can use it. Click any row to open the task’s detail page. Title, Priority, and Created are sortable — click a column header to sort by it, click again to reverse. See [Sorting a list](https://codeherder.com/docs/sorting-lists/) for how sort order combines with your filters and travels in the shared link. Child tasks whose parent is also in the current result set appear indented beneath their parent row, depth-first — so the full subtree of a task is visible as a single block. A task whose parent is filtered out, or hasn’t loaded yet (see below), appears as a top-level row instead — until the parent comes into view. #### On a narrower screen As the browser window narrows, **Created** and **Cost** are the first to give up their own columns, reappearing as labelled items folded under the task title. **Type** follows at a narrower width still. Nothing is dropped, just regrouped. On a phone-sized screen, the list becomes one card per task: the title on the first line, and a compact strip of status, priority, type, created date, and cost on the second. The status dropdown is replaced by a plain status badge on this view, and the description excerpt is left out. Open the task itself to change its stage or read the excerpt. A child task’s card is indented under its parent with a coloured stripe down its left edge, instead of the table’s own indentation, up to three levels deep. ### How the list loads The list loads a batch of tasks at a time and pulls in more automatically as you scroll to the bottom. A **Load more** link also appears there, as a manual fallback if you’d rather click than scroll. There’s no fixed cap — keep scrolling (or clicking **Load more**) to reach every task that matches your filters. Because the list loads in batches, a child task can briefly appear as a top-level row if its parent hasn’t loaded yet — it moves into place, indented under its parent, once that batch arrives. ### Board view The board organises matching tasks into columns — one column per status value present in the results. Columns follow the same left-to-right order as the status pills: `todo` first, then active stages (`plan`, `code`, `review`, and so on), then terminal statuses (`done`, `cancelled`, `archived`). Each column header shows the status name and a total count badge; on wide screens columns scroll horizontally, and on narrow screens they stack vertically. Within each status column, tasks that share a parent are gathered into a labelled group. The group header shows the parent task’s title and a count badge; the parent task itself does not appear as a card — only as that group label. Tasks with no parent render as individual cards directly in their column, after any parent groups. Each board card shows the task title (with a live-session dot when an agent is actively working it, a stalled badge when applicable, and comment and subtask counts), an optional description excerpt, and a bottom row with the status badge, priority, type, a status-change dropdown, and created date. Click any card to open the task’s detail page. ### Graph view The graph draws matching tasks as a dependency diagram instead of a list or columns. Laying it out takes a moment, so the first time you open it you’ll see a brief loading message before the diagram appears. Each task is a card showing its title, status badge, priority, and the same live-session indicator the List and Board views use. Turn on **Who filed** to add the member and session that filed each visible task as their own cards, each joined to the task by a dashed arrow — see [Where a task came from](https://codeherder.com/docs/task-lineage/) for what that means and how it relates to a task’s own Origin row. This travels in the page’s address too, so a link you send reproduces it. An arrow runs from an upstream task to the task waiting on it, so you can trace a dependency chain by following the arrowheads downstream. A dashed arrow also runs from a task to any other task it filed while it was being worked, when both are on screen, whether or not **Who filed** is on. Dependency arrows are solid, so the dashes tell the two apart. See [Collaborating](https://codeherder.com/docs/collaborating/#task-dependencies) for how to add or remove a dependency edge. When a parent task and its children are both on screen, the children are drawn inside a labelled frame named after the parent; frames nest, so an initiative’s frame can contain an epic’s frame, which contains a story’s frame. A card can also appear dimmed: that’s a task pulled in only because something else on screen links to it (a parent, or a dependency endpoint) that falls outside your current filters. It’s still a real task, and clicking it works the same as any other card. Click any card to open that task’s detail page. The diagram scrolls inside its own frame. Pinch on a trackpad, or hold Ctrl and scroll, to zoom in or out; plain scrolling pans around the diagram instead. There are no separate zoom buttons. Some referenced tasks can’t always be drawn — deleted, outside this workspace, or beyond a fixed per-page lookup limit — and when that happens a caption underneath the diagram tells you how many. With **Who filed** on, that count covers referenced actors too, since a card can now point at a person as well as a task. Like the list, the graph loads tasks in batches, but unlike the list it doesn’t load more automatically as you scroll. Click **Load more** to bring the next batch, and its dependency edges, into the diagram. --- For how tasks move through their pipelines, see [How work flows](https://codeherder.com/docs/how-work-flows/). For agents that pause waiting on a human decision — and what the Dashboard’s **Needs attention** tile and section are telling you — see [When an agent needs your input](https://codeherder.com/docs/agent-input/). For watching tasks and DM notifications, see [Watching tasks and notifications](https://codeherder.com/docs/watching/). For commenting on tasks, blockers, and dependencies, see [Collaborating](https://codeherder.com/docs/collaborating/). For cost details on specific tasks, see [Understanding costs](https://codeherder.com/docs/costs/).