@zgeoff/atc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geoff Whatley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+<div align="center">
+  <h1>atc</h1>
+
+  <p>
+    Control tower for Claude Code sessions: stock <code>claude</code> instances in PTYs behind a
+    keyboard-driven session list with hook-driven attention routing — no panes, no tiling, no
+    mouse.
+  </p>
+
+  <p>
+    <a href="./docs/README.md">Documentation</a> •
+    <a href="./docs/architecture/overview.md">Architecture</a> •
+    <a href="./AGENTS.md">Agent Guidelines</a>
+  </p>
+</div>
+
+## Run
+
+```sh
+bun src/cli.ts   # or `atc` if bin/atc is on your PATH
+```
+
+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).
+
+## Keys
+
+| Key             | Where          | Action                                                                                         |
+| --------------- | -------------- | ---------------------------------------------------------------------------------------------- |
+| `Ctrl-Space`    | anywhere       | toggle session overlay                                                                         |
+| `n`             | home/overlay   | spawn: pick dir (zoxide + history, fuzzy) → name → 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                |
+| `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                         |
+| `y`             | overlay        | yank `cd <dir> && claude --resume <id>` to clipboard (OSC 52 + clip.exe/wl-copy/xclip)         |
+| `Y`             | overlay        | eject: yank the resume command, then kill the session here — paste it in any pane to take over |
+| `K`             | overlay        | kill selected (confirm with `y`) — the entry stays revivable with `P`; a second `K` forgets it |
+| `?`             | 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                                          |
+
+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.
+
+Everything else is passed through to the focused Claude session, which owns the full screen. Fleet
+state renders inside Claude Code's own status line (injected via the same `--settings` file): your
+configured statusline runs first, and atc appends `▏● 2 need you: auth-bug`. atc draws its own
+status bar only on the home and overlay screens.
+
+## How state tracking works
+
+Spawned sessions get a `--settings` file injecting `Notification`, `Stop`, `UserPromptSubmit`, and
+`SessionEnd` hooks that report to a unix socket (`$XDG_RUNTIME_DIR/atc.sock`). Your global Claude
+settings are untouched; sessions you start outside atc are unaffected. States: red `●` needs you,
+cyan `◐` running, green `✓` turn done, gray `✗` exited. The overlay sorts needs-you first; the
+status bar turns red and names the most urgent session.
+
+## Config
+
+`~/.config/atc/config.json`:
+
+```json
+{ "claudeBin": "claude", "claudeArgs": [] }
+```
+
+`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.
+
+## Crash safety
+
+A client crash or closed window costs nothing: the daemon keeps hosting the fleet, and the next
+`atc` reconnects. The daemon continuously writes the live fleet (name, cwd, Claude session id) to
+its SQLite store. If the daemon itself dies — crash, SIGKILL, reboot — the child claude processes
+die with it, but every session's transcript is already on disk. Start atc and press `R`: the whole
+fleet respawns via `claude --resume`. Only deliberate kills (`K`, `Y` eject) remove entries from the
+fleet, so it stays restorable.

