@zgeoff/atc 0.1.0 → 0.1.2

package/README.md

@@ -7,6 +7,11 @@
     mouse.
   </p>
 
+  <p>
+    <a href="https://www.npmjs.com/package/@zgeoff/atc"><img src="https://img.shields.io/npm/v/%40zgeoff%2Fatc" alt="npm version"></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  </p>
+
   <p>
     <a href="./docs/README.md">Documentation</a> •
     <a href="./docs/architecture/overview.md">Architecture</a> •
@@ -14,12 +19,16 @@
   </p>
 </div>
 
-## Run
+## Install
 
 ```sh
-bun src/cli.ts   # or `atc` if bin/atc is on your PATH
+bun add -g @zgeoff/atc
+atc
 ```
 
+Needs [Bun](https://bun.sh) (atc runs from source through it) and the `claude` CLI on your PATH.
+From a checkout, `bun src/cli.ts` runs the same thing.
+
 The first invocation auto-spawns the daemon (`atc daemon` runs it in the foreground for systemd or
 debugging); the TUI is a thin client, so quitting or crashing it leaves every session running. Runs
 fine nested inside zellij/tmux (give the pane locked mode so Ctrl-Space reaches atc).
@@ -28,13 +37,14 @@ fine nested inside zellij/tmux (give the pane locked mode so Ctrl-Space reaches
 
 | Key             | Where          | Action                                                                                         |
 | --------------- | -------------- | ---------------------------------------------------------------------------------------------- |
-| `Ctrl-Space`    | anywhere       | toggle session overlay                                                                         |
-| `n`             | home/overlay   | spawn: pick dir (zoxide + history, fuzzy) → name → optional first prompt                       |
+| leader          | anywhere       | toggle session overlay — `Ctrl-Space` by default, configurable (see Config)                    |
+| `n`             | home/overlay   | spawn: pick dir (zoxide + history, fuzzy) → name → optional group → optional first prompt      |
 | `r`             | home/overlay   | adopt: pick dir → name → `claude --resume` (Claude's session picker opens in the new PTY)      |
 | `R`             | home           | restore last fleet after a daemon death — respawns every session via `claude --resume <id>`    |
 | `j`/`k`/`↑`/`↓` | overlay/picker | move                                                                                           |
 | `Enter`         | overlay        | attach (auto-acks)                                                                             |
-| `/`             | overlay        | fzf-style filter: type to narrow by name/dir, `⏎` attach top match, `esc` clear                |
+| `Tab`           | overlay        | attach the most urgent needs-you session                                                       |
+| `/`             | overlay        | fuzzy filter by name/dir (chars in order), `⏎` attach top match, `esc` clear                   |
 | `a`             | overlay        | ack notification without attaching                                                             |
 | `H`             | overlay        | eject to headless: the terminal dies, a headless Agent SDK run resumes the same session        |
 | `P`             | overlay        | revive: a fresh terminal resumes a headless or killed session in place                         |
@@ -44,6 +54,11 @@ fine nested inside zellij/tmux (give the pane locked mode so Ctrl-Space reaches
 | `?`             | overlay        | full key reference — the hint row only shows actions valid for the selected session            |
 | `q`             | home/overlay   | quit the client — sessions keep running in the daemon                                          |
 
+The overlay clusters sessions under dim headers when more than one group exists: a session's
+explicit group wins, and sessions without one fall back to the directory they were spawned from.
+Groups also come from outside — the `atc_session_update` MCP tool renames and regroups sessions, so
+an agent can organise the fleet for you.
+
 Revive (`P`) and headless eject (`H`) resume the session from its saved transcript, so both need one
 to exist: a session killed before its first exchange has nothing on disk yet, and the overlay says
 so in its message column instead of resuming.
@@ -63,17 +78,36 @@ status bar turns red and names the most urgent session.
 
 ## Config
 
-`~/.config/atc/config.json`:
+`~/.config/atc/config.json` (created with defaults on first run):
 
 ```json
-{ "claudeBin": "claude", "claudeArgs": [] }
+{
+  "claudeBin": "claude",
+  "claudeArgs": [],
+  "leader": "ctrl-space"
+}
+```
+
+| Field        | Default        | Meaning                                                                               |
+| ------------ | -------------- | ------------------------------------------------------------------------------------- |
+| `claudeBin`  | `"claude"`     | The binary spawned for every session.                                                 |
+| `claudeArgs` | `[]`           | Prepended to every spawn, e.g. `["--model", "opus"]`.                                 |
+| `leader`     | `"ctrl-space"` | The overlay toggle: `ctrl-` plus a letter or one of `\` `]` `^` `_`, e.g. `"ctrl-]"`. |
+
+Pick a different leader when `Ctrl-Space` is taken on your machine — Raycast on macOS claims it, and
+`ctrl-]` is a solid replacement that no common terminal, multiplexer, or OS shortcut wants. An
+unknown or reserved value falls back to the default.
+
+`atc mcp` exposes the fleet as MCP tools (list, spawn, drive, organise) to any MCP client, wrangled
+sessions included:
+
+```sh
+claude mcp add --scope user atc -- atc mcp
 ```
 
-`claudeArgs` is prepended to every spawn (e.g. `["--model", "opus"]`). `atc mcp` exposes the fleet
-as MCP tools (list, spawn, drive) to any MCP client, wrangled sessions included. Daemon state — the
-restorable fleet, spawn-dir history, and the hook-event trail — lives in `~/.local/state/atc/atc.db`
-(SQLite), next to `status.json` (read by the injected statusline); the daemon's pid file sits in
-`$XDG_RUNTIME_DIR/atc-daemon.pid`, beside its sockets.
+Daemon state — the restorable fleet, spawn-dir history, and the hook-event trail — lives in
+`~/.local/state/atc/atc.db` (SQLite), next to `status.json` (read by the injected statusline); the
+daemon's pid file sits in `$XDG_RUNTIME_DIR/atc-daemon.pid`, beside its sockets.
 
 ## Crash safety
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Terminal control tower for Claude Code sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",

package/src/config.ts

@@ -6,11 +6,18 @@ import { isRecord } from './report';
 export interface Config {
   claudeBin: string;
   claudeArgs: string[];
+  leader: LeaderKey;
+}
+
+interface LeaderKey {
+  readonly code: number;
+  readonly label: string;
 }
 
 const DEFAULTS: Config = {
   claudeBin: 'claude',
   claudeArgs: [],
+  leader: { code: 0, label: '^Space' },
 };
 
 const configDir = join(homedir(), '.config', 'atc');
@@ -50,8 +57,58 @@ export function loadConfig(): Config {
       ? parsed['claudeArgs'].filter((a): a is string => typeof a === 'string')
       : DEFAULTS.claudeArgs;
 
-    return { claudeBin, claudeArgs };
+    const leader =
+      (typeof parsed['leader'] === 'string' ? decodeLeader(parsed['leader']) : null) ??
+      DEFAULTS.leader;
+
+    return { claudeBin, claudeArgs, leader };
   } catch {
     return { ...DEFAULTS };
   }
 }
+
+// Control bytes the terminal needs for its own input: enter, tab, and esc
+// as leaders would swallow ordinary typing.
+const RESERVED_CODES = new Set([0x09, 0x0d, 0x1b]);
+
+/**
+ * Decodes a leader name like "ctrl-space", "ctrl-]", or "ctrl-a" into its
+ * control byte and status-bar label. Unknown or reserved keys decode to
+ * null, so a bad config falls back to the default instead of breaking the
+ * client.
+ */
+function decodeLeader(name: string): LeaderKey | null {
+  const m = /^ctrl-(?<key>.+)$/i.exec(name.trim().toLowerCase());
+  const key = m?.groups?.['key'];
+
+  if (key === undefined) {
+    return null;
+  }
+
+  if (key === 'space') {
+    return { code: 0, label: '^Space' };
+  }
+
+  let code: number | null = null;
+  const cp = key.codePointAt(0);
+
+  if (/^[a-z]$/.test(key) && cp !== undefined) {
+    code = cp - 96;
+  } else if (key === '[') {
+    code = 0x1b;
+  } else if (key === '\\') {
+    code = 0x1c;
+  } else if (key === ']') {
+    code = 0x1d;
+  } else if (key === '^') {
+    code = 0x1e;
+  } else if (key === '_') {
+    code = 0x1f;
+  }
+
+  if (code === null || RESERVED_CODES.has(code)) {
+    return null;
+  }
+
+  return { code, label: `^${key.toUpperCase()}` };
+}

package/src/daemon-connection.ts

@@ -15,6 +15,7 @@ interface SpawnParams {
   readonly rows: number;
   readonly resume: boolean | string;
   readonly namedBy: 'user' | 'auto';
+  readonly group?: string;
 }
 
 export interface DaemonContext {
@@ -24,6 +25,7 @@ export interface DaemonContext {
   readonly collectFleet: () => FleetEntry[];
   readonly spawnSession: (p: SpawnParams) => SessionDescriptor;
   readonly killSession: (id: string) => boolean;
+  readonly updateSession: (id: string, name?: string, group?: string) => boolean;
   readonly ackSession: (id: string) => boolean;
   readonly buildResumeCommand: (id: string) => string | null;
   readonly answerPermission: (request: string, decision: string) => AnswerResult;
@@ -213,6 +215,19 @@ export class DaemonConnection {
 
         return;
       }
+      case 'session.update': {
+        const sessionID = typeof req.p?.['session'] === 'string' ? req.p['session'] : '';
+        const name = typeof req.p?.['name'] === 'string' ? req.p['name'] : undefined;
+        const group = typeof req.p?.['group'] === 'string' ? req.p['group'] : undefined;
+
+        if (this.ctx.updateSession(sessionID, name, group)) {
+          this.sendOk(req.id, {});
+        } else {
+          this.sendErr(req.id, 'no_such_session', `no session '${sessionID}'`);
+        }
+
+        return;
+      }
       case 'session.kill': {
         this.applySessionVerb(req, this.ctx.killSession);
 
@@ -348,6 +363,8 @@ export class DaemonConnection {
       resume = rawResume;
     }
 
+    const group = typeof req.p?.['group'] === 'string' ? req.p['group'] : '';
+
     const session = this.ctx.spawnSession({
       cwd,
       name: name === '' ? basename(cwd) : name,
@@ -356,6 +373,7 @@ export class DaemonConnection {
       rows: typeof req.p?.['rows'] === 'number' ? req.p['rows'] : 24,
       resume,
       namedBy: name === '' ? 'auto' : 'user',
+      ...(group === '' ? {} : { group }),
     });
 
     this.sendOk(req.id, { session });

package/src/daemon.ts

@@ -367,6 +367,7 @@ export function startDaemon(opts: DaemonOptions): DaemonHandle {
         kind: s.kind,
         alive: s.pty !== null || (s.kind === 'jsonl' && s.state !== 'exited'),
         ...(s.claudeId === undefined ? {} : { claudeId: s.claudeId }),
+        ...(s.group === undefined ? {} : { group: s.group }),
       }),
       renamed: () => ({
         v: PROTOCOL_V,
@@ -399,7 +400,7 @@ export function startDaemon(opts: DaemonOptions): DaemonHandle {
     collectSpawnDirs: () => store.collectSpawnDirs(),
     collectFleet: () => store.loadFleet(),
     spawnSession: (p) => {
-      const s = mgr.spawn(p.cwd, p.name, p.prompt, p.cols, p.rows, p.resume, p.namedBy);
+      const s = mgr.spawn(p.cwd, p.name, p.prompt, p.cols, p.rows, p.resume, p.namedBy, p.group);
 
       ptyDims.set(s.id, { cols: p.cols, rows: p.rows });
       screens.set(s.id, new ScreenModel(p.cols, p.rows));
@@ -407,6 +408,7 @@ export function startDaemon(opts: DaemonOptions): DaemonHandle {
 
       return getDescriptor(mgr, s.id);
     },
+    updateSession: (id, name, group) => mgr.updateSession(id, name, group),
     killSession: (id) => {
       if (!mgr.sessions.some((s) => s.id === id)) {
         return false;
@@ -556,7 +558,16 @@ export function startDaemon(opts: DaemonOptions): DaemonHandle {
           continue;
         }
 
-        const s = mgr.spawn(entry.cwd, entry.name, '', cols, rows, entry.claudeId);
+        const s = mgr.spawn(
+          entry.cwd,
+          entry.name,
+          '',
+          cols,
+          rows,
+          entry.claudeId,
+          'auto',
+          entry.group,
+        );
 
         ptyDims.set(s.id, { cols, rows });
         screens.set(s.id, new ScreenModel(cols, rows));

package/src/dirs.ts

@@ -38,26 +38,21 @@ export function pickMatches(items: readonly string[], filter: string): string[]
     return [...items];
   }
 
-  const f = filter.toLowerCase();
-
-  const scored = items
-    .map((item) => {
-      const base = basename(item).toLowerCase();
-      let score = -1;
-
-      if (base.startsWith(f)) {
-        score = 0;
-      } else if (base.includes(f)) {
-        score = 1;
-      } else if (item.toLowerCase().includes(f)) {
-        score = 2;
-      }
-
-      return { item, score };
-    })
-    .filter((x) => x.score >= 0);
-
-  return scored.toSorted((a, b) => a.score - b.score).map((x) => x.item);
+  const scored: { item: string; score: number }[] = [];
+
+  for (const item of items) {
+    // Basename hits beat full-path hits, so `vers` ranks ~/projects/vers
+    // above every path that merely passes through a vers directory.
+    const baseScore = findFuzzyScore(basename(item), filter);
+    const pathScore = findFuzzyScore(item, filter);
+    const score = baseScore === null ? pathScore : baseScore + 100;
+
+    if (score !== null) {
+      scored.push({ item, score });
+    }
+  }
+
+  return scored.toSorted((a, b) => b.score - a.score).map((x) => x.item);
 }
 
 export function formatDir(d: string): string {
@@ -65,3 +60,44 @@ export function formatDir(d: string): string {
 
   return d.startsWith(home) ? `~${d.slice(home.length)}` : d;
 }
+
+const SEPARATORS = new Set(['/', '-', '_', '.', ' ']);
+
+/**
+ * Scores how well a filter fuzzy-matches a candidate: every filter
+ * character must appear in order, consecutive characters and characters
+ * starting a word score higher, and a miss is null rather than zero so
+ * non-matches are distinguishable from weak matches.
+ */
+export function findFuzzyScore(candidate: string, filter: string): number | null {
+  const hay = candidate.toLowerCase();
+  const needle = filter.toLowerCase();
+  let score = 0;
+  let pos = 0;
+  let prevHit = -2;
+
+  for (const ch of needle) {
+    const hit = hay.indexOf(ch, pos);
+
+    if (hit === -1) {
+      return null;
+    }
+
+    score += 1;
+
+    if (hit === prevHit + 1) {
+      score += 2;
+    }
+
+    const before = hay[hit - 1];
+
+    if (hit === 0 || (before !== undefined && SEPARATORS.has(before))) {
+      score += 2;
+    }
+
+    prevHit = hit;
+    pos = hit + 1;
+  }
+
+  return score;
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 import { basename } from 'node:path';
 import { bootDaemonClient } from './boot-daemon';
-import { collectDirs, formatDir, pickMatches } from './dirs';
+import { loadConfig } from './config';
+import { collectDirs, findFuzzyScore, formatDir, pickMatches } from './dirs';
 import type { EventMsg } from './protocol';
 import { isRecord } from './report';
 import { countSessionStates, sortSessionViews } from './sessions';
@@ -14,6 +15,7 @@ type Mode =
   | 'help'
   | 'picker-dir'
   | 'picker-name'
+  | 'picker-group'
   | 'picker-prompt'
   | 'picker-eject';
 
@@ -21,6 +23,7 @@ interface MirrorSession {
   id: string;
   name: string;
   cwd: string;
+  group?: string;
   state: SessionState;
   unread: boolean;
   lastMsg: string;
@@ -45,6 +48,7 @@ let pickerInput = '';
 let pickerSelected = 0;
 let spawnDir = '';
 let spawnName = '';
+let spawnGroup = '';
 let spawnResume = false;
 const stdout = process.stdout;
 
@@ -76,6 +80,7 @@ function scheduleStatus() {
         counts: countSessionStates(fleet),
         focusedName: focused === null ? null : focused.name,
         urgentName: urgent === undefined ? null : urgent.name,
+        leaderLabel: leader.label,
       });
     }
   }, 50);
@@ -127,7 +132,7 @@ function toBase() {
   } else {
     mode = 'home';
 
-    drawHome(fleetCount);
+    drawHome(fleetCount, leader.label);
   }
 
   scheduleStatus();
@@ -180,7 +185,7 @@ function openHelp() {
 function applyHelpKey(buf: Buffer) {
   const ch = buf.toString();
 
-  if (buf[0] === KEY.esc || ch === '?' || ch === 'q' || buf[0] === KEY.ctrlSpace) {
+  if (buf[0] === KEY.esc || ch === '?' || ch === 'q' || buf[0] === leader.code) {
     openOverlay();
   }
 }
@@ -195,9 +200,11 @@ function pickOverlaySessions(): MirrorSession[] {
     return sorted;
   }
 
-  const f = overlayFilter.toLowerCase();
+  const f = overlayFilter;
 
-  return sorted.filter((s) => `${s.name} ${formatDir(s.cwd)}`.toLowerCase().includes(f));
+  return sorted.filter(
+    (s) => findFuzzyScore(`${s.name} ${s.group ?? ''} ${formatDir(s.cwd)}`, f) !== null,
+  );
 }
 
 function renderOverlay() {
@@ -253,6 +260,18 @@ function renderPicker() {
       placeholder: basename(spawnDir),
       hint: `session name for ${formatDir(spawnDir)} · ⏎ accept · esc back`,
     });
+  } else if (mode === 'picker-group') {
+    const groups = [...new Set(fleet.map((s) => s.group).filter((g) => g !== undefined))];
+    const known = groups.length === 0 ? '' : ` · existing: ${groups.slice(0, 4).join(', ')}`;
+
+    drawPicker({
+      title: `${verb}: group`,
+      items: [],
+      selected: -1,
+      input: pickerInput,
+      placeholder: 'optional — ⏎ to skip',
+      hint: `group for the overlay hierarchy${known} · ⏎ accept · esc back`,
+    });
   } else if (mode === 'picker-eject') {
     drawPicker({
       title: 'eject: headless instruction',
@@ -278,6 +297,7 @@ function renderPicker() {
 
 async function openDirPicker(resume = false) {
   spawnResume = resume;
+  spawnGroup = '';
 
   let recent: string[] = [];
 
@@ -325,6 +345,7 @@ async function spawnFromPicker(prompt: string) {
       cols: cols(),
       rows: ptyRows(),
       ...(spawnResume ? { resume: true } : {}),
+      ...(spawnGroup === '' ? {} : { group: spawnGroup }),
     });
 
     const spawned = toMirrorSession(ok['session']);
@@ -380,6 +401,7 @@ function toMirrorSession(value: unknown): MirrorSession | null {
     id: value['id'],
     name: value['name'],
     cwd: value['cwd'],
+    ...(typeof value['group'] === 'string' ? { group: value['group'] } : {}),
     state,
     unread: value['unread'],
     lastMsg: value['lastMsg'],
@@ -461,6 +483,14 @@ function applyDaemonEvent(e: EventMsg) {
           s.kind = e['kind'];
         }
 
+        if (typeof e['group'] === 'string') {
+          if (e['group'] === '') {
+            delete s.group;
+          } else {
+            s.group = e['group'];
+          }
+        }
+
         if (typeof e['unread'] === 'boolean') {
           s.unread = e['unread'];
         }
@@ -524,8 +554,10 @@ function copyToClipboard(text: string) {
 
 // ---- input ----
 
+const leader = loadConfig().leader;
+
 const KEY = {
-  ctrlSpace: 0x00,
+  tab: 0x09,
   ctrlC: 0x03,
   ctrlU: 0x15,
   esc: 0x1b,
@@ -578,7 +610,7 @@ function applyOverlayFilterKey(buf: Buffer): boolean {
     return true;
   }
 
-  if (buf[0] === KEY.enter || isUp(buf) || isDown(buf) || buf[0] === KEY.ctrlSpace) {
+  if (buf[0] === KEY.enter || isUp(buf) || isDown(buf) || buf[0] === leader.code) {
     return false;
   }
 
@@ -636,7 +668,7 @@ function applyOverlayKey(buf: Buffer) {
     return;
   }
 
-  if (buf[0] === KEY.ctrlSpace || (buf[0] === KEY.esc && buf.length === 1)) {
+  if (buf[0] === leader.code || (buf[0] === KEY.esc && buf.length === 1)) {
     toBase();
 
     return;
@@ -660,6 +692,16 @@ function applyOverlayKey(buf: Buffer) {
 
   const ch = buf.toString();
 
+  if (buf[0] === KEY.tab) {
+    const needy = sortSessionViews(fleet).find((s) => s.state === 'needs_you' && s.alive);
+
+    if (needy !== undefined) {
+      void attach(needy.id);
+    }
+
+    return;
+  }
+
   if (buf[0] === KEY.enter && sel !== undefined && sel.alive) {
     void attach(sel.id);
 
@@ -778,7 +820,7 @@ function applyTextKey(buf: Buffer, onSubmit: () => void, onCancel: () => void) {
     return;
   }
 
-  if (buf[0] === KEY.ctrlSpace) {
+  if (buf[0] === leader.code) {
     toBase();
 
     return;
@@ -877,7 +919,7 @@ const stdinDecoder = new TextDecoder('utf-8');
 process.stdin.on('data', (buf: Buffer) => {
   switch (mode) {
     case 'attached': {
-      if (buf[0] === KEY.ctrlSpace && buf.length === 1) {
+      if (buf[0] === leader.code && buf.length === 1) {
         openOverlay();
 
         return;
@@ -893,7 +935,7 @@ process.stdin.on('data', (buf: Buffer) => {
       return;
     }
     case 'home': {
-      if (buf[0] === KEY.ctrlSpace) {
+      if (buf[0] === leader.code) {
         openOverlay();
 
         return;
@@ -972,6 +1014,30 @@ process.stdin.on('data', (buf: Buffer) => {
         () => {
           spawnName = pickerInput.trim();
           pickerInput = '';
+          mode = 'picker-group';
+
+          stdout.write(ansi.clear);
+
+          renderPicker();
+        },
+        () => {
+          pickerInput = '';
+          mode = 'picker-dir';
+
+          stdout.write(ansi.clear);
+
+          renderPicker();
+        },
+      );
+
+      return;
+    }
+    case 'picker-group': {
+      applyTextKey(
+        buf,
+        () => {
+          spawnGroup = pickerInput.trim();
+          pickerInput = '';
 
           // Adopt skips the prompt step: claude --resume opens its own
           // session picker inside the new PTY.
@@ -989,7 +1055,7 @@ process.stdin.on('data', (buf: Buffer) => {
         },
         () => {
           pickerInput = '';
-          mode = 'picker-dir';
+          mode = 'picker-name';
 
           stdout.write(ansi.clear);
 
@@ -1007,7 +1073,7 @@ process.stdin.on('data', (buf: Buffer) => {
         },
         () => {
           pickerInput = '';
-          mode = 'picker-name';
+          mode = 'picker-group';
 
           stdout.write(ansi.clear);
 
@@ -1037,7 +1103,7 @@ stdout.on('resize', () => {
   }
 
   if (mode === 'home') {
-    drawHome(fleetCount);
+    drawHome(fleetCount, leader.label);
   }
 
   if (mode === 'overlay') {
@@ -1072,5 +1138,5 @@ process.on('SIGHUP', () => quit());
 // ---- start ----
 stdout.write(ansi.altScreenOn);
 
-drawHome(fleetCount);
+drawHome(fleetCount, leader.label);
 scheduleStatus();

package/src/mcp-server.ts

@@ -69,6 +69,21 @@ const TOOLS: readonly MCPTool[] = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'atc_session_update',
+    description:
+      'Rename and/or regroup a session. Renames stick against auto-summaries; an empty group clears the grouping. Use this to organise the fleet: name sessions after their task and group related work.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session: { type: 'string', description: 'The atc session id' },
+        name: { type: 'string', description: 'New display name; omit to keep' },
+        group: { type: 'string', description: 'New group; empty string clears, omit to keep' },
+      },
+      required: ['session'],
+      additionalProperties: false,
+    },
+  },
   {
     name: 'atc_session_kill',
     description: 'Kill a session. A second kill on a dead session removes it from the list.',
@@ -237,6 +252,15 @@ async function runTool(
 
       return 'sent';
     }
+    case 'atc_session_update': {
+      await client.sendRequest('session.update', {
+        session: args['session'],
+        ...(typeof args['name'] === 'string' ? { name: args['name'] } : {}),
+        ...(typeof args['group'] === 'string' ? { group: args['group'] } : {}),
+      });
+
+      return 'updated';
+    }
     case 'atc_session_kill': {
       await client.sendRequest('session.kill', { session: args['session'] });
 

package/src/sessions.ts

@@ -23,6 +23,7 @@ export interface SessionDescriptor {
   readonly lastMsg: string;
   readonly lastDetail?: string;
   readonly claudeId?: string;
+  readonly group?: string;
   readonly namedBy: 'user' | 'auto' | 'agent';
   readonly createdAt: number;
   readonly kind: 'pty' | 'jsonl';
@@ -41,6 +42,7 @@ export interface Session {
   lastDetail?: string;
   claudeId?: string;
   transcriptSource?: string;
+  group?: string;
 
   // who last named this session: the agent's own rename beats everything, a
   // user-typed spawn name beats auto-summaries.
@@ -54,6 +56,7 @@ export interface FleetEntry {
   readonly name: string;
   readonly cwd: string;
   readonly claudeId: string;
+  readonly group?: string;
 }
 
 const fleetFile = join(stateDir, 'fleet.json');
@@ -187,6 +190,42 @@ export class SessionManager {
   }
 
   // Reports a headless run's lifecycle into the session state machine.
+  /**
+   * Renames and/or regroups a session on a caller's behalf. A rename lands
+   * at user strength, so auto-summaries stop overwriting it while an
+   * in-session rename still wins. An empty group clears the grouping.
+   */
+  updateSession(id: string, name?: string, group?: string): boolean {
+    const s = this.sessions.find((x) => x.id === id);
+
+    if (s === undefined) {
+      return false;
+    }
+
+    if (name !== undefined && name !== '' && s.namedBy !== 'agent') {
+      s.name = name;
+      s.namedBy = 'user';
+
+      this.onEvent('renamed', s);
+    }
+
+    if (group !== undefined) {
+      if (group === '') {
+        delete s.group;
+      } else {
+        s.group = group;
+      }
+
+      this.onEvent('state', s);
+    }
+
+    this.writeFleet();
+    this.writeStatus();
+    this.emitChange();
+
+    return true;
+  }
+
   updateSurfaceState(id: string, state: SessionState, msg: string) {
     const s = this.sessions.find((x) => x.id === id);
 
@@ -240,6 +279,7 @@ export class SessionManager {
     rows: number,
     resume: boolean | string = false,
     namedBy: 'user' | 'auto' = 'auto',
+    group?: string,
   ): Session {
     const id = `s${++counter}-${Date.now().toString(36)}`;
     const plan = this.adapter.planSpawn({ prompt, resume });
@@ -268,6 +308,7 @@ export class SessionManager {
       unread: false,
       lastMsg: initialMsg,
       ...(typeof resume === 'string' ? { claudeId: resume } : {}),
+      ...(group === undefined ? {} : { group }),
       namedBy,
       createdAt: Date.now(),
     };
@@ -309,6 +350,7 @@ export class SessionManager {
       lastMsg: s.lastMsg,
       ...(s.lastDetail === undefined ? {} : { lastDetail: s.lastDetail }),
       ...(s.claudeId === undefined ? {} : { claudeId: s.claudeId }),
+      ...(s.group === undefined ? {} : { group: s.group }),
       namedBy: s.namedBy,
       createdAt: s.createdAt,
       kind: s.kind,
@@ -525,7 +567,12 @@ export class SessionManager {
       const live = s.pty !== null || (s.kind === 'jsonl' && s.state !== 'exited');
 
       if (live && s.claudeId !== undefined) {
-        fleet.push({ name: s.name, cwd: s.cwd, claudeId: s.claudeId });
+        fleet.push({
+          name: s.name,
+          cwd: s.cwd,
+          claudeId: s.claudeId,
+          ...(s.group === undefined ? {} : { group: s.group }),
+        });
       }
     }
 

package/src/state-store.ts

@@ -23,7 +23,8 @@ export class StateStore {
       CREATE TABLE IF NOT EXISTS fleet (
         claude_id TEXT PRIMARY KEY,
         name TEXT NOT NULL,
-        cwd TEXT NOT NULL
+        cwd TEXT NOT NULL,
+        grp TEXT
       );
       CREATE TABLE IF NOT EXISTS events (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -39,6 +40,17 @@ export class StateStore {
       );
     `);
 
+    // Stores created before groups existed lack the column; the create
+    // above only applies to fresh databases.
+    const fleetColumns = this.db
+      .query<{ name: string }, []>('PRAGMA table_info(fleet)')
+      .all()
+      .map((c) => c.name);
+
+    if (!fleetColumns.includes('grp')) {
+      this.db.run('ALTER TABLE fleet ADD COLUMN grp TEXT');
+    }
+
     if (legacyFleetPath !== undefined) {
       this.adoptLegacyFleet(legacyFleetPath);
     }
@@ -46,12 +58,23 @@ export class StateStore {
 
   loadFleet(): FleetEntry[] {
     const rows = this.db
-      .query<{ claude_id: string; name: string; cwd: string }, []>(
-        'SELECT claude_id, name, cwd FROM fleet',
+      .query<{ claude_id: string; name: string; cwd: string; grp: string | null }, []>(
+        'SELECT claude_id, name, cwd, grp FROM fleet',
       )
       .all();
 
-    return rows.map((row) => ({ claudeId: row.claude_id, name: row.name, cwd: row.cwd }));
+    const entries: FleetEntry[] = [];
+
+    for (const row of rows) {
+      const entry: FleetEntry =
+        row.grp === null
+          ? { claudeId: row.claude_id, name: row.name, cwd: row.cwd }
+          : { claudeId: row.claude_id, name: row.name, cwd: row.cwd, group: row.grp };
+
+      entries.push(entry);
+    }
+
+    return entries;
   }
 
   writeFleet(entries: readonly FleetEntry[]): void {
@@ -59,11 +82,11 @@ export class StateStore {
       this.db.run('DELETE FROM fleet');
 
       const insert = this.db.query(
-        'INSERT OR REPLACE INTO fleet (claude_id, name, cwd) VALUES (?1, ?2, ?3)',
+        'INSERT OR REPLACE INTO fleet (claude_id, name, cwd, grp) VALUES (?1, ?2, ?3, ?4)',
       );
 
       for (const entry of all) {
-        insert.run(entry.claudeId, entry.name, entry.cwd);
+        insert.run(entry.claudeId, entry.name, entry.cwd, entry.group ?? null);
       }
     });
 

package/src/ui.ts

@@ -66,6 +66,7 @@ export interface StatusView {
   readonly counts: Readonly<Record<SessionState, number>>;
   readonly focusedName: string | null;
   readonly urgentName: string | null;
+  readonly leaderLabel: string;
 }
 
 export function drawStatusBar(view: StatusView) {
@@ -93,7 +94,7 @@ export function drawStatusBar(view: StatusView) {
   }
 
   const joined = parts.join(' ▏');
-  const right = ` ${joined === '' ? 'idle' : joined} ▏^Space `;
+  const right = ` ${joined === '' ? 'idle' : joined} ▏${view.leaderLabel} `;
   const pad = Math.max(1, width - left.length - right.length);
   const bg = c.needs_you > 0 ? `${ESC}[1;97;41m` : `${ESC}[30;47m`;
   const text = truncate(left + ' '.repeat(pad) + right, width).padEnd(width);
@@ -152,6 +153,7 @@ export interface OverlaySessionView extends SessionView {
   readonly alive: boolean;
   readonly kind: 'pty' | 'jsonl';
   readonly resumable: boolean;
+  readonly group?: string;
 }
 
 export interface OverlayView {
@@ -171,15 +173,29 @@ export function drawOverlay(view: OverlayView) {
     rowsList.push(dimRow(width, empty));
   }
 
+  // Sessions cluster under dim headers when more than one group exists: an
+  // explicit group wins, sessions without one fall back to their spawn
+  // directory. The rows keep the sorted order, so urgent groups lead.
+  const grouped = new Set(view.sessions.map((s) => s.group ?? s.cwd)).size > 1;
+  let lastKey: string | null = null;
+
   for (const [i, s] of view.sessions.entries()) {
+    const key = s.group ?? s.cwd;
+
+    if (grouped && key !== lastKey) {
+      lastKey = key;
+
+      rowsList.push(dimRow(width, `▸ ${s.group ?? formatDir(s.cwd)}`));
+    }
+
     const sel = i === view.selected;
     const name = truncate(s.name, 16).padEnd(16);
     const state = STATE_LABEL[s.state].padEnd(9);
-    const dir = truncate(formatDir(s.cwd), 18).padEnd(18);
-    const msgWidth = Math.max(4, width - 4 - 2 - 17 - 10 - 19);
+    const dir = grouped ? '' : ` ${truncate(formatDir(s.cwd), 18).padEnd(18)}`;
+    const msgWidth = Math.max(4, width - 4 - 2 - 17 - 10 - (grouped ? 0 : 19));
     const msg = truncate(s.lastMsg, msgWidth).padEnd(msgWidth);
     const unread = s.unread ? `${ESC}[1;33m!${ESC}[0m` : ' ';
-    const body = `${name} ${state} ${dir} ${msg}`;
+    const body = `${name} ${state}${dir} ${msg}`;
     const styledBody = sel ? `${ESC}[7m${body}${ESC}[0m` : body;
 
     rowsList.push(boxRow(width, `${GLYPH[s.state]}${unread}${styledBody}`, 2 + body.length));
@@ -248,6 +264,7 @@ export function drawHelp() {
 
   const lines = [
     '⏎  attach the selected session',
+    '⇥  attach the most urgent needs-you session',
     'a  ack its notification without attaching',
     'H  eject to a headless run',
     'P  revive a dead or headless session',
@@ -317,7 +334,7 @@ export function drawPicker(view: PickerView) {
   drawBox(rowsList);
 }
 
-export function drawHome(fleetCount = 0) {
+export function drawHome(fleetCount = 0, leaderLabel = '^Space') {
   out(ansi.clear + ansi.hideCursor);
 
   const msgs = [
@@ -326,7 +343,7 @@ export function drawHome(fleetCount = 0) {
     'n       spawn a session',
     'r       adopt an existing session (claude --resume)',
     ...(fleetCount > 0 ? [`R       restore last fleet (${fleetCount} sessions)`] : []),
-    '^Space  session list',
+    `${leaderLabel.padEnd(7)} session list`,
     'q       quit',
   ];