@zgeoff/atc 2.2.1 → 2.3.1

package/README.md

@@ -27,12 +27,30 @@ that needs an answer turns red, and `Tab` takes you to it. Quit atc and the sess
 
 ## Install
 
+Homebrew:
+
+```sh
+brew install zgeoff/tap/atc
+```
+
+Or download a binary:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/zgeoff/atc/main/install.sh | sh
+```
+
+Prebuilt binaries cover macOS and Linux, arm64 and x64. The install script puts `atc` in
+`~/.local/bin`; set `ATC_INSTALL_DIR` to change that. Checksums are on the
+[releases page](https://github.com/zgeoff/atc/releases).
+
+From source, with [Bun](https://bun.sh):
+
 ```sh
 bun add -g @zgeoff/atc
 ```
 
-atc needs [Bun](https://bun.sh) and at least one of the `claude`, `grok`, or `codex` CLIs on your
-PATH. The agent picker lists the ones it finds.
+atc needs at least one of the `claude`, `grok`, or `codex` CLIs on your PATH. The agent picker lists
+the ones it finds.
 
 ## Use
 
@@ -67,9 +85,11 @@ Sessions that need you sort to the top, so the one you want is nearly always fir
 | `q`          | quit the client; sessions keep running       |
 | `?`          | every other key                              |
 
-The directory picker reads your [zoxide](https://github.com/ajeetdsouza/zoxide) list when zoxide is
-installed, and atc's own spawn history otherwise. Inside a Claude session your statusline gains a
-fleet segment, so `● 2 need you: auth-bug` is visible without opening the list.
+The directory picker lists the directory you ran `atc` from, atc's own spawn history, every project
+under the roots in `config.json`, and your [zoxide](https://github.com/ajeetdsouza/zoxide) list when
+zoxide is installed. A typed path such as `~/pro` completes like a shell. Inside a Claude session
+your statusline gains a fleet segment, so `● 2 need you: auth-bug` is visible without opening the
+list.
 
 If the daemon dies, press `R` on the home screen and every session respawns from its transcript.
 After you upgrade atc, the status bar shows `⟳ update ready`, and `u` restarts the daemon and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",
@@ -21,11 +21,13 @@
   "scripts": {
     "start": "bun src/cli.ts",
     "build:agents": "bash scripts/build-agents-md.sh agents/shared.md agents/project.md AGENTS.md",
+    "build:binaries": "bash scripts/build-binaries.sh",
     "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",
+    "test:binary": "bun test --timeout 20000 test/daemon-e2e.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "format": "oxfmt . && format-codemod --quiet .",
     "format:check": "oxfmt --check . && format-codemod --check --quiet .",
@@ -61,6 +63,8 @@
   },
   "overrides": {
     "fast-uri": "3.1.6",
+    "hono": ">=4.13.5",
+    "js-yaml": ">=4.3.2 <5",
     "qs": "6.16.0"
   },
   "packageManager": "bun@1.3.10"

package/src/agents/build-cli-command.ts

@@ -1,4 +1,5 @@
-import { basename, join } from 'node:path';
+import { join } from 'node:path';
+import { isCompiledBinary } from '../shared/is-compiled-binary';
 
 /**
  * Command line that wrangled sessions invoke for atc subcommands: under bun
@@ -8,9 +9,9 @@ import { basename, join } from 'node:path';
 export 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}`;
+  if (isCompiledBinary()) {
+    return `"${exec}" ${subcommand}`;
   }
 
-  return `"${exec}" ${subcommand}`;
+  return `"${exec}" "${join(import.meta.dir, '..', 'cli.ts')}" ${subcommand}`;
 }

package/src/agents/build-hook-settings.ts

