tmux-agent 0.1.0

package/src/cli/index.ts

@@ -0,0 +1,430 @@
+#!/usr/bin/env node
+import { Command, CommanderError } from "commander";
+import { ensureErrorPrefix, formatPaneTable, formatWindowTable } from "../lib/output/format";
+import type { PaneInfo, WindowInfo } from "../lib/contracts/types";
+import { TargetResolutionError } from "../lib/targeting/errors";
+import { windowLs } from "./commands/windowLs";
+import { snapshot } from "./commands/snapshot";
+import { find } from "./commands/find";
+import { send } from "./commands/send";
+import { read } from "./commands/read";
+import { windowNewCommand } from "./commands/windowNew";
+import { windowRenameCommand } from "./commands/windowRename";
+import { windowKillCommand } from "./commands/windowKill";
+import { paneSpawnCommand } from "./commands/paneSpawn";
+import { paneTitleCommand } from "./commands/paneTitle";
+import { paneKillCommand } from "./commands/paneKill";
+import { codexSendCommand } from "./commands/codex/send";
+import { codexSessionInfoCommand } from "./commands/codex/sessionInfo";
+import { codexForkHomeCleanupCommand, codexForkHomePrepareCommand } from "./commands/codex/forkHome";
+import { codexSpawnCommand } from "./commands/codex/spawn";
+import { uiSelectCommand } from "./commands/ui/select";
+
+function writeLine(stream: NodeJS.WritableStream, text: string): void {
+  if (!text.endsWith("\n")) {
+    stream.write(`${text}\n`);
+    return;
+  }
+  stream.write(text);
+}
+
+function formatError(error: unknown): string {
+  if (error instanceof TargetResolutionError) {
+    const base = ensureErrorPrefix(error.message);
+    if (error.kind === "ambiguous" && error.candidates?.length) {
+      if (error.targetKind === "pane") {
+        return `${base}\n${formatPaneTable(error.candidates as PaneInfo[])}`;
+      }
+      return `${base}\n${formatWindowTable(error.candidates as WindowInfo[])}`;
+    }
+    return base;
+  }
+
+  if (error instanceof Error) {
+    return ensureErrorPrefix(error.message);
+  }
+
+  return ensureErrorPrefix(String(error));
+}
+
+function parseOptionalBoolean(value: string | boolean | undefined): boolean {
+  if (value === undefined) {
+    return true;
+  }
+  if (typeof value === "boolean") {
+    return value;
+  }
+  const normalized = value.trim().toLowerCase();
+  return normalized !== "false";
+}
+
+function parseNonNegativeNumber(optionName: string): (value: string) => number {
+  return (value: string) => {
+    const num = Number(value);
+    if (!Number.isFinite(num) || num < 0) {
+      throw new Error(`invalid --${optionName}`);
+    }
+    return num;
+  };
+}
+
+function buildProgram(): Command {
+  const program = new Command();
+  program
+    .name("agent-tmux")
+    .description("LLM-friendly tmux control plane CLI for windows/panes.")
+    .exitOverride()
+    .configureOutput({
+      writeErr: () => undefined
+    });
+
+  const window = program.command("window");
+  window.command("ls")
+    .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+    .option("--session <session>", "tmux session name")
+    .action(async (options: { json: boolean; session?: string }) => {
+      const output = await windowLs({ json: options.json, session: options.session });
+      if (output) {
+        writeLine(process.stdout, output);
+      }
+    });
+
+  window.command("new")
+    .argument("<name>")
+    .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+    .option("--session <session>", "tmux session name")
+    .option("--command <command>", "initial command to run (or '-' to read from stdin)")
+    .action(async (name: string, options: { json: boolean; session?: string; command?: string }) => {
+      const output = await windowNewCommand(name, {
+        json: options.json,
+        session: options.session,
+        command: options.command
+      });
+      if (output) {
+        writeLine(process.stdout, output);
+      }
+    });
+
+  window.command("rename")
+    .argument("<windowTarget>")
+    .argument("<name>")
+    .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+    .option("--session <session>", "tmux session name")
+    .action(async (target: string, name: string, options: { json: boolean; session?: string }) => {
+      const output = await windowRenameCommand(target, name, {
+        json: options.json,
+        session: options.session
+      });
+      if (output) {
+        writeLine(process.stdout, output);
+      }
+    });
+
+  window.command("kill")
+    .argument("<windowTarget>")
+    .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+    .option("--session <session>", "tmux session name")
+    .action(async (target: string, options: { json: boolean; session?: string }) => {
+      const output = await windowKillCommand(target, {
+        json: options.json,
+        session: options.session
+      });
+      if (output) {
+        writeLine(process.stdout, output);
+      }
+    });
+
+  const pane = program.command("pane");
+  pane.command("spawn")
+    .argument("<command>")
+    .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+    .option("--session <session>", "tmux session name")
+    .option("--window <window>", "tmux window target")
+    .option("--title <title>", "pane title")
+    .action(async (command: string, options: { json: boolean; session?: string; window?: string; title?: string }) => {
+      const output = await paneSpawnCommand(command, {
+        json: options.json,
+        session: options.session,
+        window: options.window,
+        title: options.title
+      });
+      if (output) {
+        writeLine(process.stdout, output);
+      }
+    });
+
+  pane.command("title")
+    .argument("<paneTarget>")
+    .argument("<title>")
+    .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+    .option("--session <session>", "tmux session name")
+    .option("--window <window>", "tmux window target")
+    .action(async (target: string, title: string, options: { json: boolean; session?: string; window?: string }) => {
+      const output = await paneTitleCommand(target, title, {
+        json: options.json,
+        session: options.session,
+        window: options.window
+      });
+      if (output) {
+        writeLine(process.stdout, output);
+      }
+    });
+
+  pane.command("kill")
+    .argument("<paneTarget>")
+    .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+    .option("--session <session>", "tmux session name")
+    .option("--window <window>", "tmux window target")
+    .action(async (target: string, options: { json: boolean; session?: string; window?: string }) => {
+      const output = await paneKillCommand(target, {
+        json: options.json,
+        session: options.session,
+        window: options.window
+      });
+      if (output) {
+        writeLine(process.stdout, output);
+      }
+    });
+
+  program.command("snapshot")
+    .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+    .option("--session <session>", "tmux session name")
+    .option("--window <window>", "tmux window target")
+    .action(async (options: { json: boolean; session?: string; window?: string }) => {
+      const output = await snapshot({
+        json: options.json,
+        session: options.session,
+        window: options.window
+      });
+      if (output) {
+        writeLine(process.stdout, output);
+      }
+    });
+
+  program.command("find")
+    .argument("<query>")
+    .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+    .option("--session <session>", "tmux session name")
+    .option("--window <window>", "tmux window target")
+    .action(async (query: string, options: { json: boolean; session?: string; window?: string }) => {
+      const output = await find(query, {
+        json: options.json,
+        session: options.session,
+        window: options.window
+      });
+      if (output) {
+        writeLine(process.stdout, output);
+      }
+    });
+
+  program.command("send")
+    .argument("<paneTarget>")
+    .argument("<text>")
+    .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+    .option("--session <session>", "tmux session name")
+    .option("--window <window>", "tmux window target")
+    .option("--no-enter [boolean]", "do not submit Enter", parseOptionalBoolean, false)
+    .option("--enter-delay-ms <ms>", "delay before submitting Enter", parseNonNegativeNumber("enter-delay-ms"))
+    .action(async (
+      target: string,
+      text: string,
+      options: {
+        json: boolean;
+        session?: string;
+        window?: string;
+        noEnter: boolean;
+        enterDelayMs?: number;
+      }
+    ) => {
+      const output = await send(target, text, {
+        json: options.json,
+        session: options.session,
+        window: options.window,
+        noEnter: options.noEnter,
+        enterDelayMs: options.enterDelayMs
+      });
+      if (output) {
+        writeLine(process.stdout, output);
+      }
+    });
+
+  program.command("read")
+    .argument("<paneTarget>")
+    .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+    .option("--session <session>", "tmux session name")
+    .option("--window <window>", "tmux window target")
+    .option("--lines <n>", "lines to capture", parseNonNegativeNumber("lines"))
+    .action(async (
+      target: string,
+      options: { json: boolean; session?: string; window?: string; lines?: number }
+    ) => {
+      const output = await read(target, {
+        json: options.json,
+        session: options.session,
+        window: options.window,
+        lines: options.lines
+      });
+      if (output) {
+        writeLine(process.stdout, output);
+      }
+    });
+
+  const codex = program.command("codex");
+  codex.command("send")
+    .argument("<paneTarget>")
+    .argument("<text>")
+    .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+    .option("--session <session>", "tmux session name")
+    .option("--window <window>", "tmux window target")
+    .option("--submit <key>", "submit key (default Enter; use 'none' to disable)")
+    .option("--submit-delay-ms <ms>", "delay before submitting", parseNonNegativeNumber("submit-delay-ms"))
+    .option("--post-delay-ms <ms>", "delay after submit", parseNonNegativeNumber("post-delay-ms"))
+    .option("--capture-tail <n>", "capture tail lines (prints captured tail when not --json)", parseNonNegativeNumber("capture-tail"))
+    .action(async (
+      target: string,
+      text: string,
+      options: {
+        json: boolean;
+        session?: string;
+        window?: string;
+        submit?: string;
+        submitDelayMs?: number;
+        postDelayMs?: number;
+        captureTail?: number;
+      }
+    ) => {
+      const output = await codexSendCommand(target, text, {
+        json: options.json,
+        session: options.session,
+        window: options.window,
+        submit: options.submit,
+        submitDelayMs: options.submitDelayMs,
+        postDelayMs: options.postDelayMs,
+        captureTail: options.captureTail
+      });
+      if (output) {
+        writeLine(process.stdout, output);
+      }
+    });
+
+  codex.command("session-info")
+    .argument("<paneTarget>")
+    .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+    .option("--session <session>", "tmux session name")
+    .option("--window <window>", "tmux window target")
+    .action(async (target: string, options: { json: boolean; session?: string; window?: string }) => {
+      const output = await codexSessionInfoCommand(target, {
+        json: options.json,
+        session: options.session,
+        window: options.window
+      });
+      if (output) {
+        writeLine(process.stdout, output);
+      }
+    });
+
+  const forkHome = codex.command("fork-home");
+  forkHome.command("prepare")
+    .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+    .option("--parent-rollout <path>", "parent rollout path")
+    .option("--fork-home <path>", "fork CODEX_HOME path")
+    .option("--parent-codex-home <path>", "parent CODEX_HOME override")
+    .option("--run-id <id>", "run id for naming")
+    .option("--copy-config [boolean]", "copy config.toml", parseOptionalBoolean)
+    .option("--spec <spec>", "read json spec from stdin (use '-')")
+    .action(async (options: {
+      json: boolean;
+      parentRollout?: string;
+      forkHome?: string;
+      parentCodexHome?: string;
+      runId?: string;
+      copyConfig?: boolean;
+      spec?: string;
+    }) => {
+      const output = await codexForkHomePrepareCommand({
+        json: options.json,
+        parentRollout: options.parentRollout,
+        forkHome: options.forkHome,
+        parentCodexHome: options.parentCodexHome,
+        runId: options.runId,
+        copyConfig: options.copyConfig,
+        spec: options.spec
+      });
+      if (output) {
+        writeLine(process.stdout, output);
+      }
+    });
+
+  forkHome.command("cleanup")
+    .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+    .option("--path <path>", "path to remove")
+    .option("--allowed-root <root>", "allowed root guard")
+    .option("--spec <spec>", "read json spec from stdin (use '-')")
+    .action(async (options: { json: boolean; path?: string; allowedRoot?: string; spec?: string }) => {
+      const output = await codexForkHomeCleanupCommand({
+        json: options.json,
+        path: options.path,
+        allowedRoot: options.allowedRoot,
+        spec: options.spec
+      });
+      if (output) {
+        writeLine(process.stdout, output);
+      }
+    });
+
+  codex.command("spawn")
+    .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+    .option("--origin <paneTarget>", "origin pane target")
+    .option("--session <session>", "tmux session name")
+    .option("--window <window>", "tmux window target")
+    .option("--force-simple-split [boolean]", "force fallback split", parseOptionalBoolean, false)
+    .action(async (options: {
+      json: boolean;
+      origin?: string;
+      session?: string;
+      window?: string;
+      forceSimpleSplit: boolean;
+    }) => {
+      const output = await codexSpawnCommand({
+        json: options.json,
+        origin: options.origin,
+        session: options.session,
+        window: options.window,
+        forceSimpleSplit: options.forceSimpleSplit
+      });
+      if (output) {
+        writeLine(process.stdout, output);
+      }
+    });
+
+  const ui = program.command("ui");
+  ui.command("select")
+    .requiredOption("--spec <spec>", "read json spec from stdin (use '-')")
+    .option("--json [boolean]", "output json", parseOptionalBoolean, false)
+    .action(async (options: { json: boolean; spec: string }) => {
+      const output = await uiSelectCommand({ json: options.json, spec: options.spec });
+      if (output) {
+        writeLine(process.stdout, output);
+      }
+    });
+
+  return program;
+}
+
+async function run(): Promise<void> {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0) {
+    throw new Error("missing command");
+  }
+  const program = buildProgram();
+  await program.parseAsync(process.argv);
+}
+
+run().catch((error) => {
+  if (error instanceof CommanderError && error.exitCode === 0) {
+    return;
+  }
+  const message = formatError(error);
+  writeLine(process.stderr, message);
+  process.exitCode = 1;
+});

