Tab strip redesign: seven directions, which ones would you use?

[Ark0N]

The tab strip is the part of Codeman I look at most and like least. With 18 sessions open it wraps into three rows, every tab has a different width, and the only way to tell which case a tab belongs to is the suffix in its name. It reads as scattered.

So I mocked up seven directions. They are HTML mockups built on the real stylesheet (same font, radii, colours, badge and dot sizes), not builds, and the session and case names are made up. Two states are invented so all three colours show up: w4-webshop is red (a question pending) and w75-api-gateway is yellow (waiting for input).

Rate them however you like: 1 to 5, keep or kill, or "A but with C's ordering". Hybrids are welcome, that is the whole point.

Today

18 tabs, three rows, nothing for the eye to line up on.

A · Clusters (group by case)

Tabs grouped by the case they run in. The suffix in w1-webshop is redundant inside its group, so the tabs shrink to w1, w3, w4, and 18 tabs read as 7 things. The group colour is the session palette that already exists.

Tradeoff: one-off sessions get nothing out of it, and a case with 8 workers is still a long row. Groups also change size as sessions come and go.

B · Ledger (aligned columns)

The same flat list, laid on a column grid so the rows line up. Status is a 3px bar on the left instead of a dot, mono type, and a mode tag only where the mode is not Claude. The smallest change of the set.

Tradeoff: a long name widens its whole column, and it is still a list of 18 with no grouping.

C · Triage (rows are states)

The strip answers "who wants me?" the way the home screens already do: needs-you first, then working, then idle dimmed. It would reuse the ordering the phone overview and the desktop home rail use today.

Tradeoff: tabs move between rows on their own, so muscle memory for position is gone. The Alt+N badges stay where they are.

D · Focus strip (one row, ever)

The active tab plus the four most recent stay visible. Everything else sits behind a "+13 more" button that opens a grouped, searchable list with state and duration per row. The strip never grows past one row however many sessions you have.

Tradeoff: a session you are not looking at is one click further away, and the red dot on the +N button has to carry the alerts for everything hidden.

E · Mission control (sessions leave the header)

A left column with case groups, per-session state duration, and the last line of output for each session, so you can see what every worker is doing without switching. The header keeps only the counts and the stats.

Tradeoff: costs about 280px of terminal width. It overlaps the sidebar layout that already exists (App Settings, Appearance, Tabs), so it would replace that rather than sit next to it.

F · Segments (fused pills)

Each case becomes one segmented control and its workers are the segments. The densest option: 18 sessions in about a row and a half, with the case named once.

Tradeoff: names shrink to ids, the gear and close buttons only fit on the active segment, and a very long case name pushes its segments off the row.

G · The right side of the header

Independent of the tab choice, it combines with any of the above. Compact: one system pill with tiny sparklines plus two plan-usage rings, which hands the tabs about 120px back. Tiles: label over value with a bar underneath, no icons.

What I want from you

• Which two or three would you actually use day to day?
• Anything here that would get in your way?
• If you run Codeman with many sessions, how many tabs do you usually have open? That number changes which of these make sense at all.

My guess is that whatever wins lands as a layout option next to the existing sidebar and rail, so nobody's current strip changes under them.

[irisitymichaelgrundberg]

First of all, I agree that the header is the weakest part of an otherwise great tool. Thank you for asking for our opinion about this!

To be honest, I currently mostly work in single-session browser tabs, which are opened by my own GTD-style board (which combines information from Codeman with information from other sources such as our ticketing system). But from time to time I have the Codeman board open and work from there. I've also only used Codeman for a couple of weeks. This makes my vote perhaps not as valuable as others, but take it for what you think it's worth.

Since I tend to create and then destroy sessions when working, the "muscle memory" argument is not important to me. It's rather more important that I quickly can see what status the agents are in and especially which are waiting for me, so I can keep them going.

As a sidenote, I think this is a bit tricky in today's Codeman board. Some tabs are yellow, others are yellow but still have a green spinner in them, other have a green spinner but switching to them shows "pane is dead". Not sure what is going on. Perhaps this unclear status view is what makes me using my own GTD board to show Codeman status instead of working directly in the Codeman board.

So I guess option C would be my preference, given the way I'm working currently.

On the other hand, I see value in option D as well. I tend to switch between just a few sessions in the short run (my "current working set"). Keeping just those at the top provide good focus. When resuming other work, the expanded list provides nice grouping and status.

[Ark0N]

Thanks for the detailed vote, and for the sidenote, which turned out to be the most useful part of it.

Two of the three status symptoms you describe are real bugs, and one of them is not your setup. Taking those first, then C and D.

