@zgeoff/atc 0.1.10 → 0.1.11

package/README.md

@@ -27,10 +27,11 @@ atc
 ```
 
 Needs [Bun](https://bun.sh) (atc runs from source through it) and the `claude` CLI on your PATH.
-Grok sessions also need the `grok` CLI. From a checkout, `bun src/cli.ts` runs the same thing. atc
-is built to pair with [zoxide](https://github.com/ajeetdsouza/zoxide): the spawn directory picker
-feeds on its frecency list, so with zoxide installed every directory you visit is two keystrokes
-from a session. Without it the picker falls back to atc's own spawn history.
+Grok sessions also need the `grok` CLI, and Codex sessions the `codex` CLI. From a checkout,
+`bun src/cli.ts` runs the same thing. atc is built to pair with
+[zoxide](https://github.com/ajeetdsouza/zoxide): the spawn directory picker feeds on its frecency
+list, so with zoxide installed every directory you visit is two keystrokes from a session. Without
+it the picker falls back to atc's own spawn history.
 
 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
@@ -42,7 +43,7 @@ fine nested inside zellij/tmux (give the pane locked mode so Ctrl-Space reaches
 | --------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | leader          | anywhere       | toggle session overlay — `Ctrl-Space` by default, configurable (see Config)                                                                                             |
 | `n`             | home/overlay   | spawn: pick agent → dir (zoxide + history, fuzzy) → name → optional first prompt. Fresh clients default to Claude; last-used is the last deliberate-spawn SessionStart. |
-| `r`             | home/overlay   | adopt: pick agent → dir → name. Claude opens `claude --resume`. Grok opens plain `grok`.                                                                                |
+| `r`             | home/overlay   | adopt: pick agent → dir → name. Claude opens `claude --resume`, Codex `codex resume`. Grok opens plain `grok`.                                                          |
 | `R`             | home           | restore last fleet after a daemon death — each session with its matching CLI                                                                                            |
 | `j`/`k`/`↑`/`↓` | overlay/picker | move                                                                                                                                                                    |
 | `Enter`         | overlay        | attach (auto-acks)                                                                                                                                                      |
@@ -53,7 +54,7 @@ fine nested inside zellij/tmux (give the pane locked mode so Ctrl-Space reaches
 | `g`             | overlay        | toggle the grouped view: sessions cluster under repository headers                                                                                                      |
 | `H`             | overlay        | eject to headless (Claude only). Hidden and ignored on a Grok row.                                                                                                      |
 | `P`             | overlay        | revive: a fresh terminal resumes a headless or killed session in place                                                                                                  |
-| `y`             | overlay        | yank the resume command (`claude --resume <id>` or `grok --resume <id>`)                                                                                                |
+| `y`             | overlay        | yank the resume command (`claude --resume <id>`, `grok --resume <id>`, or `codex resume <id>`)                                                                          |
 | `Y`             | overlay        | eject: yank the resume command, then kill the session here                                                                                                              |
 | `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                                                                                     |
@@ -91,6 +92,17 @@ mkdir -p ~/.grok/hooks
 atc grok-hooks > ~/.grok/hooks/atc-reporter.json
 ```
 
+Codex attention comes from hook entries in `$CODEX_HOME/hooks.json` (`~/.codex` when `CODEX_HOME` is
+unset). atc never writes that path either — `atc codex-hooks` prints the entries to merge in:
+
+```sh
+atc codex-hooks
+```
+
+Codex parses new hooks but never runs them until you trust them once: open `codex`, review the atc
+hooks in its hooks list, and approve them. Sessions you start outside atc report events too; the
+reporter exits immediately when no atc session id is present.
+
 `atc grok-hooks` prints this file, with the `hook-report` command resolved for this install:
 
 ```json
@@ -133,6 +145,8 @@ session.
   "claudeArgs": [],
   "grokBin": "grok",
   "grokArgs": [],
+  "codexBin": "codex",
+  "codexArgs": [],
   "leader": "ctrl-space"
 }
 ```
@@ -143,6 +157,8 @@ session.
 | `claudeArgs` | `[]`           | Prepended to every Claude spawn, e.g. `["--model", "opus"]`.                                                |
 | `grokBin`    | `"grok"`       | The binary spawned for Grok sessions.                                                                       |
 | `grokArgs`   | `[]`           | Prepended to every Grok spawn. A user `--leader` in this list is dropped; atc always appends `--no-leader`. |
+| `codexBin`   | `"codex"`      | The binary spawned for Codex sessions.                                                                      |
+| `codexArgs`  | `[]`           | Prepended to every Codex spawn.                                                                             |
 | `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