package/src/lib/codex/forkHome.ts

@@ -0,0 +1,148 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { safeRemove } from "../fs/safeRm";
+
+export type ForkHomePrepareOptions = {
+  parentCodexHome?: string;
+  parentRolloutPath: string;
+  forkHome: string;
+  runId?: string;
+  copyConfig?: boolean;
+};
+
+export type ForkHomePrepareResult = {
+  action: "prepare";
+  parent_rollout_path: string;
+  fork_home: string;
+  fork_rollout_path: string;
+  copied_config: boolean;
+  auth_strategy: "symlink" | "copy" | "missing" | "failed";
+  credentials_strategy: "symlink" | "copy" | "missing" | "failed";
+};
+
+export type ForkHomeCleanupResult = {
+  action: "cleanup";
+  removed: boolean;
+};
+
+function resolvePath(value: string): string {
+  return path.resolve(value);
+}
+
+function defaultCodexHome(): string {
+  const env = process.env.CODEX_HOME?.trim();
+  if (env) {
+    return resolvePath(env);
+  }
+  return resolvePath(path.join(process.env.HOME || "", ".codex"));
+}
+
+async function copyOrSymlink(
+  src: string,
+  dst: string
+): Promise<"symlink" | "copy" | "missing" | "failed"> {
+  try {
+    await fs.stat(src);
+  } catch {
+    return "missing";
+  }
+
+  try {
+    await fs.mkdir(path.dirname(dst), { recursive: true });
+    try {
+      await fs.unlink(dst);
+    } catch {
+      // ignore
+    }
+    await fs.symlink(src, dst);
+    return "symlink";
+  } catch {
+    try {
+      await fs.copyFile(src, dst);
+      return "copy";
+    } catch {
+      return "failed";
+    }
+  }
+}
+
+function resolveForkRolloutPath(
+  parentCodexHome: string,
+  parentRolloutPath: string,
+  forkHome: string,
+  runId: string
+): string {
+  try {
+    const relative = path.relative(parentCodexHome, parentRolloutPath);
+    if (!relative.startsWith("..") && !path.isAbsolute(relative)) {
+      return path.join(forkHome, relative);
+    }
+  } catch {
+    // ignore
+  }
+  return path.join(forkHome, "sessions", `rollout-${runId}.jsonl`);
+}
+
+export async function prepareForkHome(
+  options: ForkHomePrepareOptions
+): Promise<ForkHomePrepareResult> {
+  const parentCodexHome = resolvePath(options.parentCodexHome || defaultCodexHome());
+  const parentRolloutPath = resolvePath(options.parentRolloutPath);
+  const forkHome = resolvePath(options.forkHome);
+  const runId = options.runId?.trim() || String(process.pid);
+  const copyConfig = options.copyConfig ?? true;
+
+  const stat = await fs.stat(parentRolloutPath);
+  if (!stat.isFile()) {
+    throw new Error(`parent_rollout_path is not a file: ${parentRolloutPath}`);
+  }
+
+  await fs.mkdir(forkHome, { recursive: true });
+
+  let copiedConfig = false;
+  if (copyConfig) {
+    const configPath = path.join(parentCodexHome, "config.toml");
+    try {
+      await fs.copyFile(configPath, path.join(forkHome, "config.toml"));
+      copiedConfig = true;
+    } catch {
+      copiedConfig = false;
+    }
+  }
+
+  const authStrategy = await copyOrSymlink(
+    path.join(parentCodexHome, "auth.json"),
+    path.join(forkHome, "auth.json")
+  );
+  const credentialsStrategy = await copyOrSymlink(
+    path.join(parentCodexHome, ".credentials.json"),
+    path.join(forkHome, ".credentials.json")
+  );
+
+  const forkRolloutPath = resolveForkRolloutPath(
+    parentCodexHome,
+    parentRolloutPath,
+    forkHome,
+    runId
+  );
+  await fs.mkdir(path.dirname(forkRolloutPath), { recursive: true });
+  await fs.copyFile(parentRolloutPath, forkRolloutPath);
+
+  return {
+    action: "prepare",
+    parent_rollout_path: parentRolloutPath,
+    fork_home: forkHome,
+    fork_rollout_path: forkRolloutPath,
+    copied_config: copiedConfig,
+    auth_strategy: authStrategy,
+    credentials_strategy: credentialsStrategy
+  };
+}
+
+export async function cleanupForkHome(
+  pathToRemove: string,
+  allowedRoot: string
+): Promise<ForkHomeCleanupResult> {
+  const removed = await safeRemove(pathToRemove, allowedRoot);
+  return { action: "cleanup", removed };
+}