package/bin/atc

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/cli.ts";

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@zgeoff/atc",
+  "version": "0.1.0",
+  "description": "Terminal control tower for Claude Code sessions",
+  "homepage": "https://github.com/zgeoff/atc#readme",
+  "bugs": "https://github.com/zgeoff/atc/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zgeoff/atc.git"
+  },
+  "bin": {
+    "atc": "bin/atc"
+  },
+  "files": [
+    "bin",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "scripts": {
+    "start": "bun src/cli.ts",
+    "build:agents": "bash scripts/build-agents-md.sh agents/shared.md agents/project.md AGENTS.md",
+    "audit": "bun audit",
+    "deadcode": "knip",
+    "lint": "oxlint --type-aware --type-check --report-unused-disable-directives-severity error",
+    "lint:fix": "oxlint --type-aware --type-check --report-unused-disable-directives-severity error --fix",
+    "test": "bun test",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "format": "oxfmt . && format-codemod --quiet .",
+    "format:check": "oxfmt --check . && format-codemod --check --quiet .",
+    "prepare": "command -v git > /dev/null 2>&1 && lefthook install --force || true"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.222",
+    "@xterm/addon-serialize": "0.14.0",
+    "@xterm/headless": "6.0.0",
+    "bun-pty": "0.4.10",
+    "citty": "0.2.2"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "21.2.0",
+    "@stylistic/eslint-plugin": "5.10.0",
+    "@tsconfig/strictest": "2.0.8",
+    "@types/bun": "1.3.14",
+    "@zgeoff/bun-test-extended": "0.0.4",
+    "@zgeoff/format-codemod": "0.0.8",
+    "@zgeoff/oxlint-config": "0.0.6",
+    "knip": "6.24.0",
+    "lefthook": "2.1.10",
+    "oxfmt": "0.57.0",
+    "oxlint": "1.73.0",
+    "oxlint-tsgolint": "0.24.0",
+    "tslib": "2.8.1",
+    "typescript": "7.0.2"
+  },
+  "packageManager": "bun@1.3.10"
+}

package/src/agent-adapter.ts

@@ -0,0 +1,60 @@
+import type { HookEvent } from './hooks';
+
+export interface SpawnOptions {
+  readonly prompt: string;
+
+  // true opens the agent's own session picker; a string resumes that
+  // specific agent session id.
+  readonly resume: boolean | string;
+}
+
+export interface SpawnPlan {
+  bin: string;
+  args: string[];
+}
+
+export interface AdapterEvent {
+  kind: 'started' | 'needs-input' | 'turn-done' | 'prompt-submitted' | 'ended' | 'heartbeat';
+  agentSessionID?: string;
+  message?: string;
+
+  // Fuller activity text than message: what the agent last said or was
+  // asked, for briefing. Bounded by the adapter.
+  detail?: string;
+
+  // Opaque handle the adapter can later pull a session name from.
+  nameSource?: string;
+}
+
+export interface NameUpdate {
+  name: string;
+  namedBy?: 'agent';
+}
+
+type AttentionJudgment = 'needs-input' | 'working';
+
+/**
+ * The universal attention fallback for agents without a hook system: judges
+ * the current serialized screen once output quiesces. null means no opinion
+ * and the session's state stands.
+ */
+interface ScreenDetector {
+  readonly detectAttention: (screen: string) => AttentionJudgment | null;
+}
+
+/**
+ * Everything specific to one agent CLI: how to spawn it, how to read its
+ * hook payloads, where its session names come from, and how to resume a
+ * session outside atc. The session core never sees past this interface.
+ */
+export interface AgentAdapter {
+  // The detector stack's screen tier; null when hooks are authoritative.
+  readonly screenDetector: ScreenDetector | null;
+  readonly planSpawn: (opts: SpawnOptions) => SpawnPlan;
+  readonly normalizeHook: (e: HookEvent) => AdapterEvent;
+  readonly loadName: (
+    source: string,
+    namedBy: 'user' | 'auto' | 'agent',
+  ) => Promise<NameUpdate | null>;
+  readonly buildResumeCommand: (cwd: string, agentSessionID: string | undefined) => string | null;
+}

package/src/attach-registry.ts

