tmux-agent 0.1.0

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "tmux-agent",
+  "version": "0.1.0",
+  "description": "LLM-friendly tmux control plane CLI",
+  "packageManager": "bun@1.2.17",
+  "license": "MIT",
+  "bin": {
+    "agent-tmux": "dist/cli/index.js"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "typescript": "^5.5.4",
+    "vitest": "^1.6.0"
+  }
+}

package/src/cli/commands/codex/forkHome.ts

@@ -0,0 +1,141 @@
+import { formatJson } from "../../../lib/output/format";
+import { readStdin } from "../../../lib/io/readStdin";
+import { cleanupForkHome, prepareForkHome } from "../../../lib/codex/forkHome";
+
+type PrepareSpec = {
+  parent_codex_home?: string;
+  parent_rollout_path?: string;
+  fork_home?: string;
+  run_id?: string;
+  copy_config?: boolean;
+};
+
+type CleanupSpec = {
+  path?: string;
+  cleanup_path?: string;
+  allowed_root?: string;
+};
+
+function parseJsonObject(raw: string): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error("spec must be valid JSON");
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("spec must be a JSON object");
+  }
+  return parsed as Record<string, unknown>;
+}
+
+async function readSpec(specArg?: string): Promise<Record<string, unknown> | null> {
+  if (!specArg) {
+    return null;
+  }
+  if (specArg !== "-") {
+    throw new Error("spec must be '-' to read from stdin");
+  }
+  const raw = await readStdin();
+  return parseJsonObject(raw);
+}
+
+function pickString(
+  value: string | boolean | undefined,
+  fallback: unknown
+): string | undefined {
+  if (typeof value === "string" && value.trim()) {
+    return value.trim();
+  }
+  if (typeof fallback === "string" && fallback.trim()) {
+    return fallback.trim();
+  }
+  return undefined;
+}
+
+function pickBoolean(
+  value: string | boolean | undefined,
+  fallback: unknown,
+  defaultValue: boolean
+): boolean {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "string") {
+    return value.trim().toLowerCase() !== "false";
+  }
+  if (typeof fallback === "boolean") {
+    return fallback;
+  }
+  return defaultValue;
+}
+
+export type CodexForkHomePrepareOptions = {
+  json?: boolean;
+  parentRollout?: string;
+  forkHome?: string;
+  parentCodexHome?: string;
+  runId?: string;
+  copyConfig?: boolean;
+  spec?: string;
+};
+
+export async function codexForkHomePrepareCommand(
+  options: CodexForkHomePrepareOptions = {}
+): Promise<string> {
+  const spec = await readSpec(options.spec);
+  const specTyped = spec as PrepareSpec | null;
+
+  const parentRolloutPath = pickString(
+    options.parentRollout,
+    specTyped?.parent_rollout_path
+  );
+  const forkHome = pickString(options.forkHome, specTyped?.fork_home);
+  if (!parentRolloutPath || !forkHome) {
+    throw new Error("fork-home prepare requires --parent-rollout and --fork-home");
+  }
+
+  const result = await prepareForkHome({
+    parentCodexHome: pickString(options.parentCodexHome, specTyped?.parent_codex_home),
+    parentRolloutPath,
+    forkHome,
+    runId: pickString(options.runId, specTyped?.run_id),
+    copyConfig: pickBoolean(options.copyConfig, specTyped?.copy_config, true)
+  });
+
+  if (options.json) {
+    return formatJson(result);
+  }
+
+  return `${result.fork_home}\n${result.fork_rollout_path}`;
+}
+
+export type CodexForkHomeCleanupOptions = {
+  json?: boolean;
+  path?: string;
+  allowedRoot?: string;
+  spec?: string;
+};
+
+export async function codexForkHomeCleanupCommand(
+  options: CodexForkHomeCleanupOptions = {}
+): Promise<string> {
+  const spec = await readSpec(options.spec);
+  const specTyped = spec as CleanupSpec | null;
+
+  const cleanupPath = pickString(options.path, specTyped?.path ?? specTyped?.cleanup_path);
+  const allowedRoot = pickString(options.allowedRoot, specTyped?.allowed_root);
+  if (!cleanupPath || !allowedRoot) {
+    throw new Error("fork-home cleanup requires --path and --allowed-root");
+  }
+
+  const result = await cleanupForkHome(cleanupPath, allowedRoot);
+  if (!result.removed) {
+    throw new Error("cleanup did not remove path");
+  }
+
+  if (options.json) {
+    return formatJson(result);
+  }
+  return String(result.removed);
+}