package/src/lib/codex/isCodexPane.ts

@@ -0,0 +1,56 @@
+import type { PaneInfo } from "../contracts/types";
+import { listProcesses, type ProcessEntry } from "../proc/ps";
+
+const CODEX_PATTERN = /codex/i;
+
+function matchesCodex(value: string): boolean {
+  return CODEX_PATTERN.test(value);
+}
+
+function hasCodexDescendant(processes: ProcessEntry[], rootPid: number): boolean {
+  const byParent = new Map<number, ProcessEntry[]>();
+  for (const process of processes) {
+    const list = byParent.get(process.ppid);
+    if (list) {
+      list.push(process);
+    } else {
+      byParent.set(process.ppid, [process]);
+    }
+  }
+
+  const queue: number[] = [rootPid];
+  const visited = new Set<number>();
+  while (queue.length) {
+    const current = queue.shift();
+    if (current === undefined || visited.has(current)) {
+      continue;
+    }
+    visited.add(current);
+    const children = byParent.get(current);
+    if (!children) {
+      continue;
+    }
+    for (const child of children) {
+      if (matchesCodex(child.command)) {
+        return true;
+      }
+      queue.push(child.pid);
+    }
+  }
+  return false;
+}
+
+export async function isCodexPane(pane: PaneInfo): Promise<boolean> {
+  if (matchesCodex(pane.command) || matchesCodex(pane.title)) {
+    return true;
+  }
+  if (!pane.pid || !Number.isFinite(pane.pid)) {
+    return false;
+  }
+  try {
+    const processes = await listProcesses();
+    return hasCodexDescendant(processes, pane.pid);
+  } catch {
+    return false;
+  }
+}