@@ -0,0 +1,89 @@
+export interface Dims {
+  readonly cols: number;
+  readonly rows: number;
+}
+
+/**
+ * Which clients are subscribed to which session's output, and the dims each
+ * reported. A session's effective size is the smallest reported width and
+ * height across its attached clients, so every attached terminal can render
+ * the whole screen.
+ */
+export class AttachRegistry<TClient> {
+  private readonly bySession = new Map<string, Map<TClient, Dims>>();
+
+  attach(sessionID: string, client: TClient, dims: Dims): void {
+    const clients = this.bySession.get(sessionID) ?? new Map<TClient, Dims>();
+
+    clients.set(client, dims);
+    this.bySession.set(sessionID, clients);
+  }
+
+  detach(sessionID: string, client: TClient): void {
+    const clients = this.bySession.get(sessionID);
+
+    clients?.delete(client);
+
+    if (clients !== undefined && clients.size === 0) {
+      this.bySession.delete(sessionID);
+    }
+  }
+
+  detachAll(client: TClient): string[] {
+    const affected: string[] = [];
+
+    for (const [sessionID, clients] of this.bySession) {
+      if (clients.delete(client)) {
+        affected.push(sessionID);
+      }
+
+      if (clients.size === 0) {
+        this.bySession.delete(sessionID);
+      }
+    }
+
+    return affected;
+  }
+
+  removeSession(sessionID: string): void {
+    this.bySession.delete(sessionID);
+  }
+
+  hasClient(sessionID: string, client: TClient): boolean {
+    return this.bySession.get(sessionID)?.has(client) ?? false;
+  }
+
+  updateDims(sessionID: string, client: TClient, dims: Dims): boolean {
+    const clients = this.bySession.get(sessionID);
+
+    if (clients === undefined || !clients.has(client)) {
+      return false;
+    }
+
+    clients.set(client, dims);
+
+    return true;
+  }
+
+  collectClients(sessionID: string): TClient[] {
+    return [...(this.bySession.get(sessionID)?.keys() ?? [])];
+  }
+
+  findEffectiveDims(sessionID: string): Dims | null {
+    const clients = this.bySession.get(sessionID);
+
+    if (clients === undefined || clients.size === 0) {
+      return null;
+    }
+
+    let cols = Number.POSITIVE_INFINITY;
+    let rows = Number.POSITIVE_INFINITY;
+
+    for (const dims of clients.values()) {
+      cols = Math.min(cols, dims.cols);
+      rows = Math.min(rows, dims.rows);
+    }
+
+    return { cols, rows };
+  }
+}

package/src/boot-daemon.ts

@@ -0,0 +1,106 @@
+import { spawn as spawnChild } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { daemonPidFile, daemonSocketPath } from './config';
+import { DaemonClient } from './daemon-client';
+import { getBuild } from './get-build';
+
+/**
+ * Opens a handshaken client to the daemon, booting the daemon first when its
+ * socket is absent. A daemon left running from an older build is restarted,
+ * so a fresh client never talks to stale daemon code — the fleet stays
+ * restorable afterwards through the usual cold-boot recovery. The expected
+ * build is read from disk on every attempt: a long-lived caller holding a
+ * build string from its own boot would otherwise restart daemons that are
+ * already current.
+ */
+export async function bootDaemonClient(): Promise<DaemonClient> {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const build = getBuild();
+
+    const client = await openOrBootDaemon();
+    const hello = await client.sendHello(build);
+
+    const daemonBuild = hello['daemon'];
+
+    if (daemonBuild === build || attempt > 0) {
+      return client;
+    }
+
+    client.stop();
+
+    await stopStaleDaemon();
+  }
+
+  throw new Error('the atc daemon could not be restarted');
+}
+
+async function openOrBootDaemon(): Promise<DaemonClient> {
+  let opened = await tryOpenDaemon();
+
+  if (opened === null) {
+    spawnDaemonDetached();
+
+    const deadline = Date.now() + 5000;
+
+    while (opened === null && Date.now() < deadline) {
+      await Bun.sleep(100);
+
+      opened = await tryOpenDaemon();
+    }
+  }
+
+  if (opened === null) {
+    throw new Error('the atc daemon did not come up; try `atc daemon` for its output');
+  }
+
+  return opened;
+}
+
+async function tryOpenDaemon(): Promise<DaemonClient | null> {
+  try {
+    return await DaemonClient.open(daemonSocketPath);
+  } catch {
+    return null;
+  }
+}
+
+async function stopStaleDaemon(): Promise<void> {
+  let pid = 0;
+
+  try {
+    pid = Number(readFileSync(daemonPidFile, 'utf8'));
+  } catch {
+    return;
+  }
+
+  if (!Number.isInteger(pid) || pid <= 1) {
+    return;
+  }
+
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch {
+    return;
+  }
+
+  const deadline = Date.now() + 3000;
+
+  while (Date.now() < deadline) {
+    try {
+      process.kill(pid, 0);
+    } catch {
+      return;
+    }
+
+    await Bun.sleep(50);
+  }
+}
+
+function spawnDaemonDetached() {
+  const exec = process.execPath;
+  const isBun = basename(exec) === 'bun' || basename(exec) === 'bun.exe';
+  const args = isBun ? [join(import.meta.dir, 'cli.ts'), 'daemon'] : ['daemon'];
+
+  spawnChild(exec, args, { detached: true, stdio: 'ignore' }).unref();
+}