@@ -1,15 +1,19 @@
+import { z } from 'zod';
 import type { AgentID } from './agent-adapter';
 import { buildCLICommand } from './build-cli-command';
 
 /**
  * What one agent id needs on top of the shared instrumentation. The
  * environment block and the credential helper point the CLI at a backend
- * other than the default one; both are absent for the stock agent.
+ * other than the default one; both are absent for the stock agent. The
+ * settings are whatever else the config asked this agent's sessions to start
+ * with.
  */
 export interface HookSettingsProfile {
   readonly id: AgentID;
   readonly env?: Readonly<Record<string, string>>;
   readonly apiKeyHelper?: string;
+  readonly settings?: Readonly<Record<string, unknown>>;
 }
 
 /**
@@ -31,17 +35,20 @@ export function buildHookSettings(
     { hooks: [{ type: 'command', command: buildCLICommand('hook-report'), timeout: 5 }] },
   ];
 
-  return {
-    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,
-    },
+  const own = {
+    hooks: mergeSessionHooks(
+      {
+        // 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,
+      },
+      profile.settings?.['hooks'],
+    ),
 
     // Fleet status renders inside Claude Code's own status line; the injected
     // command chains the user's configured statusline first, so mirror their
@@ -56,4 +63,36 @@ export function buildHookSettings(
       : { env: profile.env }),
     ...(profile.apiKeyHelper === undefined ? {} : { apiKeyHelper: profile.apiKeyHelper }),
   };
+
+  // The configured settings fill in around what atc writes and never replace
+  // it: a session atc did not instrument is a session the fleet cannot track.
+  return { ...profile.settings, ...own };
+}
+
+type SessionHooks = Readonly<Record<string, readonly unknown[]>>;
+
+// One hook list per event name, which is the shape every harness that reads
+// this file takes.
+const CONFIGURED_HOOKS_SCHEMA = z.record(z.string(), z.array(z.unknown()));
+
+/**
+ * atc's own reporter plus whatever the config added, per event. The reporter
+ * runs first and the configured entries follow it, so an added hook joins the
+ * fleet's rather than displacing it. A block that is not hook lists is left out
+ * whole, and costs its own entries rather than atc's.
+ */
+function mergeSessionHooks(own: SessionHooks, configured: unknown): SessionHooks {
+  const parsed = CONFIGURED_HOOKS_SCHEMA.safeParse(configured);
+
+  if (!parsed.success) {
+    return own;
+  }
+
+  const merged: Record<string, readonly unknown[]> = { ...own };
+
+  for (const [event, entries] of Object.entries(parsed.data)) {
+    merged[event] = [...(merged[event] ?? []), ...entries];
+  }
+
+  return merged;
 }

package/src/agents/gateway-adapter.ts

@@ -99,6 +99,7 @@ export class GatewayAdapter implements AgentAdapter {
       ...(this.gateway.apiKeyHelper === undefined
         ? {}
         : { apiKeyHelper: this.gateway.apiKeyHelper }),
+      ...(this.gateway.settings === undefined ? {} : { settings: this.gateway.settings }),
     });
 
     return this.settingsFile;

package/src/cli.ts

