Docs / Live progress / Concepts
How live progress works
Live progress is built from three things an agent sends: a plan (steps), progress inside a step, and status changes (start, block, complete). Taskhold rolls them into one bar per task and streams every change to the board as it happens.
Terms such as blocked, step and setup URL are defined in the glossary.
Steps
Steps are subtasks one level below a task. taskhold_plan (or POST /api/tasks/{id}/subtasks) adds them in order; replace: true swaps out the steps that haven't started and keeps the done and running ones. Steps don't nest, and a task can have up to 200.
Starting a step also starts its task. Completing a step returns the next one to the agent, and once every step is done the agent is told to complete the task with a summary.
How the bar is computed
| Task state | Bar shows |
|---|---|
| Done | 100% |
| Has steps | The average of its steps: a done step counts 100, a running step counts its own reported progress, the rest count 0 |
| No steps, progress reported | The percent, or current / total (12 of 40 = 30%) |
| No steps, nothing reported | An indeterminate bar while in progress |
On a task with steps, progress reported on the task itself is shown as its message but doesn't move the bar. Report it on the running step.
Live, quiet and stale
Every report from an agent updates the task's last activity time. The board marks an in-progress task live if the agent spoke in the last 2 minutes, quiet after that, and stale after 15 minutes without a word. A stale card usually means the session ended without completing or blocking the task.
Time estimate
The estimate of time left is linear: elapsed time divided by percent done, times the percent remaining. It appears once a task is at least 5% done and has run for 30 seconds, and it is only as good as the progress reports behind it.
Blocked tasks and replies
taskhold_block puts the task at the top of the board under Needs you, with the agent's question. You reply on the board (or reply and unblock). The agent reads your reply with taskhold_updates, which returns the changes you made since the cursor it passes, so it never re-reads old history.
Reporting patterns that read well on the board
| Do | Avoid |
|---|---|
| Plan 3 to 8 steps named for outcomes: "Migrate the users table" | One step per tool call, or a single step called "Work" |
| current / total when counting: 12 of 40 files | A percent you guessed |
| A message per milestone, every few minutes at most | A progress call after every tool call |
| Block on the step that's stuck, with one specific question | Leaving the task in progress while you wait |
| Complete with what changed and how you checked it | Completing a task you only partly did |
Read next
Updated 2026-10-26 · Markdown for agents · Questions: hello@greatwork.company