Workflow progress view: phase dot colours are undocumented, and two runs in identical states render different colours
What happened
The desktop app's workflow progress view renders a coloured dot per agent under each phase. I have observed four distinct renderings: grey (filled), blue (filled), yellow/orange (filled, with the phase label also turning yellow), and hollow/outline.
Two problems, and the second is why I'm filing rather than just asking:
1. The colours are undocumented. I searched docs.claude.com, support.claude.com and anthropic.com and could not find any description of what these colours mean. The only documented color concept I could find is the color: field in a custom subagent's .claude/agents/*.md frontmatter — that is agent identification, not run status, and it is not set on these agents.
2. Two workflows in identical recorded states rendered different colours. Two Workflow runs were executing concurrently. Both were on their final phase with exactly one agent still in flight. One rendered that phase's dot blue; the other rendered it yellow with a yellow phase label. Same state, different colour.
I checked their journal.jsonl files rather than guessing from the UI, and found nothing that distinguishes them:
run A (rendered BLUE): {'started': 18, 'result': 17} 1 agent in flight
run B (rendered YELLOW): {'started': 13, 'result': 12} 1 agent in flightBoth journals contained only started and result events — zero error, retry, skip or empty-result events. So no recorded state differentiates them.
I initially assumed the yellow one was the "focused/expanded" card, since it happened to have a phase expanded at the time. A later screenshot with both cards collapsed still showed one blue and one yellow, which refuted that.
What I expected
Either:
- the colours map to documented, distinct agent/phase states — in which case please document them; or
- identical states render identically — in which case the differing colour is a rendering bug.
Repro
- Invoke
Workflowtwice so both run concurrently, with different agent counts per phase. - Watch the final phase of each while exactly one agent is in flight in both.
- Observe that the two phases can render in different colours despite identical journal state.
(Both of my runs used the same script shape: a fan-out phase, a per-item verification phase, and a single final synthesis agent. They differed in agent count and in whether an initial single-agent phase existed.)
Possibly related
There is precedent for this view diverging from the underlying data — a changelog entry records a fix for "the workflow progress view dropping the earliest agents from the list while the phase counter stayed correct" in SDK and desktop-app sessions. That was a different symptom, but the same view and the same class (render state not matching recorded state).
Why it matters
The progress view is the only live signal for a long-running multi-agent workflow. If a colour indicates something actionable — a stall, a retry, a slow agent — an operator needs to know. If it indicates nothing, it invites exactly the wrong inference. In my case I could only resolve the question by reading journal.jsonl directly, which is not a reasonable expectation for a UI indicator.
Environment
- Claude Code 2.1.220, desktop app
- Windows 11 Pro 26200
- Model: Opus 5
Showing cached comments. Read the full discussion on GitHub ↗
3 Comments
Additional evidence from a later run, which narrows this and adds a second, separable issue.
1. More data on the colour
Two agents running concurrently in the same phase of the same workflow, both healthy and actively making tool calls, both rendered yellow at ~14 minutes elapsed:
Earlier in this same workflow, a single agent in that phase rendered blue early in its life and yellow at ~43 minutes. That is what you would expect if yellow were an elapsed-time warning — but it does not square with two agents going yellow at 14 minutes while a different workflow's agent stayed blue for longer. I can't reconcile the two observations from the outside, which is really the point of the report: there is no documented mapping to check against.
Practical consequence: the colour is not usable as a stall signal. What did work was reading
agent-*.jsonldirectly and comparing tool-call counts and silence duration. A healthy agent showed steady tool calls; the genuinely-degraded one showed ~36 minutes with zero tool calls.2. Separable issue: a stopped agent is never marked finished, and shows as in-flight forever
I stopped a workflow with
TaskStopwhile one agent was mid-run. The stop succeeded and the workflow ended. But no terminal event was ever written for the in-flight agent —journal.jsonlretains itsstartedwith no matchingresult, so any consumer that derives "still running" fromstarted - resultreports it as running indefinitely. Mine still showed it at 72 minutes elapsed / 27 minutes silent, long after the workflow was stopped.This also inflates the in-flight count in the progress view after a stop-and-resume, since the stale agent is indistinguishable from the two genuinely running ones by journal state alone.
Suggested fix: write a terminal event (
stopped/cancelled) for every in-flight agent when a workflow is stopped, sostartedalways has a matching terminal record.Environment
Same as the original report — Claude Code 2.1.220, desktop app, Windows 11, Opus 5.
Still relevant. Four distinct dot renderings, no published description of what any of them mean, and two runs in the same state rendering differently.
The second half is the reason this is a bug report rather than a documentation request. If the colours were merely undocumented, a user could learn them by observation. Because identical states render differently, observation does not converge either, so the view cannot be read at all.
Documenting the vocabulary and making it deterministic would both be needed.
Still open. The first half of this report is a documentation gap and the second half is why I filed it, so I would not want the two collapsed.
Two
Workflowruns were in identical recorded states, both on their final phase with exactly one agent in flight, and they rendered different colours. One phase dot blue, the other yellow with a yellow phase label. I read theirjournal.jsonlfiles rather than inferring from the UI, and both contained onlystartedandresultevents, with no error, retry, skip or empty-result events. So nothing in the recorded state distinguishes them.That means the colour is not a readable signal about run health today, even for someone who knows what the colours are meant to mean. Documenting the vocabulary would help, but it would not resolve two identical states rendering differently.