@@ -64,7 +64,7 @@ const main = defineCommand({
             Number.isFinite(capOverride) && capOverride >= 0 ? capOverride : 15_000;
 
           const claudeAdapter = new claude.ClaudeAdapter(cfg, (runOpts, hooks) =>
-            headless.startHeadlessRun(runOpts, hooks),
+            headless.startHeadlessRun({ ...runOpts, claudeBin: cfg.claudeBin }, hooks),
           );
 
           const grokAdapter = new grok.GrokAdapter(cfg);
@@ -73,7 +73,7 @@ const main = defineCommand({
           const gatewayAdapters = cfg.gateways.map(
             (entry) =>
               new gateway.GatewayAdapter(entry, cfg, (runOpts, hooks) =>
-                headless.startHeadlessRun(runOpts, hooks),
+                headless.startHeadlessRun({ ...runOpts, claudeBin: entry.bin }, hooks),
               ),
           );
 

package/src/client/boot-daemon.ts

@@ -1,10 +1,11 @@
 import { spawn as spawnChild } from 'node:child_process';
 import { readFileSync } from 'node:fs';
-import { basename, join } from 'node:path';
+import { join } from 'node:path';
 import { toAgentID } from '../agents/agent-adapter';
 import type { AgentID } from '../agents/agent-adapter';
 import { daemonPidFile, daemonSocketPath } from '../shared/config';
 import { getBuild } from '../shared/get-build';
+import { isCompiledBinary } from '../shared/is-compiled-binary';
 import { isRecord } from '../shared/report';
 import { DaemonClient } from './daemon-client';
 
@@ -119,9 +120,7 @@ async function stopStaleDaemon(): Promise<void> {
 }
 
 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'];
+  const args = isCompiledBinary() ? ['daemon'] : [join(import.meta.dir, '..', 'cli.ts'), 'daemon'];
 
-  spawnChild(exec, args, { detached: true, stdio: 'ignore' }).unref();
+  spawnChild(process.execPath, args, { detached: true, stdio: 'ignore' }).unref();
 }

package/src/client/collect-path-completions.ts

@@ -0,0 +1,59 @@
+import { readdirSync, statSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { resolvePathInput } from './resolve-path-input';
+
+/**
+ * Shell-style completion of a typed path: the child directories of the
+ * typed parent whose names start with the last segment, and the typed
+ * directory itself first when it exists, so Enter takes it. A trailing
+ * slash lists every child. Hidden directories show only when the segment
+ * starts with a dot. Input that is not a path completes to nothing.
+ */
+export function collectPathCompletions(input: string, cwd: string, home: string): string[] {
+  const target = resolvePathInput(input, cwd, home);
+
+  if (target === null) {
+    return [];
+  }
+
+  const listsChildren = input.endsWith('/') || input === '~' || input === '.' || input === '..';
+  const parent = listsChildren ? target : dirname(target);
+  const partial = listsChildren ? '' : basename(target);
+
+  const children = collectChildDirs(parent).filter((child) => {
+    const name = basename(child);
+
+    return (
+      name.toLowerCase().startsWith(partial.toLowerCase()) &&
+      (partial.startsWith('.') || !name.startsWith('.'))
+    );
+  });
+
+  if (listsChildren && isDirectory(target)) {
+    return [target, ...children.filter((child) => child !== target)];
+  }
+
+  return [
+    ...children.filter((child) => child === target),
+    ...children.filter((child) => child !== target),
+  ];
+}
+
+function collectChildDirs(dir: string): string[] {
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => join(dir, entry.name))
+      .toSorted();
+  } catch {
+    return [];
+  }
+}
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/src/client/collect-root-dirs.ts

@@ -0,0 +1,32 @@
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * The directories one level under each configured root, plus every
+ * worktree under those: `~/projects/atc` and `~/projects/atc/.worktrees/fix`
+ * both list for a root of `~/projects`. Hidden directories are skipped, a
+ * root that cannot be read contributes nothing, and the result is sorted
+ * per root so the list is stable between opens.
+ */
+export function collectRootDirs(roots: readonly string[]): string[] {
+  const found: string[] = [];
+
+  for (const root of roots) {
+    for (const child of collectChildDirs(root)) {
+      found.push(child, ...collectChildDirs(join(child, '.worktrees')));
+    }
+  }
+
+  return found;
+}
+
+function collectChildDirs(dir: string): string[] {
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+      .map((entry) => join(dir, entry.name))
+      .toSorted();
+  } catch {
+    return [];
+  }
+}

package/src/client/collect-zoxide-dirs.ts

@@ -0,0 +1,15 @@
+/**
+ * zoxide's frecency list, most visited first. An absent zoxide or a failed
+ * query contributes nothing, so the picker never depends on it.
+ */
+export async function collectZoxideDirs(): Promise<string[]> {
+  try {
+    const proc = Bun.spawn(['zoxide', 'query', '-l'], { stdout: 'pipe', stderr: 'ignore' });
+
+    const text = await new Response(proc.stdout).text();
+
+    return text.split('\n').filter((line) => line !== '');
+  } catch {
+    return [];
+  }
+}

package/src/client/dirs.ts

@@ -1,25 +1,33 @@
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename } from 'node:path';
+import { collectRootDirs } from './collect-root-dirs';
 