package/src/cli/commands/codex/send.ts

@@ -0,0 +1,83 @@
+import { formatJson } from "../../../lib/output/format";
+import { readStdin } from "../../../lib/io/readStdin";
+import { resolveSessionScope, resolveWindowScope } from "../../../lib/targeting/scope";
+import { resolvePaneTarget } from "../../../lib/targeting/resolvePaneTarget";
+import { snapshotPanes } from "../../../lib/tmux/snapshotPanes";
+import { codexSend } from "../../../lib/codex/send";
+
+function isPaneIdTarget(target: string): boolean {
+  return target.startsWith("%") || /^@[^%]+%[^%]+$/.test(target);
+}
+
+export type CodexSendOptions = {
+  json?: boolean;
+  session?: string;
+  window?: string;
+  submit?: string;
+  submitDelayMs?: number;
+  postDelayMs?: number;
+  captureTail?: number;
+};
+
+export async function codexSendCommand(
+  target: string,
+  textArg: string,
+  options: CodexSendOptions = {}
+): Promise<string> {
+  if (!target || !textArg) {
+    throw new Error("codex send requires <paneTarget> <text>");
+  }
+
+  const scope = await resolveSessionScope(options.session?.trim() || undefined);
+
+  let windowId: string | undefined;
+  if (!isPaneIdTarget(target)) {
+    const window = await resolveWindowScope(
+      scope.session,
+      options.window?.trim() || undefined
+    );
+    windowId = window.wid;
+  }
+
+  const panes = await snapshotPanes({ session: scope.session });
+  const resolved = resolvePaneTarget(panes, target, { windowId });
+
+  const textSource = textArg === "-" ? "stdin" : "arg";
+  const text = textArg === "-" ? await readStdin() : textArg;
+
+  const submitRaw = options.submit === undefined ? "Enter" : String(options.submit);
+  const submitKeyRaw = submitRaw.trim();
+  const submitKey =
+    submitKeyRaw.toLowerCase() === "none" || submitKeyRaw.toLowerCase() === "false"
+      ? ""
+      : submitKeyRaw;
+  const submitDelayMs =
+    (options.submitDelayMs !== undefined ? Math.max(0, options.submitDelayMs) : undefined) ??
+    (submitKey ? 250 : 0);
+  const postDelayMs = options.postDelayMs !== undefined ? Math.max(0, options.postDelayMs) : 0;
+  const captureTailLines =
+    options.captureTail !== undefined ? Math.max(0, Math.floor(options.captureTail)) : undefined;
+
+  const result = await codexSend(resolved.id, text, {
+    submitKey,
+    submitDelayMs,
+    postDelayMs,
+    captureTailLines
+  });
+
+  if (options.json) {
+    const { capture_tail, ...sent } = result;
+    return formatJson({
+      requested: { target, text_source: textSource },
+      resolved: { id: resolved.id, ...(resolved.idx !== undefined ? { idx: resolved.idx } : {}) },
+      sent,
+      ...(capture_tail ? { capture_tail } : {})
+    });
+  }
+
+  if (captureTailLines && captureTailLines > 0) {
+    return result.capture_tail ?? resolved.id;
+  }
+
+  return resolved.id;
+}

package/src/cli/commands/codex/sessionInfo.ts

