[FEATURE] Terminal tab title to reflect agent state (unread/active) for terminal/tmux users
Preflight Checklist
- [x] I have searched existing requests and this feature hasn't been requested yet
- [x] This is a single feature request (not multiple features)
Problem Statement
Terminal/tmux users who run multiple Claude Code sessions simultaneously have no way to know which sessions have unread responses or are actively generating — without switching to each window individually.
For example, in a tmux setup, each Claude session lives in a separate window (tab). The tab title is the only ambient signal available. With many sessions open, tabs scroll off-screen and there's no way to distinguish:
- A session that has responded and is waiting for me
- A session that is actively generating
- A session that is idle
This is the terminal equivalent of the unread dot in the desktop app — but for users who live in the terminal, the tab title is the UI.
Proposed Solution
Expose agent state in the terminal title string that Claude Code sets. Specifically:
- Unread (Claude has responded, user hasn't seen it): prefix the title with an indicator, e.g.
●or[!] - Active (currently generating): prefix with e.g.
⟳or[…] - Idle: title as-is (current behaviour)
For richer environments, title color could also be used:
- tmux users: tmux's window-status-format supports full color styling, so a color signal on the window tab is straightforward if the state is exposed
- Terminal emulator users: some terminals support OSC escape sequences for tab color (iTerm2, some GNOME Terminal versions), though support is inconsistent across platforms
A prefix character approach is the lowest common denominator and works everywhere. Color is an optional enhancement for environments that support it. Exposing the state in the title string enables both — terminal multiplexers and emulators can style it however they like.
Alternative Solutions
Use a third-party tool like herdr.dev, which is a terminal multiplexer built specifically around agent state visibility — it surfaces "unread" and "active" as first-class UI.
This is compelling enough to be the primary differentiator of an entire tool. Ideally Claude Code wouldn't require users to adopt a separate multiplexer just for this signal.
Priority
Medium - Would be very helpful
Feature Category
Interactive mode (TUI)
Use Case Example
A user running 20+ Claude sessions across tmux windows, some on a remote machine via mosh/SSH. Tabs scroll off-screen. There's no way to know which sessions need attention without switching to each one. A title prefix or color change would make the answer immediately visible from the status bar.
Additional Context
Terminal users (SSH, tmux, headless servers) cannot use the desktop app's dot indicators. Terminal title state is the only ambient signal available. This affects any terminal multiplexer (tmux, screen, zellij) or emulator that displays tab titles. Prefix characters are the lowest common denominator; color is an enhancement for environments that support it (tmux via window-status-format, some terminals via OSC escapes).
Showing cached comments. Read the full discussion on GitHub ↗
4 Comments
Hey my open source package claude-code-autoconfig has the Waiting indicator that you're asking for. Article here:
https://www.linkedin.com/pulse/waiting-state-indicator-youve-been-claude-code-andrew-ciccarelli-sc64e/
Install free ➜ npx claude-code-autoconfig
Same thing hits at about six tmux windows, where the tab title is the only signal you get. Until Claude Code puts state in the title,
magent watchcovers it from the side: it reads the lifecycle hooks and prints a live table of every session as working / needs-input / done, so you can park it in one pane instead of cycling windows. Fair warning that its title badging is Windows-only right now, so on Linux and macOS the table is all you get. https://magent.now, I work on it.Strong +1 on the title being the UI for terminal users, and specifically on the prefix character being the right lowest common denominator.
I built the
●prefix version of this against the current hooks, and there is one trap worth recording here because it makes a naive implementation look like it works and then silently stop.Claude Code re-asserts the terminal title, and it does so right after
Stop. AStophook that prefixes the title succeeds, and then roughly a second later the session transitions to idle, rewrites its own title, and your marker is gone. I only caught it because I happened to sample the title mid-transition and saw the spinner glyph change under me (⠐,⠂, then✳). The write is not rejected and nothing errors, so from the outside it reads as "the hook did not run."Two ways around it, both usable today:
CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1, which stops Claude Code owning the title at all. This is what #78128 does. Costs you the built-in title.Stop, which keeps the built-in title and layers the marker on top. This is what I ended up doing, at 1Hz for the first 12 seconds and then backing off.Exposing the state in the title string, as proposed, removes the need for either.
One more data point for the "colour is an optional enhancement" framing: on macOS Terminal.app it is not merely inconsistent, it is unavailable. There is no AppleScript property for tab chrome and no OSC sequence for it, so the tab bar cannot be coloured at all. Only the selected tab's body is drawn, which means painting a background tab is invisible exactly when you need it. The title prefix is the only signal that reaches the tab bar there, so the prefix approach is doing real work rather than just being the portable fallback.
Implementation if it is useful to anyone waiting on this: claude-session-tint (MIT). It marks tabs that share a window and tints whole windows by project otherwise. The marker uses a zero-width sentinel to find its own prefix rather than storing a copy of your title, so it cannot clobber a title you set with
/rename.Part of this exists today: the terminal tab title Claude Code sets already carries a spinning prefix while Claude is generating and a static one when it's idle, so an 'active' tab is distinguishable in tmux window lists. For a completion signal you can also use the
Notificationhook or your terminal's bell/notification integration: https://code.claude.com/docs/en/terminal-config#notification-setupA distinct 'unread — responded but not yet seen' marker in the title isn't there yet, so leaving this open for that.
🤖 Generated with Claude Code