package/src/claude-adapter.ts

@@ -0,0 +1,235 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import type {
+  AdapterEvent,
+  AgentAdapter,
+  NameUpdate,
+  SpawnOptions,
+  SpawnPlan,
+} from './agent-adapter';
+import type { Config } from './config';
+import { stateDir } from './config';
+import type { HookEvent } from './hooks';
+import { isRecord } from './report';
+
+/**
+ * The Claude Code adapter: spawn arguments, `--settings` instrumentation,
+ * resume semantics, transcript name-pulling, and statusline chaining.
+ */
+export class ClaudeAdapter implements AgentAdapter {
+  // Claude's hooks are authoritative; no screen heuristics needed.
+  readonly screenDetector = null;
+
+  private readonly config: Config;
+
+  private readonly settingsFile: string;
+
+  constructor(config: Config) {
+    this.config = config;
+    this.settingsFile = writeHookSettings();
+  }
+
+  planSpawn(opts: SpawnOptions): SpawnPlan {
+    return {
+      bin: this.config.claudeBin,
+      args: [
+        ...this.config.claudeArgs,
+        '--settings',
+        this.settingsFile,
+        ...(opts.resume === true ? ['--resume'] : []),
+        ...(typeof opts.resume === 'string' ? ['--resume', opts.resume] : []),
+        ...(opts.prompt === '' ? [] : [opts.prompt]),
+      ],
+    };
+  }
+
+  normalizeHook(e: HookEvent): AdapterEvent {
+    const sessionID = e.payload['session_id'];
+    const transcript = e.payload['transcript_path'];
+
+    const base: AdapterEvent = {
+      kind: 'heartbeat',
+      ...(typeof sessionID === 'string' ? { agentSessionID: sessionID } : {}),
+    };
+
+    const named: AdapterEvent = {
+      ...base,
+      ...(typeof transcript === 'string' ? { nameSource: transcript } : {}),
+    };
+
+    switch (e.event) {
+      case 'SessionStart': {
+        return { ...named, kind: 'started' };
+      }
+      case 'Notification': {
+        const message = e.payload['message'];
+
+        return {
+          ...base,
+          kind: 'needs-input',
+          ...(typeof message === 'string' && message !== ''
+            ? { message, detail: truncateDetail(message) }
+            : {}),
+        };
+      }
+      case 'Stop': {
+        const lastMessage = e.payload['last_assistant_message'];
+
+        return {
+          ...named,
+          kind: 'turn-done',
+          ...(typeof lastMessage === 'string' && lastMessage !== ''
+            ? { detail: truncateDetail(lastMessage) }
+            : {}),
+        };
+      }
+      case 'UserPromptSubmit': {
+        const prompt = e.payload['prompt'];
+        const preview = typeof prompt === 'string' ? prompt.slice(0, 80) : '';
+
+        return {
+          ...named,
+          kind: 'prompt-submitted',
+          ...(preview === '' ? {} : { message: preview, detail: truncateDetail(preview) }),
+        };
+      }
+      case 'SessionEnd': {
+        return { ...base, kind: 'ended' };
+      }
+      default: {
+        return base;
+      }
+    }
+  }
+
+  // Claude is the naming authority: /rename writes custom-title lines to the
+  // transcript, auto-summaries write summary lines. A custom title always
+  // wins; a summary never overrides a user-typed name.
+  async loadName(source: string, namedBy: 'user' | 'auto' | 'agent'): Promise<NameUpdate | null> {
+    try {
+      const proc = Bun.spawn(['grep', '-E', '"type":"(custom-title|summary)"', source], {
+        stdout: 'pipe',
+        stderr: 'ignore',
+      });
+
+      const text = await new Response(proc.stdout).text();
+
+      let title: string | undefined;
+      let summary: string | undefined;
+
+      for (const line of text.split('\n')) {
+        if (line.trim() === '') {
+          continue;
+        }
+
+        try {
+          const parsed: unknown = JSON.parse(line);
+
+          if (!isRecord(parsed)) {
+            continue;
+          }
+
+          const customTitle = parsed['customTitle'];
+          const summaryText = parsed['summary'];
+
+          if (parsed['type'] === 'custom-title' && typeof customTitle === 'string') {
+            title = customTitle;
+          }
+
+          if (parsed['type'] === 'summary' && typeof summaryText === 'string') {
+            summary = summaryText;
+          }
+        } catch {}
+      }
+
+      if (title !== undefined && title !== '') {
+        return { name: title, namedBy: 'agent' };
+      }
+
+      if (namedBy !== 'user' && summary !== undefined && summary !== '') {
+        return { name: summary };
+      }
+
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  // Shell command that re-opens this session outside atc (or anywhere).
+  buildResumeCommand(cwd: string, agentSessionID: string | undefined): string | null {
+    const resume =
+      agentSessionID === undefined ? 'claude --resume' : `claude --resume ${agentSessionID}`;
+
+    const quoted = cwd.replaceAll("'", String.raw`'\''`);
+
+    return `cd '${quoted}' && ${resume}`;
+  }
+}
+
+// Settings file injected into wrangled sessions via `claude --settings`.
+// The user's own settings are untouched; these hooks only exist in sessions
+// atc spawns, and identify themselves via ATC_SESSION_ID in the env.
+function writeHookSettings(): string {
+  const cmd = buildCLICommand('hook-report');
+  const entry = [{ hooks: [{ type: 'command', command: cmd, timeout: 5 }] }];
+
+  const settings = {
+    hooks: {
+      // SessionStart carries the session id at spawn/resume time, before any
+      // interaction — without it a session only enters the fleet file after
+      // its first prompt/notification.
+      SessionStart: entry,
+      Notification: entry,
+      Stop: entry,
+      UserPromptSubmit: entry,
+      SessionEnd: entry,
+    },
+  };
+
+  // Fleet status renders inside Claude Code's own status line; the injected
+  // command chains the user's configured statusline first, so mirror their
+  // padding.
+  let padding = 0;
+
+  try {
+    const settingsPath = join(homedir(), '.claude', 'settings.json');
+    const raw = readFileSync(settingsPath, 'utf8');
+    const user: unknown = JSON.parse(raw);
+    const statusLine = isRecord(user) ? user['statusLine'] : undefined;
+    const userPadding = isRecord(statusLine) ? statusLine['padding'] : undefined;
+
+    if (typeof userPadding === 'number') {
+      padding = userPadding;
+    }
+  } catch {}
+
+  const statusline = {
+    type: 'command',
+    command: buildCLICommand('statusline'),
+    padding,
+  };
+
+  const file = join(stateDir, 'hook-settings.json');
+
+  writeFileSync(file, JSON.stringify({ ...settings, statusLine: statusline }, null, 2));
+
+  return file;
+}
+
+function truncateDetail(text: string): string {
+  return text.length <= 600 ? text : `${text.slice(0, 599)}…`;
+}
+
+// Wrangled sessions invoke atc subcommands: under bun the CLI entry path is
+// part of the command; a compiled binary is itself the entry.
+function buildCLICommand(subcommand: string): string {
+  const exec = process.execPath;
+
+  if (basename(exec) === 'bun' || basename(exec) === 'bun.exe') {
+    return `"${exec}" "${join(import.meta.dir, 'cli.ts')}" ${subcommand}`;
+  }
+
+  return `"${exec}" ${subcommand}`;
+}