@@ -0,0 +1,59 @@
+import { formatJson } from "../../../lib/output/format";
+import { resolveSessionScope, resolveWindowScope } from "../../../lib/targeting/scope";
+import { resolvePaneTarget } from "../../../lib/targeting/resolvePaneTarget";
+import { snapshotPanes } from "../../../lib/tmux/snapshotPanes";
+import { resolveCodexSessionInfo } from "../../../lib/codex/sessionInfo";
+
+function isPaneIdTarget(target: string): boolean {
+  return target.startsWith("%") || /^@[^%]+%[^%]+$/.test(target);
+}
+
+export type CodexSessionInfoOptions = {
+  json?: boolean;
+  session?: string;
+  window?: string;
+};
+
+export async function codexSessionInfoCommand(
+  target: string,
+  options: CodexSessionInfoOptions = {}
+): Promise<string> {
+  if (!target) {
+    throw new Error("codex session-info requires <paneTarget>");
+  }
+
+  const scope = await resolveSessionScope(options.session?.trim() || undefined);
+
+  let windowId: string | undefined;
+  if (!isPaneIdTarget(target)) {
+    const window = await resolveWindowScope(
+      scope.session,
+      options.window?.trim() || undefined
+    );
+    windowId = window.wid;
+  }
+
+  const panes = await snapshotPanes({ session: scope.session });
+  const resolved = resolvePaneTarget(panes, target, { windowId });
+  const resolvedPane = panes.find((pane) => pane.id === resolved.id);
+
+  const info = await resolveCodexSessionInfo({
+    paneId: resolved.id,
+    panePid: resolvedPane?.pid
+  });
+
+  if (options.json) {
+    return formatJson({
+      requested: { target },
+      resolved: { id: resolved.id, ...(resolved.idx !== undefined ? { idx: resolved.idx } : {}) },
+      session_id: info.sessionId,
+      rollout_path: info.rolloutPath,
+      method: info.method,
+      ...(info.matchedPids ? { matched_pids: info.matchedPids } : {}),
+      ...(info.selfPid ? { self_pid: info.selfPid } : {}),
+      ...(info.codexHome ? { codex_home: info.codexHome } : {})
+    });
+  }
+
+  return `${info.sessionId}\n${info.rolloutPath}`;
+}

package/src/cli/commands/codex/spawn.ts