Yellow ring. Codeman got an idle-prompt hook from that session, so the agent is sitting at its composer waiting on you. A red ring means a permission or question dialog is blocking it. A yellow one is cleared when you open the session, when the turn's stop hook arrives, or when the server sees the session start working again (resolveForSession(..., ['idle']) in src/web/session-listener-wiring.ts).

Yellow with a green spinner. Two independent signals with no single answer between them. The alert repaints the status dot yellow but not the ring spinning around it, which keeps the green of "a turn is running" (.session-tab .tab-status.busy::after in src/web/public/styles.css, against the .tab-alert-idle .tab-status rules a few lines below it). Since a yellow alert is supposed to clear the moment the session goes back to working, a tab showing both means one of the two signals is stale and the strip cannot say which. That needs one answer whatever the tab strip ends up looking like. If you catch it again: does clicking the tab clear the yellow, and does the spinner stop?

Green spinner, then "Pane is dead" when you switch. This one is a genuine gap, not your configuration. Codeman runs each session in a tmux pane with remain-on-exit on, so when the agent inside exits, the pane stays with its last frame on screen and the process Codeman tracks (the tmux attach client) keeps running. Nothing exits, so the session's status never changes. Work detection then makes it worse: it asks the pane what it is rendering (_probePaneWorking() in src/session.ts), and a pane frozen mid-turn still shows the working line forever, so the session stays busy and spins on a corpse. The wait endpoints do probe for this (workerIsDead() in src/web/routes/session-routes.ts), and codeman tui refuses to attach to a dead pane and offers to resume the conversation instead, but the browser dashboard has no equivalent: the periodic reconcile asks tmux only for session name and pane pid (PANE_LIST_FORMAT, src/tmux-manager.ts:223), and a dead pane still lists. You have since written it up properly as #446, measurements included, so that is where it lives now. All seven mockups draw a status model and not one of them has a state for "this worker exited", so thank you for finding the hole before I built on top of it: whichever direction wins has to draw that state.

On C. The ordering C is about already ships, on the vertical rail rather than in the header strip. App Settings, Appearance, Tabs, set Tab Orientation to "Vertical (side rail)". The other two defaults are already what you want: Vertical Rail Order is "By activity" (since 1.27.0) and Vertical Rail Rows is "Detailed". Rows then come out in the home screens' order, blocked on you first with the longest-blocked on top, then whatever has been running longest, then the most recently quiet, and each row carries a status pill and how long it has been in that state ("waiting 8m"). It is not C: there are no state headings and it is a side rail, not the header. But it answers the same question the same way, so try it for a day and tell me whether the ordering alone fixes it, or whether the state headings are what make it readable. That difference is most of what separates C from a setting that already exists.

Worth turning on alongside it: the Approvals Inbox (App Settings, Header & Panels, Cross-session features), which is off by default. It puts a bell with a count in the header and a drawer listing every session waiting on a human, and you answer the prompt from the drawer without switching to the session at all. If "keep them going" is the job, that may be worth more to you than any of the seven.

On D. Noted, and the working-set argument is the best case anyone has made for it so far. The closest thing today is Ctrl/Cmd/Alt+K, which searches your open sessions and can open the Session Manager, but it has no case grouping and no duration per row; a status word is all each row carries.

One aside on your own board. You do not have to pick one or the other. GET /api/v1/approvals is the same queue the inbox renders, documented in docs/api-reference.md under Approvals Inbox, so your board can show the waiting-for-you set directly, and docs/extending-codeman.md has a worked SSE example for that exact notification. /session/<id> is the single-session URL your board is presumably already linking to (the pop-out button on a tab produces it). And a dashboard URL can be a tab inside Codeman (docs/web-tabs.md; 1.29.0 made single-page dashboards behave in there), so your board could sit beside the sessions rather than instead of them.

Two weeks of use is not a weak vote here. It is the kind of vote that notices the status colours do not add up.

[irisitymichaelgrundberg]

Thanks for explaining! The tabs are kind of overwhelming for a newcomer, since they have multiple dynamic indicators, that are neither intuitive (to me) nor explained. Here is the current state of my board:

The yellow rings are clear now that you explained, and are what I should focus on to "keep sessions going". But they also make it difficult to know which is my currently active session. If I look closely, I can see that the text is whiter on that tab than the rest, but I did not notice that until now. Perhaps consider a friendly help text explaining how to interpret the tabs? As well as something that more clearly shows which tab is the currently active one?

Those green blob + spinning green ones are the exited sessions that linger here after I've closed the browser tab they were in. Sounds like you are ok with #446 making its way into Codeman? If you could please answer the questions that I posted in the issue, I will proceed making a PR for it.

The single yellow blob + spinning green in the screenshot turned to green blob + spinning green when I clicked on it. The session had a background agent that it was waiting for.

