Title a session by the group it belongs to

Four panes named claude-code-N tell you nothing about which fleet you are
looking at, so the surfaces that show an agent ON ITS OWN now say the group
first: `[Agent-manager] claude-code-7`. The sidebar and the Overview already
draw the group as a frame around its agents and are left alone — saying it
twice is noise.

Changed: the terminal and remote pane headers, the phone's title bar, and the
browser tab (which never named a session before and now does, dropping the
app's own name rather than pushing the agent's out — the favicon already says
which app this is). Left alone: the files pane (titled by the folder it is
showing) and the trace pane (titled by the transcript's own recorded title).

An agent with no group shows a bare name. Ungrouped is an absence here, not a
word — the tree simply has no group listing the session — so there is no
`[None] foo` to guard against.

The prefix is context and the name is what you are looking for, so the group is
what gives way when there isn't room: in a pane it is weighted to shrink
hundreds of times faster than the name (and drops out below 260px, where a
clipped prefix would say nothing anyway), and in the tab `sessionTitle` elides
then drops it, never cutting into the name. The full title stays in the
header's tooltip.

The group name rides the existing tree poll, so renaming a group or moving an
agent between groups retitles its pane and the tab without a reload.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

web/package.json

@@ -13,7 +13,7 @@
     "dev": "vite",
     "build": "tsc --noEmit && vite build",
     "typecheck": "tsc --noEmit",
-    "test": "node test/exchanges.test.mjs",
+    "test": "node test/exchanges.test.mjs && node test/sessionTitle.test.mjs",
     "preview": "vite preview"
   },
   "dependencies": {

web/src/App.tsx

@@ -16,6 +16,7 @@ import Welcome from './components/Welcome';
 import * as api from './api';
 import type { Cli, GridSpec, MoveTarget, OverviewFilter, Session, Tree } from './types';
 import { onPaneMode, readPaneMode, writePaneMode } from './lib/paneMode';
+import { groupLabel, sessionTitle } from './lib/sessionTitle';
 import { isPassive, isRemote } from './types';
 import { GridGlyph, ListGlyph } from './components/icons';
 
@@ -407,6 +408,15 @@ export default function App() {
   const cliMap = useMemo(() => Object.fromEntries(clis.map((c) => [c.id, c])), [clis]);
   const sessById = useMemo(() => Object.fromEntries(tree.sessions.map((s) => [s.id, s])), [tree.sessions]);
   const groupById = useMemo(() => Object.fromEntries(tree.groups.map((g) => [g.id, g])), [tree.groups]);
+  // Which group an agent belongs to, by name — the one fact every place that
+  // titles a single agent needs. It rides the tree poll, so renaming a group or
+  // dragging an agent into another one retitles its pane and the browser tab on
+  // the next refresh, with no reload and nothing to keep in sync by hand.
+  const groupNameOf = useMemo(() => {
+    const m: Record<string, string> = {};
+    for (const g of tree.groups) for (const id of g.sessionIds) m[id] = g.name;
+    return m;
+  }, [tree.groups]);
 
   // Keep a valid selection ('overview' is always valid).
   useEffect(() => {
@@ -437,6 +447,21 @@ export default function App() {
   const visibleIds = visibleSessions.map((s) => s.id).join(',');
   const showZoom = visibleSessions.length > 0;
 
+  // The browser tab names the agent you are actually in — `[Group] name`, the
+  // same reading as its pane header. A tab strip (or a phone's app switcher) is
+  // exactly where several Spaces and several `claude-code-N` look alike, so the
+  // group earns its place there; the app's own name is what gives way, since
+  // the favicon already says which app this is. Under a tiled group the title
+  // follows the focused pane, because that is the one taking your keystrokes.
+  const onStage = !isMobile || mobileStage;
+  const titleSession = onStage
+    ? visibleSessions.find((s) => s.id === focusedId) ?? visibleSessions[0] ?? null
+    : null;
+  const tabTitle = titleSession
+    ? sessionTitle(titleSession.name, groupNameOf[titleSession.id])
+    : 'Agent Manager';
+  useEffect(() => { document.title = tabTitle; }, [tabTitle]);
+
   // Keep a small working set of terminal panes alive across navigation. The
   // backend session already survives a viewer disconnect; retaining xterm and
   // its socket as well makes switching back genuinely instant and preserves the
@@ -739,6 +764,7 @@ export default function App() {
                 theme={theme}
                 zoom={zoom}
                 mode={paneMode}
+                groupName={groupNameOf[s.id]}
                 focused={shown && sessions.length > 1 && s.id === focusedId}
                 visible={shown && deckVisible}
                 active={shown && deckVisible && s.id === focusedId}
@@ -773,6 +799,7 @@ export default function App() {
               <RemotePane
                 session={s}
                 zoom={zoom}
+                groupName={groupNameOf[s.id]}
                 focused={visibleSessions.length > 1 && s.id === focusedId}
                 dragId={canDrag ? `p:${s.id}` : undefined}
                 onDragActive={setPaneDrag}
@@ -904,7 +931,19 @@ export default function App() {
                 ))}
               </div>
             ) : (
-              <span className="mtitle mono">{activeRef === 'overview' ? 'Overview' : activeSingle?.name}</span>
+              <span className="mtitle mono" title={activeSingle ? sessionTitle(activeSingle.name, groupNameOf[activeSingle.id]) : undefined}>
+                {activeRef === 'overview' ? 'Overview' : (
+                  <>
+                    {/* Same rule as the pane header: the group is a prefix that
+                        elides before the agent's name does. A loose agent — the
+                        usual case for this bar — shows a bare name. */}
+                    {activeSingle && groupLabel(groupNameOf[activeSingle.id]) && (
+                      <span className="ph-group">[{groupNameOf[activeSingle.id]}]</span>
+                    )}
+                    <span className="ph-name">{activeSingle?.name}</span>
+                  </>
+                )}
+              </span>
             )}
           </div>
         )}

web/src/components/RemotePane.tsx

@@ -4,6 +4,7 @@ import { REMOTE_STATE_LABEL } from '../types';
 import * as api from '../api';
 import Logo from './Logo';
 import { renderMarkdown } from '../lib/markdown';
+import { groupLabel, sessionTitle } from '../lib/sessionTitle';
 import { CloseGlyph, StopGlyph, PlayGlyph, ShareGlyph, AckGlyph } from './icons';
 
 // Looks like the terminal, is not one: no PTY, no xterm.js, no WebSocket. The
@@ -24,9 +25,10 @@ const fmtAgo = (ts?: number | null) => {
 };
 
 export default function RemotePane({
-  session, focused, zoom = 100, dragId, onDragActive, onFocus, onClose, onRename,
+  session, focused, zoom = 100, dragId, groupName, onDragActive, onFocus, onClose, onRename,
 }: {
   session: Session;
+  groupName?: string | null; // the group this pane belongs to, if any
   focused?: boolean;
   zoom?: number;
   dragId?: string;
@@ -36,6 +38,7 @@ export default function RemotePane({
   onRename?: (name: string) => void;
 }) {
   const name = session.remote?.name || '';
+  const group = groupLabel(groupName);
   const [info, setInfo] = useState<RemoteInfo | null>(null);
   const [messages, setMessages] = useState<RemoteMessage[]>([]);
   const [draft, setDraft] = useState('');
@@ -218,9 +221,12 @@ export default function RemotePane({
         ) : (
           <span
             className="ph-title"
-            title={onRename ? 'double-click to rename' : undefined}
+            title={`${sessionTitle(session.name, groupName)}${onRename ? ' · double-click to rename' : ''}`}
             onDoubleClick={onRename ? () => { setTitleDraft(session.name); setEditing(true); } : undefined}
-          >{session.name}</span>
+          >
+            {group && <span className="ph-group">[{group}]</span>}
+            <span className="ph-name">{session.name}</span>
+          </span>
         )}
         <div className="ph-right">
           <div className="rp-pop-wrap" ref={popRef}>

web/src/components/TerminalPane.tsx

@@ -10,6 +10,7 @@ import Logo from './Logo';
 import ConversationView from './conversation/ConversationView';
 import { isPassive } from '../types';
 import type { PaneMode } from '../lib/paneMode';
+import { groupLabel, sessionTitle } from '../lib/sessionTitle';
 import { CloseGlyph, RefreshGlyph } from './icons';
 
 const THEMES: Record<'light' | 'dark', ITheme> = {
@@ -180,11 +181,12 @@ if (typeof window !== 'undefined') {
 }
 
 export default function TerminalPane({
-  session, cli, theme, focused, visible, active, zoom = 100, mode = 'terminal', dragId, isMobile, onDragActive, onFocus, onRename, onClose,
+  session, cli, theme, focused, visible, active, zoom = 100, mode = 'terminal', dragId, isMobile, groupName, onDragActive, onFocus, onRename, onClose,
 }: {
   session: Session;
   cli?: Cli;
   theme: 'light' | 'dark';
+  groupName?: string | null; // the group this pane belongs to, if any
   focused?: boolean;
   visible?: boolean;
   active?: boolean;
@@ -810,6 +812,7 @@ export default function TerminalPane({
   // Focused panes tint toward THEIR agent's brand color, not the app accent.
   const tint = cli?.color;
   const pathLabel = workspaceLabel(session.path);
+  const group = groupLabel(groupName);
   return (
     <div
       className={`slot${focused ? ' focused' : ''}`}
@@ -840,7 +843,17 @@ export default function TerminalPane({
             onKeyDown={(e) => { if (e.key === 'Enter') commitName(); if (e.key === 'Escape') setEditing(false); }}
           />
         ) : (
-          <span className="ph-title" title={`${pathLabel} · double-click to rename`} onDoubleClick={() => { setDraft(session.name); setEditing(true); }}>{session.name}</span>
+          // Two spans, not one string: the group is a prefix that must give way
+          // before the agent's own name does (see .ph-group in styles.css), and
+          // the rename below still edits the name alone.
+          <span
+            className="ph-title"
+            title={`${sessionTitle(session.name, groupName)} · ${pathLabel} · double-click to rename`}
+            onDoubleClick={() => { setDraft(session.name); setEditing(true); }}
+          >
+            {group && <span className="ph-group">[{group}]</span>}
+            <span className="ph-name">{session.name}</span>
+          </span>
         )}
         <div className="ph-right">
           <span className="ph-path" title={pathLabel}>{pathLabel}</span>

web/src/lib/sessionTitle.ts

@@ -0,0 +1,49 @@
+// What an agent is called when it is shown on its own: `[Group] name`.
+//
+// The sidebar and the Overview already draw the group as a frame around its
+// agents, so they say it once and leave the rows bare. The surfaces that show a
+// single agent with no such frame — a pane header in a tiled group, the phone's
+// title bar, the browser tab — have to spell the group out, or four panes named
+// `claude-code-1` are indistinguishable.
+//
+// One rule everywhere: the group is context and the name is the thing you are
+// looking for, so when there isn't room the group gives way first. A session
+// with no group is titled by its bare name — never `[None] foo` or `[] foo`.
+
+/**
+ * The group's display name, or null when the session sits loose in the tree.
+ *
+ * Ungrouped is an absence here, not a word: the tree simply has no group that
+ * lists the session, and `/api/agents` serialises that as `group: null`. So the
+ * empty cases all collapse to the same bare name — there is no `[None] foo`.
+ */
+export function groupLabel(name?: string | null): string | null {
+  const trimmed = (name ?? '').trim();
+  return trimmed ? trimmed : null;
+}
+
+// About what a browser shows of a tab title before it stops being readable.
+// Past this the prefix would be all you can see, which is the failure this
+// whole module exists to avoid.
+export const TAB_BUDGET = 42;
+
+// Shorter than "[abc…]" the prefix identifies nothing, so drop it instead.
+const MIN_GROUP = 4;
+
+/**
+ * `[Group] name` as a single string, for the places that can only take one: the
+ * browser tab and `title=` tooltips.
+ *
+ * Fits `budget` characters by shortening the group, then by dropping it. The
+ * name comes back whole even when it exceeds the budget by itself — cutting
+ * into the name is the one thing this must never do.
+ */
+export function sessionTitle(name: string, group?: string | null, budget = TAB_BUDGET): string {
+  const g = groupLabel(group);
+  if (!g) return name;
+  const full = `[${g}] ${name}`;
+  if (full.length <= budget) return full;
+  const room = budget - name.length - 3; // the brackets and the separating space
+  if (room < MIN_GROUP) return name;
+  return `[${g.slice(0, room - 1)}…] ${name}`;
+}

web/src/styles.css

@@ -562,7 +562,14 @@ body {
 
 .pane-head { container-type: inline-size; display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, auto) minmax(0, 1fr); align-items: center; gap: 9px; padding: 7px 11px; background: var(--panel); border-bottom: 1px solid var(--border); font-size: 12px; flex: none; }
 .pane-head .ph-left { grid-column: 1; justify-self: start; display: inline-flex; align-items: center; gap: 7px; }
-.pane-head .ph-title { grid-column: 2; min-width: 0; max-width: 100%; text-align: center; font-family: var(--font-mono); font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; cursor: text; }
+.pane-head .ph-title { grid-column: 2; min-width: 0; max-width: 100%; display: inline-flex; align-items: baseline; justify-content: center; gap: 5px; text-align: center; font-family: var(--font-mono); font-weight: 600; white-space: nowrap; overflow: hidden; cursor: text; }
+/* `[Group] name` is one title in two parts, and the group is the part that
+   gives way: it is weighted to shrink hundreds of times faster than the name,
+   so a tile too narrow for both truncates the context rather than the thing you
+   are looking for. Below a tile width where a clipped prefix would say nothing
+   anyway, it drops out entirely and the name gets the whole header. */
+.ph-group { flex: 0 500 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--muted); font-weight: 500; }
+.ph-name { flex: 0 1 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .pane-head .ph-right { grid-column: 3; min-width: 0; display: inline-flex; align-items: center; justify-self: end; gap: 6px; }
 .pane-head .ph-path { min-width: 0; max-width: min(24vw, 220px); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--muted); font-family: var(--font-mono); font-size: 10.5px; font-weight: 500; }
 .pane-head .ph-title-input { width: 100%; text-align: center; font: inherit; font-family: var(--font-mono); font-weight: 600; padding: 1px 6px; border: 1px solid var(--accent); border-radius: var(--r-sm); background: var(--panel-2); color: var(--text); min-width: 0; }
@@ -570,6 +577,11 @@ body {
 @container (max-width: 520px) {
   .pane-head .ph-path { display: none; }
 }
+/* Narrower than this a prefix could only ever be a sliver of itself, and a
+   header that reads "[A… name" is worse than one that just reads "name". */
+@container (max-width: 260px) {
+  .pane-head .ph-group { display: none; }
+}
 .slot { transition: border-color 0.15s ease-out, box-shadow 0.15s ease-out; }
 /* fallback focus tint (terminal panes override with their agent's color inline) */
 .slot.focused { border-color: color-mix(in srgb, var(--accent) 45%, var(--border)); box-shadow: 0 4px 18px -10px rgba(0, 0, 0, 0.35); }
@@ -1074,7 +1086,7 @@ a.btn-ghost { text-decoration: none; }
 .modebar { flex: none; margin-right: 6px; }
 .modebar button { padding: 2px 8px; font-size: 10.5px; letter-spacing: 0.02em; }
 
-.mtitle { font-size: 13px; font-weight: 600; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.mtitle { display: inline-flex; align-items: baseline; gap: 5px; min-width: 0; font-size: 13px; font-weight: 600; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .mchips { display: flex; gap: 6px; overflow-x: auto; flex: 1; padding: 2px; }
 .mchip { display: inline-flex; align-items: center; gap: 7px; padding: 6px 10px; background: var(--panel); border: 1px solid var(--border); border-radius: var(--r-md); cursor: pointer; flex: none; }
 .mchip.on { border-color: var(--accent); background: color-mix(in srgb, var(--accent) 10%, transparent); }

web/test/sessionTitle.test.mjs

@@ -0,0 +1,70 @@
+// The length budget, which is the part of `[Group] name` that is easy to get
+// wrong: a prefix that pushes the agent's own name out of a browser tab has
+// made the title worse than it was before.
+//
+// Same shape as exchanges.test.mjs — no test runner, esbuild transpiles the
+// module and we import it. Run with:  node test/sessionTitle.test.mjs
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { build } from 'esbuild';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const out = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'title-')), 'sessionTitle.mjs');
+await build({
+  entryPoints: [path.join(HERE, '../src/lib/sessionTitle.ts')],
+  outfile: out, format: 'esm', bundle: false, logLevel: 'error',
+});
+const { groupLabel, sessionTitle, TAB_BUDGET } = await import(pathToFileURL(out).href);
+
+let failed = 0;
+const check = (what, fn) => {
+  try { fn(); console.log(`  ok  ${what}`); } catch (e) {
+    failed++;
+    console.log(`  FAIL ${what}\n       ${e.message.split('\n')[0]}`);
+  }
+};
+
+console.log('groupLabel');
+check('a real group is itself', () => assert.equal(groupLabel('Agent-manager'), 'Agent-manager'));
+check('no group is null, not a word', () => {
+  assert.equal(groupLabel(null), null);
+  assert.equal(groupLabel(undefined), null);
+  assert.equal(groupLabel(''), null);
+  assert.equal(groupLabel('   '), null);
+});
+
+console.log('sessionTitle');
+check('the example from the request', () => {
+  assert.equal(sessionTitle('claude-code-7', 'Agent-manager'), '[Agent-manager] claude-code-7');
+});
+check('ungrouped degrades to a bare name', () => {
+  for (const g of [null, undefined, '', '  ']) assert.equal(sessionTitle('claude-code-7', g), 'claude-code-7');
+});
+check('an over-budget pair keeps the name whole and elides the group', () => {
+  const t = sessionTitle('claude-code-7', 'a-very-long-group-name-that-will-not-fit', 30);
+  assert.ok(t.endsWith('claude-code-7'), `name survived: ${t}`);
+  assert.ok(t.startsWith('[') && t.includes('…]'), `group elided: ${t}`);
+  assert.ok(t.length <= 30, `within budget: ${t.length}`);
+});
+check('when the group can only show a stub, it is dropped instead', () => {
+  const t = sessionTitle('a-session-name-of-exactly-this-length', 'Agent-manager', 42);
+  assert.equal(t, 'a-session-name-of-exactly-this-length');
+});
+check('a name that blows the budget alone is still returned whole', () => {
+  const name = 'x'.repeat(80);
+  assert.equal(sessionTitle(name, 'Agent-manager', 42), name);
+});
+check('the budget is respected exactly at the boundary', () => {
+  // '[g] name' is 8 chars: fits a budget of 8, elides at 7.
+  assert.equal(sessionTitle('name', 'g', 8), '[g] name');
+  assert.equal(sessionTitle('name', 'group', 8), 'name');
+});
+check('the default budget fits a realistic pair', () => {
+  assert.ok(sessionTitle('claude-code-7', 'Agent-manager').length <= TAB_BUDGET);
+});
+
+console.log(failed ? `\n${failed} check(s) failed` : '\nall checks passed');
+process.exit(failed ? 1 : 0);