Text status labels for sessions instead of colored dots (or as an option)

[mazanur]

Right now the agent status in the sidebar is shown as a colored dot (orange / red / green, sometimes blinking). The problem: the colors aren't labeled anywhere, so their meaning isn't obvious — you have to memorize which is which, and a new user simply can't tell what the indicators mean.

Proposal: add an option to show the status as a text label next to the session name, e.g.:

• splitty [working] — active
• customer growth [waiting] — blocked
• attune [done] — completed

Ideally as a setting toggle (dots / text / dots + text) so everyone can pick what suits them. At a minimum, a tooltip or a small legend explaining the colors would already help a lot.

[umputun]

added tooltips in #283. Hovering a visible agent-status indicator now shows Agent status: Active, Blocked, or Completed.

I don't plan to add persistent text labels or another dots/text/both setting. There are only three statuses, the indicators already use distinct symbols, and their colors are configurable. The tooltip covers discoverability without making the sidebar wider or adding another setting.

[mazanur]

Thanks for the tooltips — that helps.

One data point on "the indicators already use distinct symbols": I've been using agterm daily and I genuinely could not tell them apart. I read them as plain colored dots, and I only learned they were an ellipsis, an exclamation mark, and a check after reading the source. Before that I had also mapped the colors wrong in my head and was ignoring the amber blocked glyph as "it's busy, leave it alone" — which is exactly the state that wanted me.

The code points at why. In SidebarRowViews.swift all three are .circle.fill "for a consistent silhouette", drawn at a fixed glyphWidth: CGFloat = 16. So the distinguishing mark is a small knockout inside an identical filled circle, and it doesn't scale with the sidebar font size setting. The shared silhouette is deliberate, and it works — the three really do look like one shape in three colors.

That's the part a hover tooltip doesn't reach: the sidebar is scanned peripherally. The whole value is noticing that some session needs you without aiming at it first. If they have to be hovered one by one to be told apart, that's lost.

I'm not asking for the text labels again — the width objection is fair. Two cheaper options that keep the current layout:

1. Make the SF Symbol name configurable per status, next to the existing color settings. Same 16pt slot, no new width, no new UI concept — just three more fields where three already exist.
2. Or drop .fill (or use a different base shape) for at least one status, so blocked differs by outline and not only by hue. exclamationmark.triangle.fill for blocked reads instantly at a glance and costs no extra width.

Either would also help the color-blind case, where hue is the only channel currently carrying the meaning.

[umputun]

there are three states and three user-configurable colors. Set blocked to whatever color reads as an immediate warning to you, completed to whatever reads as done, and keep active close to the theme if you only want a quiet "something is cooking" signal. The defaults follow exactly that model for the default theme: muted active, orange blocked, green completed.

I'm not adding configurable symbols or changing the fixed symbols for everyone. The tooltip in #283 was a cheap consistency fix because a visible indicator should explain itself on hover, not a reason to add another display mode. Three configurable colors are enough here.

[umputun]

changed my mind on this. Shapes are configurable now, merged in #292.

two things moved me. First, to my surprise I got the same ask from another user independently, which makes it a pattern rather than one person's preference. Second, your color-blind point is the one I under-weighted. Platform guidance is explicit that color should not be the only thing separating two states, and macOS ships a "Differentiate without color" toggle in Accessibility ▸ Display precisely because hue carries nothing for some people. My "three configurable colors are enough" was answered from the position of someone who can see all three.

what shipped is close to your option 1, with one change. Rather than a free-form SF Symbol name per status, it is a fixed set of six: circle, square, triangle, diamond, capsule, star. I rendered a lot of candidates at the real 13pt in the 16pt slot before settling on six. hexagon, octagon, pentagon and seal are indistinguishable from circle at that size, app duplicates square, rhombus duplicates diamond. A picker entry that does not actually differentiate is worse than no entry, because you believe you have separated two states and you have not.

Settings ▸ Agent Status now has a "Colors and Shapes" section, one row per state with its color well and its shape picker side by side. There is also a per-call override for scripts:

agtermctl session status blocked --shape triangle

that one rides the status and reverts on the next set without it, so an agent can mark one session for the duration of a run. It reads back on tree as statusShape.

one change you will spot right away: the old marked circles are gone. Your reading of SidebarRowViews.swift was right, the mark was a knockout inside an identical filled circle at a fixed 16pt. Where those marks did read was the larger glyph in the attention palette and the popover, not the sidebar, and the sidebar is the primary place, the one you scan all day. A mark that only resolves in the secondary surface is not doing the job, so all three states now default to a plain filled circle everywhere.

the default stays color-only on purpose. For the large majority of users three distinct colors do the job, and I am not changing what everyone sees to serve a small minority. Shapes are there for the people color does not work for, and they cost nothing if you never open the picker.

all of this is in master only for now, it will come with the next release: #292

thx for pushing on this one, and for reading the source instead of taking my word for it. The 16pt detail is what actually changed my mind.