@zgeoff/atc 0.1.0 → 0.1.1

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,7 +37,7 @@ fine nested inside zellij/tmux (give the pane locked mode so Ctrl-Space reaches
 
 | Key             | Where          | Action                                                                                         |
 | --------------- | -------------- | ---------------------------------------------------------------------------------------------- |
-| `Ctrl-Space`    | anywhere       | toggle session overlay                                                                         |
+| leader          | anywhere       | toggle session overlay — `Ctrl-Space` by default, configurable (see Config)                    |
 | `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>`    |
@@ -63,17 +72,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) 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.1",
   "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/index.ts

@@ -1,5 +1,6 @@
 import { basename } from 'node:path';
 import { bootDaemonClient } from './boot-daemon';
+import { loadConfig } from './config';
 import { collectDirs, formatDir, pickMatches } from './dirs';
 import type { EventMsg } from './protocol';
 import { isRecord } from './report';
@@ -76,6 +77,7 @@ function scheduleStatus() {
         counts: countSessionStates(fleet),
         focusedName: focused === null ? null : focused.name,
         urgentName: urgent === undefined ? null : urgent.name,
+        leaderLabel: leader.label,
       });
     }
   }, 50);
@@ -127,7 +129,7 @@ function toBase() {
   } else {
     mode = 'home';
 
-    drawHome(fleetCount);
+    drawHome(fleetCount, leader.label);
   }
 
   scheduleStatus();
@@ -180,7 +182,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();
   }
 }
@@ -524,8 +526,9 @@ function copyToClipboard(text: string) {
 
 // ---- input ----
 
+const leader = loadConfig().leader;
+
 const KEY = {
-  ctrlSpace: 0x00,
   ctrlC: 0x03,
   ctrlU: 0x15,
   esc: 0x1b,
@@ -578,7 +581,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 +639,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;
@@ -778,7 +781,7 @@ function applyTextKey(buf: Buffer, onSubmit: () => void, onCancel: () => void) {
     return;
   }
 
-  if (buf[0] === KEY.ctrlSpace) {
+  if (buf[0] === leader.code) {
     toBase();
 
     return;
@@ -877,7 +880,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 +896,7 @@ process.stdin.on('data', (buf: Buffer) => {
       return;
     }
     case 'home': {
-      if (buf[0] === KEY.ctrlSpace) {
+      if (buf[0] === leader.code) {
         openOverlay();
 
         return;
@@ -1037,7 +1040,7 @@ stdout.on('resize', () => {
   }
 
   if (mode === 'home') {
-    drawHome(fleetCount);
+    drawHome(fleetCount, leader.label);
   }
 
   if (mode === 'overlay') {
@@ -1072,5 +1075,5 @@ process.on('SIGHUP', () => quit());
 // ---- start ----
 stdout.write(ansi.altScreenOn);
 
-drawHome(fleetCount);
+drawHome(fleetCount, leader.label);
 scheduleStatus();

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);
@@ -317,7 +318,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 +327,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',
   ];