@sandropadin/tend 0.1.0

package/src/index.ts

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+// tend — status of AI coding agents across your tmux sessions.
+//
+//   tend                 list agents grouped by session (all sessions) once
+//   tend watch           live-updating grouped list
+//   tend pick            interactive picker — select an agent and jump to it
+//   tend jump <pane>     jump straight to a pane id (e.g. jump %3)
+//   tend --json          machine-readable output (once)
+//   tend --current       limit to the current session (default: all sessions)
+//   tend --debug <pane>  dump each region's extracted text, for rule tuning
+//
+// Flags: --interval <ms> (watch/pick refresh, default 800),
+//        --once-delay <ms> (fire-once activity sampling window, default 350).
+
+import { capturePane, listClients, listPanes, selfClientTty } from "./tmux.ts";
+import { identifyAgent } from "./detect.ts";
+import { extractRegion } from "./regions.ts";
+import { manifestFor } from "./manifests.ts";
+import { scan, scanOnce, type ScanOptions } from "./scan.ts";
+import { runPicker } from "./pick.ts";
+import { insideTmux, jumpToPane } from "./nav.ts";
+import type { PaneMemory } from "./detect.ts";
+import {
+  CLEAR_SCREEN,
+  dim,
+  renderGrouped,
+  renderJson,
+  summaryLine,
+} from "./render.ts";
+
+interface Options {
+  // "default" = dashboard in a terminal, snapshot when piped. "watch" = the
+  // dashboard, explicitly requested (repaints even when piped).
+  mode: "default" | "watch" | "jump" | "debug" | "clients";
+  json: boolean;
+  all: boolean;
+  once: boolean; // force a one-off snapshot even on an interactive terminal
+  readonly: boolean;
+  interval: number;
+  onceDelay: number;
+  target?: string; // pane id for jump/debug
+  targetClient?: string; // --to <tty>: open jumps in this client (window)
+  other: boolean; // --other: open jumps in the one other attached client
+}
+
+function parseArgs(argv: string[]): Options {
+  const opts: Options = {
+    mode: "default",
+    json: false,
+    all: true, // scan every session by default (global view across all sessions)
+    once: false,
+    readonly: false,
+    interval: 800,
+    onceDelay: 350,
+    other: false,
+  };
+  const args = [...argv];
+  while (args.length) {
+    const a = args.shift()!;
+    switch (a) {
+      case "watch":
+      case "pick": // alias — watch is the selectable dashboard
+      case "select":
+        opts.mode = "watch";
+        break;
+      case "clients":
+        opts.mode = "clients";
+        break;
+      case "--once":
+      case "ls":
+        opts.once = true;
+        break;
+      case "--readonly":
+        opts.readonly = true;
+        break;
+      case "--to":
+        opts.targetClient = args.shift();
+        break;
+      case "--other":
+        opts.other = true;
+        break;
+      case "jump":
+        opts.mode = "jump";
+        opts.target = args.shift();
+        break;
+      case "--debug":
+        opts.mode = "debug";
+        opts.target = args.shift();
+        break;
+      case "--json":
+        opts.json = true;
+        break;
+      case "--current":
+      case "-s":
+        opts.all = false;
+        break;
+      case "--all":
+      case "-a":
+        opts.all = true;
+        break;
+      case "--interval":
+        opts.interval = Number(args.shift()) || opts.interval;
+        break;
+      case "--once-delay":
+        opts.onceDelay = Number(args.shift()) || opts.onceDelay;
+        break;
+      case "-h":
+      case "--help":
+        printHelp();
+        process.exit(0);
+      default:
+        process.stderr.write(`tend: unknown argument "${a}"\n`);
+        process.exit(2);
+    }
+  }
+  return opts;
+}
+
+function printHelp(): void {
+  process.stdout.write(
+    [
+      "tend — status of AI coding agents across your tmux sessions",
+      "",
+      "Usage:",
+      "  tend                 live, selectable dashboard — ↑/↓ move, enter jumps",
+      "                         (falls back to a one-off snapshot when piped)",
+      "  tend --once          print a grouped snapshot and exit",
+      "  tend jump <pane>     jump to a pane id (e.g. jump %3)",
+      "  tend clients         list attached tmux clients (terminal windows)",
+      "  tend --json          machine-readable snapshot",
+      "  tend --current       limit to the current session",
+      "  tend --readonly      dashboard without selection (display-only pane)",
+      "  tend --debug <pane>  dump extracted regions for a pane (rule tuning)",
+      "",
+      "Open jumps in another window (keep the dashboard put):",
+      "  In the dashboard, press `o` to cycle where Enter opens: this window →",
+      "  each other attached client → back. Or preset it:",
+      "  --to <tty>         open jumps in that client (see `tend clients`)",
+      "  --other            open jumps in the one other attached client",
+      "",
+      "Options:",
+      "  --interval <ms>    dashboard refresh interval (default 800)",
+      "  --once-delay <ms>  activity sampling window for --once (default 350)",
+      "",
+    ].join("\n"),
+  );
+}
+
+const scanOpts = (o: Options): ScanOptions => ({ all: o.all });
+
+async function runOnce(opts: Options): Promise<void> {
+  const statuses = await scanOnce(scanOpts(opts), opts.onceDelay);
+  if (opts.json) {
+    process.stdout.write(renderJson(statuses) + "\n");
+  } else {
+    process.stdout.write(renderGrouped(statuses) + "\n\n" + summaryLine(statuses) + "\n");
+  }
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+async function runWatch(opts: Options): Promise<void> {
+  let memory = new Map<string, PaneMemory>();
+  process.on("SIGINT", () => {
+    process.stdout.write("\x1b[?25h\n");
+    process.exit(0);
+  });
+  process.stdout.write("\x1b[?25l"); // hide cursor
+  let frame = 0;
+  for (;;) {
+    const result = await scan(scanOpts(opts), memory);
+    memory = result.memory;
+    const header = new Date().toLocaleTimeString();
+    process.stdout.write(
+      CLEAR_SCREEN +
+        `tend · ${header}\n\n` +
+        renderGrouped(result.statuses, frame++) +
+        "\n\n" +
+        summaryLine(result.statuses) +
+        "\n" +
+        dim("Ctrl-C to exit") +
+        "\n",
+    );
+    await sleep(opts.interval);
+  }
+}
+
+// Resolve which client (window) a jump should open in, from --to / --other.
+// Returns a client tty, or null to use the current window. Exits with guidance
+// when --other is ambiguous.
+async function resolveTargetClient(opts: Options): Promise<string | null> {
+  if (opts.targetClient) return opts.targetClient;
+  if (!opts.other) return null;
+  const clients = await listClients();
+  const self = insideTmux() ? await selfClientTty() : null;
+  const others = clients.filter((c) => c.tty !== self);
+  if (others.length === 1) return others[0]!.tty;
+  if (others.length === 0) {
+    process.stderr.write("tend: --other found no other attached client.\n");
+    process.exit(1);
+  }
+  process.stderr.write(
+    "tend: --other is ambiguous — multiple other clients attached:\n" +
+      others.map((c) => `  ${c.tty}  (${c.session})`).join("\n") +
+      "\nPick one with --to <tty>.\n",
+  );
+  process.exit(1);
+}
+
+async function runClients(): Promise<void> {
+  const clients = await listClients();
+  const self = insideTmux() ? await selfClientTty() : null;
+  if (clients.length === 0) {
+    process.stdout.write(dim("No tmux clients attached.\n"));
+    return;
+  }
+  for (const c of clients) {
+    const mark = c.tty === self ? dim(" (this window)") : "";
+    process.stdout.write(`${c.tty}  → ${c.session}${mark}\n`);
+  }
+}
+
+async function runJump(opts: Options): Promise<void> {
+  const target = opts.target;
+  if (!target) {
+    process.stderr.write("tend jump requires a pane id, e.g. jump %3\n");
+    process.exit(2);
+  }
+  const wanted = target.startsWith("%") ? target : `%${target}`;
+  const panes = await listPanes({ all: true });
+  const pane = panes.find((p) => p.id === wanted);
+  if (!pane) {
+    process.stderr.write(`tend: pane "${target}" not found\n`);
+    process.exit(1);
+  }
+  const client = await resolveTargetClient(opts);
+  await jumpToPane(pane, client ? { client } : {});
+  const where = client ? `${client}` : `${pane.sessionName} (${pane.id})`;
+  process.stdout.write(dim(`→ ${where}\n`));
+}
+
+// Debug: show what each region extractor pulls from a pane so you can see why a
+// rule did or didn't match, then iterate on manifests.ts.
+async function runDebug(opts: Options): Promise<void> {
+  const target = opts.target;
+  if (!target) {
+    process.stderr.write("tend --debug requires a pane id, e.g. --debug %3\n");
+    process.exit(2);
+  }
+  const wanted = target.startsWith("%") ? target : `%${target}`;
+  const panes = await listPanes({ all: true });
+  const pane = panes.find((p) => p.id === wanted);
+  if (!pane) {
+    process.stderr.write(`tend: pane "${target}" not found\n`);
+    process.exit(1);
+  }
+  const lines = await capturePane(pane.id);
+  const agent = identifyAgent(pane, lines.join("\n"));
+  process.stdout.write(
+    `pane ${pane.id}  command=${pane.command}  agent=${agent ?? "(none)"}\n`,
+  );
+  const regions = [
+    "full",
+    "after_last_horizontal_rule",
+    "prompt_box_body",
+    { bottom_non_empty_lines: 6 },
+  ] as const;
+  for (const region of regions) {
+    const label = typeof region === "object" ? "bottom_non_empty_lines(6)" : region;
+    process.stdout.write(`\n\x1b[1m── region: ${label} ──\x1b[0m\n`);
+    process.stdout.write(extractRegion(lines, region) + "\n");
+  }
+  if (agent) {
+    const manifest = manifestFor(agent);
+    process.stdout.write(`\n\x1b[1m── manifest rules for ${agent} ──\x1b[0m\n`);
+    for (const rule of manifest?.rules ?? []) {
+      const regionText = extractRegion(lines, rule.region);
+      const matched = ruleWouldMatch(rule, regionText);
+      const mark = matched ? "\x1b[32m✓\x1b[0m" : "\x1b[90m·\x1b[0m";
+      process.stdout.write(`  ${mark} [${rule.priority}] ${rule.id} → ${rule.state}\n`);
+    }
+  }
+}
+
+// Small duplicate of the engine's predicate, kept here so --debug has no need to
+// export internals. If you change ruleMatches in detect.ts, mirror it here.
+function ruleWouldMatch(
+  rule: { contains?: string[]; anyContains?: string[]; not?: string[]; regex?: string },
+  regionText: string,
+): boolean {
+  const hay = regionText.toLowerCase();
+  if (rule.contains && !rule.contains.every((s) => hay.includes(s.toLowerCase()))) return false;
+  if (rule.anyContains && !rule.anyContains.some((s) => hay.includes(s.toLowerCase()))) return false;
+  if (rule.not && rule.not.some((s) => hay.includes(s.toLowerCase()))) return false;
+  if (rule.regex && !new RegExp(rule.regex, "im").test(regionText)) return false;
+  return true;
+}
+
+async function main(): Promise<void> {
+  const opts = parseArgs(process.argv.slice(2));
+  switch (opts.mode) {
+    case "default":
+    case "watch": {
+      // A snapshot is forced by --json / --once, and is also the right default
+      // when output is piped (so `tend | grep` and `tend > file` behave).
+      if (opts.json || opts.once) {
+        await runOnce(opts);
+        break;
+      }
+      const interactiveTty =
+        process.stdin.isTTY === true && process.stdout.isTTY === true;
+      if (interactiveTty && !opts.readonly) {
+        // Optional preset target window from --to/--other; `o` cycles it live.
+        const initialTarget =
+          opts.targetClient ?? (opts.other ? await resolveTargetClient(opts) : null);
+        await runPicker(scanOpts(opts), opts.interval, initialTarget ?? undefined);
+      } else if (opts.readonly) {
+        await runWatch(opts); // display-only repaint (explicit)
+      } else if (opts.mode === "watch") {
+        await runWatch(opts); // `tend watch` piped → repaint loop (explicit)
+      } else {
+        await runOnce(opts); // bare `tend` piped → one-off snapshot
+      }
+      break;
+    }
+    case "jump":
+      await runJump(opts);
+      break;
+    case "clients":
+      await runClients();
+      break;
+    case "debug":
+      await runDebug(opts);
+      break;
+  }
+}
+
+main().catch((err: unknown) => {
+  process.stderr.write(`tend: ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+});

package/src/manifests.ts

@@ -0,0 +1,139 @@
+// Agent manifests — the declarative rule sets. This is the file you tune.
+//
+// Detection philosophy: read what's already on the screen rather than demand
+// agents speak a protocol. Each rule matches a region of the
+// captured terminal; the highest-priority match wins. "blocked" is deliberately
+// strict (only fires on a positive match of a known approval UI) so you don't
+// get false "needs you" alarms; everything else falls back to idle.
+//
+// These patterns are a starting point. Run `tend --debug <pane>` against a
+// live pane to see exactly what text each region extracts, then adjust.
+
+import type { Manifest } from "./types.ts";
+
+const claude: Manifest = {
+  agent: "claude",
+  match: ["claude"],
+  // Claude Code renames its process comm to its version (e.g. "2.1.200"), so the
+  // literal name never appears — this catches it regardless of screen state.
+  commandPattern: "^\\d+\\.\\d+\\.\\d+",
+  // Persistent on-screen chrome, for the rare case comm is generic (`node`).
+  // These are strings Claude keeps visible in SOME state during a live session —
+  // the mode footer, the shortcuts hint, the interrupt hint, the permission
+  // prompt — NOT the welcome banner, which scrolls away mid-conversation.
+  signature: [
+    "shift+tab to cycle", // mode footer (auto/plan mode)
+    "? for shortcuts", // default footer
+    "esc to interrupt", // working footer
+    "for agents", // "← for agents" footer
+    "Do you want to proceed?", // permission prompt
+    "No, and tell Claude", // permission prompt option
+    "Claude Code", // welcome banner (fresh session)
+  ],
+  rules: [
+    // Scrollback / transcript / picker screens don't reflect live state — hold.
+    {
+      id: "transcript_or_picker",
+      state: "unknown",
+      priority: 950,
+      region: "full",
+      anyContains: ["(END)", "Select a model", "Choose a model", "─ Transcript ─"],
+      skipStateUpdate: true,
+    },
+    // Blocked = a *live* permission/approval prompt: the selection cursor (❯)
+    // sits on a numbered choice while Claude waits for you. Keying on the live
+    // cursor (not the question text) is deliberate — the cursor vanishes the
+    // instant you answer, so a prompt lingering in the scroll buffer no longer
+    // counts as blocked. `not` guards against a stale answered prompt whose text
+    // is still on screen but whose cursor has moved on.
+    {
+      id: "selection_prompt",
+      state: "blocked",
+      priority: 900,
+      region: { bottom_non_empty_lines: 15 },
+      regex: "^\\s*❯\\s+\\d+\\.\\s", // e.g. "❯ 1. Yes"
+      not: ["esc to interrupt"], // if it's generating, it isn't waiting on you
+    },
+    // Actively generating — Claude shows an interrupt hint while working.
+    {
+      id: "working_interrupt_hint",
+      state: "working",
+      priority: 700,
+      region: { bottom_non_empty_lines: 8 },
+      anyContains: ["esc to interrupt", "(esc to interrupt)"],
+    },
+    // Empty prompt box with the caret and no menu chrome = idle, awaiting input.
+    {
+      id: "idle_prompt",
+      state: "idle",
+      priority: 100,
+      region: "prompt_box_body",
+      regex: "^\\s*[>❯]",
+      not: ["esc to interrupt", "1. Yes", "Do you want"],
+    },
+  ],
+};
+
+const codex: Manifest = {
+  agent: "codex",
+  match: ["codex"],
+  signature: ["OpenAI Codex", "Codex CLI", "codex>"],
+  rules: [
+    // Blocked = a *live* prompt Codex is waiting on — a command-approval dialog
+    // or a selectable question (request_user_input). Both render as a numbered
+    // list with the live selection cursor `›` (U+203A, Codex's analogue of
+    // Claude's `❯`) on one choice. Key on that cursor row, NOT footer text:
+    // Codex keeps "esc to interrupt" in the prompt footer even while blocked
+    // (e.g. "enter to submit answer | esc to interrupt"), so the interrupt hint
+    // can't distinguish blocked from working — only the live cursor can. Like
+    // Claude's ❯ cursor, it vanishes the instant you answer, so a prompt left in
+    // scrollback stops counting as blocked.
+    {
+      id: "selection_prompt",
+      state: "blocked",
+      priority: 900,
+      region: { bottom_non_empty_lines: 20 },
+      regex: "^\\s*›\\s+\\d+\\.\\s", // e.g. "› 1. Yes"
+    },
+    // Belt-and-suspenders: explicit approval/question wording, for a prompt
+    // whose numbered cursor row isn't in the captured window (long command
+    // preview pushing it out of view).
+    {
+      id: "approval_prompt",
+      state: "blocked",
+      priority: 890,
+      region: { bottom_non_empty_lines: 20 },
+      anyContains: [
+        "Allow command",
+        "wants to run",
+        "Do you want to apply",
+        "enter to submit answer", // selectable-question footer
+      ],
+    },
+    {
+      id: "working_interrupt_hint",
+      state: "working",
+      priority: 700,
+      region: { bottom_non_empty_lines: 8 },
+      anyContains: ["Esc to interrupt", "esc to interrupt", "Working", "Thinking"],
+    },
+    {
+      id: "idle_prompt",
+      state: "idle",
+      priority: 100,
+      region: "prompt_box_body",
+      regex: "^\\s*[>›❯▌]", // Codex's input marker is `›` (U+203A)
+      not: ["Esc to interrupt", "Allow command", "enter to submit answer"],
+    },
+  ],
+};
+
+// Generic fallback for any other terminal agent: no screen rules, so its state
+// comes purely from PTY activity (content changed since last tick = working).
+// Add signatures/rules here as you bring more agents into the fold.
+export const MANIFESTS: Manifest[] = [claude, codex];
+
+// Ordered agent-name → manifest lookup used by the detector.
+export function manifestFor(agent: string): Manifest | undefined {
+  return MANIFESTS.find((m) => m.agent === agent);
+}

package/src/nav.ts

@@ -0,0 +1,44 @@
+// Jump the terminal to an agent's pane. Inside tmux we switch the attached
+// client instantly; outside tmux we pre-select the pane on the server and then
+// hand the terminal to `tmux attach`.
+
+import { spawn } from "node:child_process";
+import { preselectPane, switchClientToPane, switchToPane } from "./tmux.ts";
+import type { PaneInfo } from "./types.ts";
+
+export { listClients, selfClientTty, type TmuxClient } from "./tmux.ts";
+
+export function insideTmux(): boolean {
+  return Boolean(process.env.TMUX);
+}
+
+export interface JumpOptions {
+  // Send the jump to this client (tty) instead of our own — e.g. open the agent
+  // in a different terminal window while the dashboard stays put.
+  client?: string;
+}
+
+// Jump the terminal to an agent's pane.
+//  - opts.client set  → move that other client to the pane (dashboard stays).
+//  - inside tmux      → switch our own client and resolve immediately.
+//  - outside tmux     → pre-select the pane, then `tmux attach` (blocks until
+//                       the user detaches).
+export async function jumpToPane(pane: PaneInfo, opts: JumpOptions = {}): Promise<void> {
+  const { sessionName, id: paneId } = pane;
+  if (opts.client) {
+    await switchClientToPane(opts.client, sessionName, paneId);
+    return;
+  }
+  if (insideTmux()) {
+    await switchToPane(sessionName, paneId);
+    return;
+  }
+  await preselectPane(paneId);
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn("tmux", ["attach-session", "-t", sessionName], {
+      stdio: "inherit",
+    });
+    child.on("close", () => resolve());
+    child.on("error", reject);
+  });
+}