-// Spawn-history first (most recently used, reported by the daemon), then
-// zoxide's frecency list.
-export async function collectDirs(recent: readonly string[]): Promise<string[]> {
-  let zoxide: string[] = [];
-
-  try {
-    const proc = Bun.spawn(['zoxide', 'query', '-l'], { stdout: 'pipe', stderr: 'ignore' });
-
-    const text = await new Response(proc.stdout).text();
-
-    zoxide = text.split('\n').filter((line) => line !== '');
-  } catch {}
+/**
+ * Every source the picker lists, merged in the order the reader expects
+ * to find a directory: where the client runs, then the daemon's spawn
+ * history (most recent first), then the configured roots, then zoxide's
+ * frecency list. A path that no longer exists is dropped, a duplicate keeps
+ * its first position, and an empty merge falls back to the home directory.
+ */
+export interface DirSources {
+  readonly cwd: string;
+  readonly recent: readonly string[];
+  readonly roots: readonly string[];
+  readonly zoxide: readonly string[];
+}
 
+export function collectDirs(sources: DirSources): string[] {
   const seen = new Set<string>();
 
   const found: string[] = [];
 
-  for (const d of [...recent, ...zoxide]) {
+  for (const d of [
+    sources.cwd,
+    ...sources.recent,
+    ...collectRootDirs(sources.roots),
+    ...sources.zoxide,
+  ]) {
     if (!seen.has(d) && existsSync(d)) {
       seen.add(d);
       found.push(d);

package/src/client/resolve-path-input.ts

@@ -0,0 +1,23 @@
+import { resolve } from 'node:path';
+
+/**
+ * Where the picker looks a typed path up: `~` and `~/…` under the home
+ * directory, `.`, `..`, and `./…` under the client's working directory, and
+ * an absolute path as written. Anything else is a filter over the known
+ * list, not a path, and resolves to null.
+ */
+export function resolvePathInput(input: string, cwd: string, home: string): string | null {
+  if (input === '~' || input.startsWith('~/')) {
+    return resolve(home, input.slice(2));
+  }
+
+  if (input.startsWith('/') || isRelativePathInput(input)) {
+    return resolve(cwd, input);
+  }
+
+  return null;
+}
+
+function isRelativePathInput(input: string): boolean {
+  return input === '.' || input === '..' || input.startsWith('./') || input.startsWith('../');
+}

package/src/client/spawn-picker.ts

@@ -1,9 +1,13 @@
+import { homedir } from 'node:os';
 import type { AgentID } from '../agents/agent-adapter';
 import { loadConfig } from '../shared/config';
 import { collectAgentPicks } from './collect-agent-picks';
 import type { AgentPick } from './collect-agent-picks';
+import { collectPathCompletions } from './collect-path-completions';
+import { collectZoxideDirs } from './collect-zoxide-dirs';
 import { collectDirs, formatDir, formatDirName, pickMatches } from './dirs';
 import { planTextEdit } from './keys';
+import { resolvePathInput } from './resolve-path-input';
 import { ansi, cols, drawPicker } from './ui';
 
 type PickerStep = 'agent' | 'dir' | 'name' | 'prompt';
@@ -45,6 +49,9 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
 
   private dirs: string[] = [];
 
+  // The configured roots, read with the agents each time the menu opens.
+  private roots: readonly string[] = [];
+
   private dir = '';
 
   private name = '';
@@ -59,7 +66,11 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
 
   open(resume = false) {
     this.resume = resume;
-    this.picks = collectAgentPicks(loadConfig());
+
+    const config = loadConfig();
+
+    this.picks = collectAgentPicks(config);
+    this.roots = config.dirs.roots;
     this.input = '';
 
     // A last-used agent that is no longer installed is not in the menu, so
@@ -139,7 +150,7 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
         hint,
       });
     } else if (this.step === 'dir') {
-      const items = pickMatches(this.dirs, this.input).map((d) => formatDir(d));
+      const items = this.collectDirItems().map((d) => formatDir(d));
 
       this.selected = Math.min(this.selected, Math.max(0, Math.min(items.length, 10) - 1));
 
@@ -148,7 +159,7 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
         items,
         selected: this.selected,
         input: this.input,
-        hint: 'type to filter · ↑↓ move · ⏎ select · esc cancel',
+        hint: 'type to filter, or a path (/ ~ .) · ↑↓ move · ⏎ select · esc cancel',
       });
     } else if (this.step === 'name') {
       drawPicker({
@@ -216,13 +227,9 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
     }
 
     if (this.step === 'dir') {
-      const items = pickMatches(this.dirs, this.input);
-      const raw = this.input.trim();
-      let chosen = items[this.selected] ?? null;
-
-      if (chosen === null && (raw.startsWith('/') || raw.startsWith('~'))) {
-        chosen = raw.replace(/^~/u, process.env['HOME'] ?? '~');
-      }
+      const chosen =
+        this.collectDirItems()[this.selected] ??
+        resolvePathInput(this.input.trim(), process.cwd(), homedir());
 
       if (chosen === null) {
         return;
@@ -254,6 +261,16 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
     this.render();
   }
 
+  /**
+   * A typed path completes against the filesystem, like a shell; anything
+   * else fuzzy-filters the merged list.
+   */
+  private collectDirItems(): string[] {
+    return resolvePathInput(this.input, process.cwd(), homedir()) === null
+      ? pickMatches(this.dirs, this.input)
+      : collectPathCompletions(this.input, process.cwd(), homedir());
+  }
+
   private async openDirStep() {
     let recent: string[] = [];
 
@@ -267,7 +284,12 @@ export class SpawnPicker<TMirror extends { readonly id: string }> {
       }
     } catch {}
 
-    this.dirs = await collectDirs(recent);
+    this.dirs = collectDirs({
+      cwd: process.cwd(),
+      recent,
+      roots: this.roots,
+      zoxide: await collectZoxideDirs(),
+    });
 
     this.input = '';
     this.selected = 0;

package/src/daemon/resolve-headless-executable.ts

@@ -0,0 +1,27 @@
+/**
+ * The Claude Code executable a headless turn runs under. The Agent SDK
+ * carries its own copy of the CLI as a platform package, which a compiled
+ * atc binary cannot reach, so a compiled binary hands the SDK the same
+ * `claude` the terminal sessions spawn, resolved on PATH. An npm-installed
+ * `claude` is a JavaScript entry and runs under node, since the SDK would
+ * otherwise spawn it under a bun that is not installed. Under a source run
+ * the SDK's own copy stays in use and the result is empty.
+ */
+export function resolveHeadlessExecutable(
+  claudeBin: string,
+  compiled: boolean,
+): { readonly pathToClaudeCodeExecutable: string; readonly executable?: 'node' } | null {
+  if (!compiled) {
+    return null;
+  }
+
+  // Spawns inherit this process's PATH, so the search list is read live
+  // rather than left to the snapshot Bun.which defaults to.
+  const path = claudeBin.includes('/')
+    ? claudeBin
+    : (Bun.which(claudeBin, { PATH: process.env['PATH'] ?? '' }) ?? claudeBin);
+
+  return /\.[cm]?js$/u.test(path)
+    ? { pathToClaudeCodeExecutable: path, executable: 'node' }
+    : { pathToClaudeCodeExecutable: path };
+}

package/src/daemon/start-headless-run.ts

@@ -1,7 +1,9 @@
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import type { AgentSessionID } from '../shared/agent-session-id';
 import { collectCleanEnv } from '../shared/collect-clean-env';
+import { isCompiledBinary } from '../shared/is-compiled-binary';
 import { isRecord } from '../shared/report';
+import { resolveHeadlessExecutable } from './resolve-headless-executable';
 
 const PERMISSION_MODES = [
   'default',
@@ -13,6 +15,7 @@ const PERMISSION_MODES = [
 ] as const;
 
 interface HeadlessRunOptions {
+  readonly claudeBin: string;
   readonly cwd: string;
   readonly prompt: string;
   readonly resume?: AgentSessionID;
@@ -62,6 +65,7 @@ export function startHeadlessRun(
           // The same generated file the terminal spawn passes, so the turn
           // runs against the session's own backend and instrumentation.
           ...(opts.settings === undefined ? {} : { extraArgs: { settings: opts.settings } }),
+          ...resolveHeadlessExecutable(opts.claudeBin, isCompiledBinary()),
         },
       });
 

package/src/shared/collect-dir-roots.ts

@@ -0,0 +1,33 @@
+import { homedir } from 'node:os';
+import { isRecord } from './report';
+
+/**
+ * Reads `dirs.roots`: the directories whose children the spawn picker
+ * lists. A non-string entry is dropped, a leading `~` expands to the home
+ * directory, and trailing slashes are trimmed so a root compares equal to
+ * the paths under it.
+ */
+export function collectDirRoots(raw: unknown): readonly string[] {
+  if (!isRecord(raw) || !Array.isArray(raw['roots'])) {
+    return [];
+  }
+
+  const roots: string[] = [];
+
+  for (const item of raw['roots']) {
+    if (typeof item !== 'string' || item === '') {
+      continue;
+    }
+
+    roots.push(normalizeRoot(item));
+  }
+
+  return roots;
+}
+
+function normalizeRoot(dir: string): string {
+  const expanded = dir === '~' ? homedir() : dir.replace(/^~\//u, `${homedir()}/`);
+  const trimmed = expanded.replace(/\/+$/u, '');
+
+  return trimmed === '' ? '/' : trimmed;
+}

package/src/shared/collect-gateways.ts

@@ -18,6 +18,7 @@ export interface GatewayConfig {
   readonly baseURL: string;
   readonly apiKeyHelper?: string;
   readonly env: Readonly<Record<string, string>>;
+  readonly settings?: Readonly<Record<string, unknown>>;
 }
 
 // Ids the built-in adapters answer to; a gateway may not take one.
@@ -34,6 +35,7 @@ const GATEWAY_ENTRY_SCHEMA = z.object({
   args: buildOptionalStringArray(),
   apiKeyHelper: buildOptionalNonEmptyString(),
   env: buildStringEnvRecord(),
+  settings: buildOptionalSettings(),
 });
 
 /**
@@ -76,12 +78,22 @@ export function collectGateways(
       baseURL: parsed.data.baseURL,
       ...(parsed.data.apiKeyHelper === undefined ? {} : { apiKeyHelper: parsed.data.apiKeyHelper }),
       env: parsed.data.env,
+      ...(parsed.data.settings === undefined ? {} : { settings: parsed.data.settings }),
     });
   }
 
   return gateways;
 }
 
+// Claude Code settings the sessions of this gateway are started with, on top of
+// the ones atc writes itself. Anything but an object is no extra settings.
+function buildOptionalSettings() {
+  return z.preprocess(
+    (v) => (isRecord(v) ? v : undefined),
+    z.record(z.string(), z.unknown()).optional(),
+  );
+}
+
 function buildOptionalNonEmptyString() {
   return z.preprocess(
     (v) => (typeof v === 'string' && v !== '' ? v : undefined),

package/src/shared/config.ts

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { z } from 'zod';
 import { buildOptionalString } from './build-optional-string';
 import { buildOptionalStringArray } from './build-optional-string-array';
+import { collectDirRoots } from './collect-dir-roots';
 import { collectGateways } from './collect-gateways';
 import type { GatewayConfig } from './collect-gateways';
 import { collectHooks } from './collect-hooks';
@@ -16,11 +17,20 @@ export interface Config {
   grokArgs: string[];
   codexBin: string;
   codexArgs: string[];
+  dirs: DirsConfig;
   gateways: GatewayConfig[];
   hooks: HooksConfig;
   leader: LeaderKey;
 }
 
+/**
+ * Where the spawn picker looks for directories beyond its own history: each
+ * root contributes its child directories and their worktrees.
+ */
+interface DirsConfig {
+  readonly roots: readonly string[];
+}
+
 interface LeaderKey {
   readonly code: number;
   readonly label: string;
@@ -33,6 +43,7 @@ const DEFAULTS: Config = {
   grokArgs: [],
   codexBin: 'codex',
   codexArgs: [],
+  dirs: { roots: [] },
   gateways: [],
   hooks: {},
   leader: { code: 0, label: '^Space' },
@@ -59,6 +70,7 @@ const CONFIG_SCHEMA = z.object({
   grokArgs: buildOptionalStringArray(),
   codexBin: buildOptionalString(),
   codexArgs: buildOptionalStringArray(),
+  dirs: z.unknown().optional(),
   gateways: z.unknown().optional(),
   hooks: z.unknown().optional(),
   leader: buildOptionalString(),
@@ -102,13 +114,25 @@ export function parseConfig(raw: unknown): Config {
   const grokArgs = parsed.data.grokArgs ?? DEFAULTS.grokArgs;
   const codexBin = parsed.data.codexBin ?? DEFAULTS.codexBin;
   const codexArgs = parsed.data.codexArgs ?? DEFAULTS.codexArgs;
+  const dirs = { roots: collectDirRoots(parsed.data.dirs) };
   const gateways = collectGateways(parsed.data.gateways, claudeBin, claudeArgs);
   const hooks = collectHooks(parsed.data.hooks);
 
   const leader =
     (parsed.data.leader === undefined ? null : decodeLeader(parsed.data.leader)) ?? DEFAULTS.leader;
 
-  return { claudeBin, claudeArgs, grokBin, grokArgs, codexBin, codexArgs, gateways, hooks, leader };
+  return {
+    claudeBin,
+    claudeArgs,
+    grokBin,
+    grokArgs,
+    codexBin,
+    codexArgs,
+    dirs,
+    gateways,
+    hooks,
+    leader,
+  };
 }
 
 // Control bytes the terminal needs for its own input: enter, tab, and esc

package/src/shared/is-compiled-binary.ts

@@ -0,0 +1,12 @@
+import { basename } from 'node:path';
+
+/**
+ * Whether this process is a compiled atc binary rather than bun running the
+ * source tree: the binary is then its own CLI entry, and nothing under
+ * node_modules exists at runtime.
+ */
+export function isCompiledBinary(): boolean {
+  const exec = basename(process.execPath);
+
+  return exec !== 'bun' && exec !== 'bun.exe';
+}