@@ -150,8 +166,8 @@ Pick a different leader when `Ctrl-Space` is taken on your machine — Raycast o
 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. `atc_session_spawn` takes an optional `agent` (`claude` or `grok`) and defaults
-to Claude; it never reads the TUI last-used value.
+sessions included. `atc_session_spawn` takes an optional `agent` (`claude`, `grok`, or `codex`) and
+defaults to Claude; it never reads the TUI last-used value.
 
 ```sh
 claude mcp add --scope user atc -- atc mcp

package/package.json

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

package/src/agent-adapter.ts

@@ -1,13 +1,13 @@
 import type { HookEvent } from './hooks';
 
-export type AgentKind = 'claude' | 'grok';
+export type AgentKind = 'claude' | 'grok' | 'codex';
 
 /**
  * Missing, empty, and unknown values become Claude so a fleet written
  * before the agent column still restores as Claude.
  */
 export function toAgentKind(raw: unknown): AgentKind {
-  return raw === 'grok' ? 'grok' : 'claude';
+  return raw === 'grok' || raw === 'codex' ? raw : 'claude';
 }
 
 export interface SpawnOptions {

package/src/cli.ts

@@ -46,6 +46,7 @@ const main = defineCommand({
           const config = await import('./config');
           const claude = await import('./claude-adapter');
           const grok = await import('./grok-adapter');
+          const codex = await import('./codex-adapter');
           const headless = await import('./start-headless-run');
 
           // Test harnesses shrink the outbound queue to force overflow
@@ -66,13 +67,14 @@ const main = defineCommand({
           );
 
           const grokAdapter = new grok.GrokAdapter(cfg);
+          const codexAdapter = new codex.CodexAdapter(cfg);
 
           const handle = daemon.startDaemon({
             socketPath: config.daemonSocketPath,
             reporterSocketPath: config.socketPath,
             build: getBuild(),
             adapter: claudeAdapter,
-            adapters: { claude: claudeAdapter, grok: grokAdapter },
+            adapters: { claude: claudeAdapter, grok: grokAdapter, codex: codexAdapter },
             dbPath: config.dbFile,
             legacyFleetPath: config.legacyFleetFile,
             pidPath: config.daemonPidFile,
@@ -87,6 +89,19 @@ const main = defineCommand({
           });
         },
       }),
+    'codex-hooks': () =>
+      defineCommand({
+        meta: {
+          name: 'codex-hooks',
+          description:
+            'Print the Codex hook entries to merge into $CODEX_HOME/hooks.json (trust them once in the Codex TUI)',
+        },
+        async run() {
+          const hook = await import('./print-codex-hook-file');
+
+          hook.printCodexHookFile();
+        },
+      }),
     'grok-hooks': () =>
       defineCommand({
         meta: {

package/src/codex-adapter.ts

@@ -0,0 +1,178 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type {
+  AdapterEvent,
+  AgentAdapter,
+  NameUpdate,
+  ResumeCheck,
+  SpawnOptions,
+  SpawnPlan,
+} from './agent-adapter';
+import type { Config } from './config';
+import type { HookEvent } from './hooks';
+import { isRecord } from './report';
+
+/**
+ * The Codex CLI adapter: spawn arguments, hook payload mapping, resume
+ * semantics, and session_index.jsonl name-pulling. Hooks are a user-installed
+ * entry in the Codex hook config (`atc codex-hooks` prints it) that the user
+ * trusts once in the Codex TUI; atc never writes into the user's Codex config.
+ */
+export class CodexAdapter implements AgentAdapter {
+  readonly kind = 'codex';
+
+  // Codex has no headless handoff.
+  readonly headlessRunner = null;
+
+  // Codex's hooks are authoritative; no screen heuristics needed.
+  readonly screenDetector = null;
+
+  private readonly config: Config;
+
+  constructor(config: Config) {
+    this.config = config;
+  }
+
+  planSpawn(opts: SpawnOptions): SpawnPlan {
+    return {
+      bin: this.config.codexBin,
+      args: [
+        ...this.config.codexArgs,
+
+        // Bare resume opens Codex's own session picker; an id resumes that
+        // session directly. Both accept a prompt afterwards.
+        ...(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 sessionID === 'string' ? { nameSource: sessionID } : {}),
+      ...(typeof transcript === 'string' ? { transcriptSource: transcript } : {}),
+    };
+
+    switch (e.event) {
+      case 'SessionStart': {
+        return { ...named, kind: 'started' };
+      }
+      case 'PermissionRequest': {
+        const toolName = e.payload['tool_name'];
+
+        const message =
+          typeof toolName === 'string' && toolName !== ''
+            ? `waiting for approval: ${toolName}`
+            : 'waiting for approval';
+
+        return { ...base, kind: 'needs-input', message, detail: message };
+      }
+      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 'Stop': {
+        const lastMessage = e.payload['last_assistant_message'];
+
+        return {
+          ...named,
+          kind: 'turn-done',
+          ...(typeof lastMessage === 'string' && lastMessage !== ''
+            ? { detail: truncateDetail(lastMessage) }
+            : {}),
+        };
+      }
+      case 'SessionEnd': {
+        return { ...base, kind: 'ended' };
+      }
+      default: {
+        return base;
+      }
+    }
+  }
+
+  // Codex records session titles in session_index.jsonl; the index does not
+  // say whether a title was set by /rename or auto-generated, so a title
+  // never overrides a user-typed name.
+  loadName(source: string, namedBy: 'user' | 'auto' | 'agent'): Promise<NameUpdate | null> {
+    if (namedBy === 'user') {
+      return Promise.resolve(null);
+    }
+
+    const index = join(resolveCodexHome(), 'session_index.jsonl');
+    let text: string;
+
+    try {
+      text = readFileSync(index, 'utf8');
+    } catch {
+      return Promise.resolve(null);
+    }
+
+    let name: string | undefined;
+
+    for (const line of text.split('\n')) {
+      if (line.trim() === '' || !line.includes(source)) {
+        continue;
+      }
+
+      try {
+        const parsed: unknown = JSON.parse(line);
+
+        if (
+          isRecord(parsed) &&
+          parsed['id'] === source &&
+          typeof parsed['thread_name'] === 'string'
+        ) {
+          name = parsed['thread_name'];
+        }
+      } catch {}
+    }
+
+    const update = name === undefined || name === '' ? null : { name };
+
+    return Promise.resolve(update);
+  }
+
+  canResume(session: ResumeCheck): boolean {
+    if (session.transcriptSource === undefined) {
+      return true;
+    }
+
+    return existsSync(session.transcriptSource);
+  }
+
+  // Shell command that re-opens this session outside atc (or anywhere).
+  buildResumeCommand(cwd: string, agentSessionID: string | undefined): string | null {
+    const resume = agentSessionID === undefined ? 'codex resume' : `codex resume ${agentSessionID}`;
+    const quoted = cwd.replaceAll("'", String.raw`'\''`);
+
+    return `cd '${quoted}' && ${resume}`;
+  }
+}
+
+function resolveCodexHome(): string {
+  const home = process.env['CODEX_HOME'];
+
+  return home !== undefined && home !== '' ? home : join(homedir(), '.codex');
+}
+
+function truncateDetail(text: string): string {
+  return text.length <= 600 ? text : `${text.slice(0, 599)}…`;
+}

package/src/collect-clean-env.ts

@@ -42,5 +42,10 @@ const GROK_PARENT_KEYS = new Set([
 ]);
 
 function isParentSessionKey(key: string): boolean {
-  return key === 'CLAUDECODE' || key.startsWith('CLAUDE_CODE_') || GROK_PARENT_KEYS.has(key);
+  return (
+    key === 'CLAUDECODE' ||
+    key.startsWith('CLAUDE_CODE_') ||
+    key.startsWith('CODEX_SANDBOX') ||
+    GROK_PARENT_KEYS.has(key)
+  );
 }

package/src/config.ts

@@ -8,6 +8,8 @@ export interface Config {
   claudeArgs: string[];
   grokBin: string;
   grokArgs: string[];
+  codexBin: string;
+  codexArgs: string[];
   leader: LeaderKey;
 }
 
@@ -21,6 +23,8 @@ const DEFAULTS: Config = {
   claudeArgs: [],
   grokBin: 'grok',
   grokArgs: [],
+  codexBin: 'codex',
+  codexArgs: [],
   leader: { code: 0, label: '^Space' },
 };
 
@@ -67,11 +71,18 @@ export function loadConfig(): Config {
       ? parsed['grokArgs'].filter((a): a is string => typeof a === 'string')
       : DEFAULTS.grokArgs;
 
+    const codexBin =
+      typeof parsed['codexBin'] === 'string' ? parsed['codexBin'] : DEFAULTS.codexBin;
+
+    const codexArgs = Array.isArray(parsed['codexArgs'])
+      ? parsed['codexArgs'].filter((a): a is string => typeof a === 'string')
+      : DEFAULTS.codexArgs;
+
     const leader =
       (typeof parsed['leader'] === 'string' ? decodeLeader(parsed['leader']) : null) ??
       DEFAULTS.leader;
 
-    return { claudeBin, claudeArgs, grokBin, grokArgs, leader };
+    return { claudeBin, claudeArgs, grokBin, grokArgs, codexBin, codexArgs, leader };
   } catch {
     return { ...DEFAULTS };
   }

package/src/daemon-connection.ts

@@ -375,13 +375,18 @@ export class DaemonConnection {
 
     const rawAgent = req.p?.['agent'];
 
-    if (rawAgent !== undefined && rawAgent !== 'claude' && rawAgent !== 'grok') {
-      this.sendErr(req.id, 'bad_args', "session.spawn agent must be 'claude' or 'grok'");
+    if (
+      rawAgent !== undefined &&
+      rawAgent !== 'claude' &&
+      rawAgent !== 'grok' &&
+      rawAgent !== 'codex'
+    ) {
+      this.sendErr(req.id, 'bad_args', "session.spawn agent must be 'claude', 'grok', or 'codex'");
 
       return;
     }
 
-    const agent: AgentKind = rawAgent === 'grok' ? 'grok' : 'claude';
+    const agent: AgentKind = rawAgent === 'grok' || rawAgent === 'codex' ? rawAgent : 'claude';
 
     if (this.ctx.findAdapter(agent) === null) {
       this.sendErr(req.id, 'unsupported', `no adapter for agent '${agent}'`);

package/src/format-overlay-agent-mark.ts

@@ -5,5 +5,13 @@ import type { AgentKind } from './agent-adapter';
  * Claude, so session names stay aligned across a mixed fleet.
  */
 export function formatOverlayAgentMark(agent: AgentKind): string {
-  return agent === 'grok' ? 'g' : ' ';
+  if (agent === 'grok') {
+    return 'g';
+  }
+
+  if (agent === 'codex') {
+    return 'x';
+  }
+
+  return ' ';
 }

package/src/index.ts

@@ -10,7 +10,7 @@ import { countSessionStates, sortGroupedSessionViews, sortSessionViews } from '.
 import type { SessionState } from './sessions';
 import { ansi, cols, drawHelp, drawHome, drawOverlay, drawPicker, drawStatusBar, rows } from './ui';
 
-type AgentKind = 'claude' | 'grok';
+type AgentKind = 'claude' | 'grok' | 'codex';
 
 type Mode =
   | 'home'
@@ -26,6 +26,7 @@ type Mode =
 const AGENT_PICKS = [
   { agent: 'claude' as const, label: 'Claude' },
   { agent: 'grok' as const, label: 'Grok' },
+  { agent: 'codex' as const, label: 'Codex' },
 ];
 
 interface MirrorSession {
@@ -320,7 +321,12 @@ function openAgentPicker(resume = false) {
   spawnResume = resume;
   spawnAgent = lastUsedAgent;
   pickerInput = '';
-  pickerSelected = lastUsedAgent === 'grok' ? 1 : 0;
+
+  pickerSelected = Math.max(
+    0,
+    AGENT_PICKS.findIndex((p) => p.agent === lastUsedAgent),
+  );
+
   mode = 'picker-agent';
 
   stdout.write(ansi.clear);
@@ -442,7 +448,7 @@ function toMirrorSession(value: unknown): MirrorSession | null {
     kind: value['kind'] === 'headless' ? 'headless' : 'pty',
     alive: value['alive'],
     resumable: typeof value['agentSessionID'] === 'string',
-    agent: value['agent'] === 'grok' ? 'grok' : 'claude',
+    agent: value['agent'] === 'grok' || value['agent'] === 'codex' ? value['agent'] : 'claude',
   };
 }
 
@@ -541,7 +547,7 @@ function applyDaemonEvent(e: EventMsg) {
           s.lastMsg = e['lastMsg'];
         }
 
-        if (e['agent'] === 'grok' || e['agent'] === 'claude') {
+        if (e['agent'] === 'grok' || e['agent'] === 'codex' || e['agent'] === 'claude') {
           s.agent = e['agent'];
         }
 
@@ -814,7 +820,13 @@ function applyOverlayKey(buf: Buffer) {
     return;
   }
 
-  if (ch === 'H' && sel !== undefined && sel.kind === 'pty' && sel.alive && sel.agent !== 'grok') {
+  if (
+    ch === 'H' &&
+    sel !== undefined &&
+    sel.kind === 'pty' &&
+    sel.alive &&
+    sel.agent === 'claude'
+  ) {
     ejectTarget = sel.id;
     pickerInput = '';
     mode = 'picker-eject';
@@ -1149,7 +1161,12 @@ process.stdin.on('data', (buf: Buffer) => {
         },
         () => {
           pickerInput = '';
-          pickerSelected = spawnAgent === 'grok' ? 1 : 0;
+
+          pickerSelected = Math.max(
+            0,
+            AGENT_PICKS.findIndex((p) => p.agent === spawnAgent),
+          );
+
           mode = 'picker-agent';
 
           stdout.write(ansi.clear);

package/src/mcp-server.ts

@@ -43,7 +43,7 @@ const TOOLS: readonly MCPTool[] = [
   {
     name: 'atc_session_spawn',
     description:
-      'Spawn a new session in a directory. Optional agent is claude or grok; omitted agent is always Claude, never the TUI last-used value. Returns the new session descriptor. Give it a prompt to start it working immediately.',
+      'Spawn a new session in a directory. Optional agent is claude, grok, or codex; omitted agent is always Claude, never the TUI last-used value. Returns the new session descriptor. Give it a prompt to start it working immediately.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -52,7 +52,7 @@ const TOOLS: readonly MCPTool[] = [
         prompt: { type: 'string', description: 'First message for the session' },
         agent: {
           type: 'string',
-          enum: ['claude', 'grok'],
+          enum: ['claude', 'grok', 'codex'],
           description: 'Which agent CLI to spawn; defaults to claude',
         },
       },
@@ -243,15 +243,22 @@ async function runTool(
     case 'atc_session_spawn': {
       const rawAgent = args['agent'];
 
-      if (rawAgent !== undefined && rawAgent !== 'claude' && rawAgent !== 'grok') {
-        throw new Error("agent must be 'claude' or 'grok'");
+      if (
+        rawAgent !== undefined &&
+        rawAgent !== 'claude' &&
+        rawAgent !== 'grok' &&
+        rawAgent !== 'codex'
+      ) {
+        throw new Error("agent must be 'claude', 'grok', or 'codex'");
       }
 
       const ok = await client.sendRequest('session.spawn', {
         cwd: args['cwd'],
         ...(typeof args['name'] === 'string' ? { name: args['name'] } : {}),
         ...(typeof args['prompt'] === 'string' ? { prompt: args['prompt'] } : {}),
-        ...(rawAgent === 'claude' || rawAgent === 'grok' ? { agent: rawAgent } : {}),
+        ...(rawAgent === 'claude' || rawAgent === 'grok' || rawAgent === 'codex'
+          ? { agent: rawAgent }
+          : {}),
         cols: 100,
         rows: 30,
       });

package/src/print-codex-hook-file.ts

@@ -0,0 +1,26 @@
+import { buildCLICommand } from './build-cli-command';
+
+const CODEX_HOOK_EVENTS = [
+  'SessionStart',
+  'UserPromptSubmit',
+  'PermissionRequest',
+  'Stop',
+] as const;
+
+/**
+ * Print the Codex hook entries to stdout. The operator merges them into
+ * `$CODEX_HOME/hooks.json` and trusts them once in the Codex TUI — Codex
+ * parses untrusted hooks but never runs them. atc never writes that path.
+ */
+export function printCodexHookFile(): void {
+  process.stdout.write(buildCodexHookFile());
+}
+
+function buildCodexHookFile(): string {
+  const cmd = buildCLICommand('hook-report');
+  const buildEntry = (timeout: number) => [{ hooks: [{ type: 'command', command: cmd, timeout }] }];
+  const hooks = Object.fromEntries(CODEX_HOOK_EVENTS.map((event) => [event, buildEntry(5)]));
+
+  // Codex caps SessionEnd hooks at three seconds.
+  return `${JSON.stringify({ hooks: { ...hooks, SessionEnd: buildEntry(3) } }, null, 2)}\n`;
+}

package/src/ui.ts

@@ -269,7 +269,7 @@ export function buildOverlayHint(s: OverlaySessionView | undefined): string {
       actions.push('a ack');
     }
 
-    if (s.agent !== 'grok') {
+    if (s.agent === 'claude') {
       actions.push('H headless');
     }