CodeHerderSearch⌘KRequest access →

Reading the task flow report

See where a task's elapsed time goes between arrival and completion, and why ready work isn't running.

Understanding costs answers “what did this cost?” Observability answers “where did the time go inside a session?” Task flow answers a third question: where does a task’s elapsed time go between arrival and completion, and why isn’t ready work running?

Where to find it

Open Work → Reports, then the Task flow card under “Time and flow”. You can also run the commands in From the command line. They print the same figures.

A window picker at the top of the page sets the period: Today, Yesterday, Last 7 days or Last 30 days. The default is Last 7 days. If the window holds no data, the page offers a Show last 30 days button.

A task’s own page also has a Lifecycle flow panel. See One task’s own flow.

Like the Observability report, task flow covers a workspace or a group. A group’s report covers every workspace nested beneath it.

The summary

The Summary panel shows five figures for the window. ch observability flow summary prints the same figures.

  • Arrivals — how many tasks were created in the window.
  • Completions — how many tasks finished in the window.
  • Work in progress — how many tasks are not finished. It asks whether a task is open now, not whether it was open when the window closed.
  • Completion latency p50 — how long a task that finished in the window took from arrival to finishing. The p95 sits under it.
  • Queue age p50 — how long the waiting work has been waiting. The p95 and the number of queued tasks sit under it. It is a snapshot at the end of the window. Only tasks queued at that instant count. Work that already started counts for nothing. Read a rising p95 as “the backlog is ageing”, not “tasks took longer to start”.

The three charts

Below the summary, three charts read the same per-bucket data:

  • Cumulative flow — measured wait-state occupancy per time bucket, stacked. Select a band to open the task cohort behind it.
  • Arrivals and completions — how much work entered and left the system in each time bucket.
  • Queue age — how long the work waiting at each time bucket had already waited.

Select a band on any of the three charts to open a Selected task cohort table below them. It lists the tasks behind that bucket. If you picked one band of a stacked bar, it lists only the tasks in that wait state. The columns are Task, Type, Priority, Current stage, State in bucket, Current state and Created.

State in bucket is the state the task spent most of that bucket in, or the band you picked. Current stage and Current state are live: they show where the task is now. Clear the selection to close the cohort and go back to the whole window.

Wait states

Every instant of a task’s life, from arrival to completion (or to now, if it’s still open), falls into one of six wait states:

  • Blocked — someone filed a blocker on the task, and it does not come from an unfinished upstream task.
  • Blocked on dependency — CodeHerder filed a blocker for you because an upstream task is not finished.
  • Executing — a session is actively working the task.
  • Queued — the task is waiting for an agent to pick it up, at a stage that runs one.
  • Awaiting handoff — the task is at a stage that runs no agent. That covers To do and Done, human stages, and stages that wait on an outside check.
  • Unknown — no record covers that stretch of time, so the report does not guess.

The Wait-state occupancy table has the columns State, Duration and What it means. It gives one row per state, with the total time this window’s tasks spent in it. Duration is a time, not a task count. On the command line, the same six states have these keys: blocked_explicit, blocked_dependency, executing, queued, awaiting_handoff, and unknown.

Why work didn’t run

The Why work didn’t run table lists the placement and capacity refusals CodeHerder recorded in the window. Its columns are Reason, Count and What it means. Count is how many times CodeHerder recorded that reason. These events age out over time. An empty table does not prove that nothing was refused. It only means nothing survives in this window.

See The Placement report for the full picture of device eligibility behind a single task, and Why isn’t my task moving? if you’re trying to unstick one task right now — task flow is the aggregate, workspace-wide view of the same refusals.

One task’s own flow

A task’s own page has a Lifecycle flow panel. It shows a lane for each stage attempt, with that attempt’s time split across wait states. From the command line:

ch task flow <taskId>

This prints the same lanes as a table. Each row is one slice of a stage attempt, with the columns STAGE, ATTEMPT, STATE, DURATION, SESSIONS and START. Leave out <taskId> and it uses the current task (CH_TASK_ID).

From the command line

ch observability flow has three subcommands. Each takes an optional workspace or group first, which defaults to your current workspace. Each takes the same window flags as ch costs.

ch observability flow summary

Prints the summary figures, the wait-state occupancy table and the refusal-reasons table. The default window is the last 7 days. Plain ch observability flow does the same.

ch observability flow buckets --window month

Prints one row per time bucket. The columns are BUCKET, BUCKET END, ARRIVALS, COMPLETIONS, WIP, QUEUE P50, QUEUE P95 and INCOMPLETE.

ch observability flow tasks --state queued

Prints the cohort task list. The columns are TASK, TITLE, TYPE, PRIORITY, STAGE NOW, STATE IN BUCKET and STATE NOW. Narrow it with --state (one of the six wait-state keys above) or --bucket. For --bucket, copy a bucket start from the BUCKET column of flow buckets --json. Without --bucket, STATE IN BUCKET is the task’s state as of the end of the window. It pages like any other ch list, with --limit and --cursor.

ch observability flow my-group
ch observability flow buckets --since 30d

See Understanding costs for how --window and --since work.

Who can see it

Any workspace member can read the task flow report, in the app or from the CLI — there’s no separate permission to grant.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close