Thanks for the tips on features I was not aware of - I will turn them on and try them out.

[Ark0N]

Thanks, that screenshot answers more than the words could.

The active tab really does vanish under a yellow ring, and it is not your eyes. The alert is drawn as an overlay on the tab's ::before at inset: -2px with a 2px border (.session-tabs .session-tab.tab-alert-idle::before, src/web/public/styles.css:1782). The active tab's own marking is a 1px accent border plus a tinted background, set with !important (src/web/public/styles.css:14707, and :714 on the OG skin). The ring sits exactly over that border, and its translucent fill paints over the label too, because a positioned pseudo-element paints above in-flow content. What is left of "this one is selected" is the label colour (var(--text) instead of var(--text-dim)) and the Alt+N badge, which turns accent-coloured on the active tab. The badge is only rendered for tabs 1 to 9 (src/web/public/app.js:5246), so from the tenth tab on, the whiter label really is all there is.

The overlay was built that way on purpose, so that a permission prompt still looks blocking while you are looking at it. What it missed is that the active state then has nothing of its own left. The answer is a cue the ring cannot cover, an underline below the tab rather than a border around it, or the label switching weight. That is squarely what this thread is for: whichever direction wins has to draw three things at once, "this one is selected", "this one wants you", and now "this one exited".

There is a legend, and it is not in the app. It is the wiki: https://github.com/Ark0N/Codeman/wiki/The-Dashboard under Session tabs. Green dot alive, pulsing green dot with a ring working, yellow blinking waiting for you, red blinking blocked on a question or a permission prompt. Nothing in the app points at it. The Help panel (Ctrl+? or Alt+?) is keyboard shortcuts only, the status dot has no tooltip and is aria-hidden (src/web/public/app.js:5248), and a tab's tooltip is its working directory. An in-app legend is a fair ask and a small one, and the Help panel is where it would go.

Your yellow-plus-spinner case is explained now, and my guess last time was wrong. Neither mark was stale, both were live. The yellow is armed by Claude's idle-prompt notification and cleared by three things: the turn's stop hook, a working transition, or you opening the tab (markIdleAlertSeen, src/web/public/app.js:881, with the server half in src/web/session-listener-wiring.ts:231). The catch is that the working signal fires on the transition only (_markWorking, src/session.ts:2741), so a session that was already busy when the notification landed keeps the ring and gains the yellow, and nothing takes the yellow down until the turn stops or you look at it. That is exactly what you saw: you clicked, the yellow went, the ring stayed.

The ring does not come from a hook. Work detection reads the rendered pane for the CLI's working line (CLAUDE_WORKING_LINE_PATTERN, src/utils/regex-patterns.ts:79), which matches … (13s and esc to interrupt. So the pair you saw means "the composer reported itself idle" and "the pane is still rendering a working line", which for a session waiting on a background agent are both true at once. What I would like from you, if you catch it again: run tmux -L codeman capture-pane -p -t codeman-<first 8 characters of the session id> | tail -5 while a background agent is running, and paste what it prints. That decides whether the strip can tell "your turn is running" from "a background task is running" at all, and right now I do not think it can.

One thing that already resolves the pair into a single word: the detailed vertical rail. It classifies by hook first and status second (_mobileOverviewState, src/web/public/mobile-overview.js:104), so that session reads waiting 8m with nothing to interpret. The header strip is the one surface that draws the two signals as two separate marks.

On #446: yes. The problem is real, and the write-up with the tmux table is the kind of bug report I wish I got more of. The four questions in it are design calls rather than facts, so I will answer them in the issue itself and keep the decision in one place rather than split across two threads.

Two things worth having in hand before you build part 2, neither of which decides the questions:

• The close path cron uses (cleanupSession, called from src/cron/cron-service.ts:683) recursively removes <workingDir>/.claude-images (src/web/server.ts:1429). Several workers commonly share one case directory, so a sweep that closes exited sessions through that path can delete pasted images belonging to a live sibling. The stopped demotion on the same path is the half you do want, since that is what makes the reboot restore inherit the fix for free.
• The remote side already made this exact choice once, in the other direction: remote panes are created with remain-on-exit failed rather than on (src/tmux-manager.ts:951, with the reasoning in the comment above it), precisely because on left a corpse behind after a clean exit and the next launch reattached to it. Local panes still use on (src/tmux-manager.ts:2046, and again at :2094). That is not a drop-in fix here (a destroyed pane ends the tmux session, and sessionDied currently only logs and broadcasts, src/web/server.ts:417), but it is the nearest precedent and it is worth a paragraph in the issue before we settle question 1.

Part 1 is the piece this thread needs whatever happens to part 2. All seven directions draw a status model, and none of them can draw "this worker exited" until the server reports it.