@@ -0,0 +1,90 @@
+import { formatJson } from "../../../lib/output/format";
+import { resolveSessionScope, resolveWindowScope } from "../../../lib/targeting/scope";
+import { resolvePaneTarget } from "../../../lib/targeting/resolvePaneTarget";
+import { snapshotPanes } from "../../../lib/tmux/snapshotPanes";
+import { codexSpawn } from "../../../lib/codex/spawn";
+import { tmuxExec } from "../../../lib/tmux/exec";
+
+function isPaneIdTarget(target: string): boolean {
+  return target.startsWith("%") || /^@[^%]+%[^%]+$/.test(target);
+}
+
+async function readGlobalOriginOption(): Promise<string | null> {
+  try {
+    const result = await tmuxExec(["show", "-gqv", "@panel_origin_pane_id"]);
+    const value = result.stdout.trim();
+    if (!value || value.includes("#{") || !value.startsWith("%")) {
+      return null;
+    }
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+function resolveOriginCandidate(): string | null {
+  const envFirst = [process.env.CODEX_PANE_ID, process.env.ORIGIN_PANE_ID, process.env.TMUX_PANE];
+  for (const candidate of envFirst) {
+    const value = (candidate ?? "").trim();
+    if (!value || value.includes("#{")) {
+      continue;
+    }
+    return value;
+  }
+  return null;
+}
+
+export type CodexSpawnOptions = {
+  json?: boolean;
+  origin?: string;
+  session?: string;
+  window?: string;
+  forceSimpleSplit?: boolean;
+};
+
+export async function codexSpawnCommand(options: CodexSpawnOptions = {}): Promise<string> {
+  let originTarget = options.origin ? String(options.origin).trim() : "";
+  if (!originTarget) {
+    originTarget = resolveOriginCandidate() ?? "";
+  }
+  if (!originTarget) {
+    originTarget = (await readGlobalOriginOption()) ?? "";
+  }
+
+  if (!originTarget) {
+    throw new Error(
+      "codex spawn requires --origin <paneTarget> (or run inside tmux with TMUX_PANE)"
+    );
+  }
+
+  const panesAll = await snapshotPanes({});
+
+  let windowId: string | undefined;
+  if (!isPaneIdTarget(originTarget)) {
+    const scope = await resolveSessionScope(
+      options.session?.trim() || undefined
+    );
+    const window = await resolveWindowScope(
+      scope.session,
+      options.window?.trim() || undefined
+    );
+    windowId = window.wid;
+  }
+
+  const resolved = resolvePaneTarget(panesAll, originTarget, { windowId });
+
+  const created = await codexSpawn(resolved.id, {
+    forceSimpleSplit: Boolean(options.forceSimpleSplit)
+  });
+
+  if (options.json) {
+    return formatJson({
+      requested: { origin: originTarget },
+      origin: { id: resolved.id, ...(resolved.idx !== undefined ? { idx: resolved.idx } : {}) },
+      created: { id: created.createdPaneId },
+      meta: created.meta
+    });
+  }
+
+  return created.createdPaneId;
+}

package/src/cli/commands/find.ts

@@ -0,0 +1,40 @@
+import { formatJson, formatPaneTable } from "../../lib/output/format";
+import { resolveSessionScope, resolveWindowScope } from "../../lib/targeting/scope";
+import { snapshotPanes } from "../../lib/tmux/snapshotPanes";
+
+export type FindOptions = {
+  json?: boolean;
+  session?: string;
+  window?: string;
+};
+
+export async function find(query: string, options: FindOptions = {}): Promise<string> {
+  if (!query || !query.trim()) {
+    throw new Error("missing find query");
+  }
+
+  const scope = await resolveSessionScope(options.session?.trim() || undefined);
+  const window = await resolveWindowScope(
+    scope.session,
+    options.window?.trim() || undefined
+  );
+
+  const panes = await snapshotPanes({ windowId: window.wid });
+  const needle = query.toLowerCase();
+  const matches = panes.filter(
+    (pane) =>
+      pane.command.toLowerCase().includes(needle) ||
+      pane.title.toLowerCase().includes(needle)
+  );
+
+  if (options.json) {
+    return formatJson({
+      query,
+      session: { name: scope.session },
+      window: { widx: window.widx, wid: window.wid, name: window.name },
+      panes: matches
+    });
+  }
+
+  return formatPaneTable(matches);
+}

package/src/cli/commands/paneKill.ts

@@ -0,0 +1,49 @@
+import { formatJson } from "../../lib/output/format";
+import { resolveSessionScope, resolveWindowScope } from "../../lib/targeting/scope";
+import { resolvePaneTarget } from "../../lib/targeting/resolvePaneTarget";
+import { snapshotPanes } from "../../lib/tmux/snapshotPanes";
+import { paneKill } from "../../lib/tmux/paneOps";
+
+function isPaneIdTarget(target: string): boolean {
+  return target.startsWith("%") || /^@[^%]+%[^%]+$/.test(target);
+}
+
+export type PaneKillOptions = {
+  json?: boolean;
+  session?: string;
+  window?: string;
+};
+
+export async function paneKillCommand(
+  target: string,
+  options: PaneKillOptions = {}
+): Promise<string> {
+  if (!target) {
+    throw new Error("pane kill requires <paneTarget>");
+  }
+
+  const scope = await resolveSessionScope(options.session?.trim() || undefined);
+
+  let windowId: string | undefined;
+  if (!isPaneIdTarget(target)) {
+    const window = await resolveWindowScope(
+      scope.session,
+      options.window?.trim() || undefined
+    );
+    windowId = window.wid;
+  }
+
+  const panes = await snapshotPanes({ session: scope.session });
+  const resolved = resolvePaneTarget(panes, target, { windowId });
+  await paneKill(resolved.id);
+
+  if (options.json) {
+    return formatJson({
+      requested: { target },
+      resolved: { id: resolved.id, ...(resolved.idx !== undefined ? { idx: resolved.idx } : {}) },
+      killed: true
+    });
+  }
+
+  return resolved.id;
+}

package/src/cli/commands/paneSpawn.ts

@@ -0,0 +1,53 @@
+import { formatJson } from "../../lib/output/format";
+import { readStdin } from "../../lib/io/readStdin";
+import { resolveSessionScope, resolveWindowScope } from "../../lib/targeting/scope";
+import { paneSpawn, paneTitle } from "../../lib/tmux/paneOps";
+import { tmuxExec } from "../../lib/tmux/exec";
+import { pasteText } from "../../lib/tmux/paste";
+
+export type PaneSpawnOptions = {
+  json?: boolean;
+  session?: string;
+  window?: string;
+  title?: string;
+};
+
+export async function paneSpawnCommand(
+  commandArg: string,
+  options: PaneSpawnOptions = {}
+): Promise<string> {
+  if (!commandArg) {
+    throw new Error("pane spawn requires <command>");
+  }
+
+  const scope = await resolveSessionScope(options.session?.trim() || undefined);
+  const window = await resolveWindowScope(scope.session, options.window?.trim() || undefined);
+
+  let command = commandArg;
+  if (commandArg === "-") {
+    command = await readStdin();
+  }
+
+  const created = await paneSpawn(window.wid);
+  const title = options.title?.trim() || undefined;
+  if (command) {
+    await pasteText(created.id, command);
+    await tmuxExec(["send-keys", "-t", created.id, "Enter"]);
+  }
+  if (title) {
+    await paneTitle(created.id, title);
+  }
+
+  if (options.json) {
+    return formatJson({
+      created: {
+        id: created.id,
+        idx: created.idx,
+        command,
+        title: title ?? ""
+      }
+    });
+  }
+
+  return created.id;
+}

package/src/cli/commands/paneTitle.ts

@@ -0,0 +1,50 @@
+import { formatJson } from "../../lib/output/format";
+import { resolveSessionScope, resolveWindowScope } from "../../lib/targeting/scope";
+import { resolvePaneTarget } from "../../lib/targeting/resolvePaneTarget";
+import { snapshotPanes } from "../../lib/tmux/snapshotPanes";
+import { paneTitle } from "../../lib/tmux/paneOps";
+
+function isPaneIdTarget(target: string): boolean {
+  return target.startsWith("%") || /^@[^%]+%[^%]+$/.test(target);
+}
+
+export type PaneTitleOptions = {
+  json?: boolean;
+  session?: string;
+  window?: string;
+};
+
+export async function paneTitleCommand(
+  target: string,
+  title: string,
+  options: PaneTitleOptions = {}
+): Promise<string> {
+  if (!target || !title) {
+    throw new Error("pane title requires <paneTarget> <title>");
+  }
+
+  const scope = await resolveSessionScope(options.session?.trim() || undefined);
+
+  let windowId: string | undefined;
+  if (!isPaneIdTarget(target)) {
+    const window = await resolveWindowScope(
+      scope.session,
+      options.window?.trim() || undefined
+    );
+    windowId = window.wid;
+  }
+
+  const panes = await snapshotPanes({ session: scope.session });
+  const resolved = resolvePaneTarget(panes, target, { windowId });
+  await paneTitle(resolved.id, title);
+
+  if (options.json) {
+    return formatJson({
+      requested: { target, title },
+      resolved: { id: resolved.id, ...(resolved.idx !== undefined ? { idx: resolved.idx } : {}) },
+      updated: { title }
+    });
+  }
+
+  return resolved.id;
+}

package/src/cli/commands/read.ts

@@ -0,0 +1,48 @@
+import { formatJson } from "../../lib/output/format";
+import { resolveSessionScope, resolveWindowScope } from "../../lib/targeting/scope";
+import { resolvePaneTarget } from "../../lib/targeting/resolvePaneTarget";
+import { snapshotPanes } from "../../lib/tmux/snapshotPanes";
+import { capturePane, splitLines } from "../../lib/tmux/capturePane";
+
+function isPaneIdTarget(target: string): boolean {
+  return target.startsWith("%") || /^@[^%]+%[^%]+$/.test(target);
+}
+
+export type ReadOptions = {
+  json?: boolean;
+  session?: string;
+  window?: string;
+  lines?: number;
+};
+
+export async function read(target: string, options: ReadOptions = {}): Promise<string> {
+  if (!target) {
+    throw new Error("read requires <paneTarget>");
+  }
+
+  const lineCount = Math.max(1, Math.floor(options.lines ?? 20));
+  const scope = await resolveSessionScope(options.session?.trim() || undefined);
+
+  let windowId: string | undefined;
+  if (!isPaneIdTarget(target)) {
+    const window = await resolveWindowScope(
+      scope.session,
+      options.window?.trim() || undefined
+    );
+    windowId = window.wid;
+  }
+
+  const panes = await snapshotPanes({ session: scope.session });
+  const resolved = resolvePaneTarget(panes, target, { windowId });
+
+  const text = await capturePane(resolved.id, lineCount);
+  if (options.json) {
+    return formatJson({
+      requested: { target, lines: lineCount },
+      resolved: { id: resolved.id, ...(resolved.idx !== undefined ? { idx: resolved.idx } : {}) },
+      lines: splitLines(text)
+    });
+  }
+
+  return text;
+}