@sandropadin/tend 0.1.0

package/dist/regions.js

@@ -0,0 +1,60 @@
+// Region extractors: pure string functions that slice the captured pane text
+// down to the part a rule cares about. Keeping these tiny and pure is what makes
+// the rule engine testable.
+// A "horizontal rule" line is one made mostly of box-drawing horizontals — the
+// borders Claude/Codex draw around their input box and section separators.
+const RULE_CHARS = /[─━╌╍]/g;
+function isRuleLine(line) {
+    const matches = line.match(RULE_CHARS);
+    return matches !== null && matches.length >= 3;
+}
+function indicesOfRuleLines(lines) {
+    const idx = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (isRuleLine(lines[i]))
+            idx.push(i);
+    }
+    return idx;
+}
+// Everything below the last horizontal rule — isolates the live prompt area
+// from scrollback above it.
+export function afterLastHorizontalRule(lines) {
+    const rules = indicesOfRuleLines(lines);
+    if (rules.length === 0)
+        return lines;
+    const last = rules[rules.length - 1];
+    return lines.slice(last + 1);
+}
+// The interior of the input box: the lines between the last two horizontal
+// rules (the box's top and bottom borders). Falls back to the tail if there
+// aren't two borders to bracket.
+export function promptBoxBody(lines) {
+    const rules = indicesOfRuleLines(lines);
+    if (rules.length < 2)
+        return bottomNonEmptyLines(lines, 3);
+    const bottom = rules[rules.length - 1];
+    const top = rules[rules.length - 2];
+    return lines.slice(top + 1, bottom);
+}
+// The last N lines that aren't blank.
+export function bottomNonEmptyLines(lines, n) {
+    const out = [];
+    for (let i = lines.length - 1; i >= 0 && out.length < n; i--) {
+        if (lines[i].trim().length > 0)
+            out.push(lines[i]);
+    }
+    return out.reverse();
+}
+export function extractRegion(lines, region) {
+    if (typeof region === "object") {
+        return bottomNonEmptyLines(lines, region.bottom_non_empty_lines).join("\n");
+    }
+    switch (region) {
+        case "full":
+            return lines.join("\n");
+        case "after_last_horizontal_rule":
+            return afterLastHorizontalRule(lines).join("\n");
+        case "prompt_box_body":
+            return promptBoxBody(lines).join("\n");
+    }
+}

package/dist/render.js

@@ -0,0 +1,118 @@
+// Terminal rendering: agents grouped by tmux session, with colored state dots
+// and a git column. No dependencies — raw ANSI. Falls back to plain text when
+// stdout isn't a TTY (piped) or NO_COLOR is set.
+const useColor = process.stdout.isTTY === true && !process.env.NO_COLOR;
+export const color = (code, s) => useColor ? `\x1b[${code}m${s}\x1b[0m` : s;
+export const dim = (s) => color("2", s);
+export const bold = (s) => color("1", s);
+// Braille spinner frames for the "working" state (classic dots animation).
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+// The state indicator: a distinct *shape* per state (so it reads even without
+// color) plus color. "working" animates through the spinner; `frame` advances it.
+export function stateGlyph(state, frame = 0) {
+    switch (state) {
+        case "blocked":
+            return color("31", "●"); // red filled — needs you
+        case "working":
+            return color("33", SPINNER[frame % SPINNER.length]); // yellow spinner
+        case "idle":
+            return color("32", "○"); // green hollow — waiting for input
+        case "unknown":
+            return color("90", "◌"); // grey dotted — unknown
+    }
+}
+export function gitCell(git) {
+    if (!git || !git.branch)
+        return dim("—");
+    let s = git.branch;
+    const marks = [];
+    if (git.ahead)
+        marks.push(`↑${git.ahead}`);
+    if (git.behind)
+        marks.push(`↓${git.behind}`);
+    if (git.dirty)
+        marks.push(color("33", "✱"));
+    if (marks.length)
+        s += " " + marks.join(" ");
+    return s;
+}
+// Pad by *visible* width, ignoring ANSI escapes.
+export function pad(s, width) {
+    const visible = s.replace(/\x1b\[[0-9;]*m/g, "").length;
+    return s + " ".repeat(Math.max(0, width - visible));
+}
+const STATE_ORDER = {
+    blocked: 0,
+    working: 1,
+    idle: 2,
+    unknown: 3,
+};
+// Group agents by tmux session (insertion order = tmux's session order), with
+// each session's agents sorted blocked→working→idle so the ones needing you
+// float to the top.
+export function groupBySession(statuses) {
+    const groups = new Map();
+    for (const s of statuses) {
+        const key = s.pane.sessionName;
+        let list = groups.get(key);
+        if (!list) {
+            list = [];
+            groups.set(key, list);
+        }
+        list.push(s);
+    }
+    return [...groups.entries()].map(([session, agents]) => ({
+        session,
+        agents: agents.sort((a, b) => STATE_ORDER[a.state] - STATE_ORDER[b.state]),
+    }));
+}
+// One agent row: state glyph + pane id + agent + git. The glyph's shape+color
+// carries the state (● red blocked, spinner yellow working, ○ green idle); the
+// pane id is the jump reference. `cursor` renders a caret; `frame` animates the
+// working spinner.
+export function agentRow(s, cursor = false, frame = 0) {
+    const caret = cursor ? bold("❯ ") : "  ";
+    return (caret +
+        `${stateGlyph(s.state, frame)} ` +
+        pad(s.pane.id, 6) +
+        pad(bold(s.agent), 10) +
+        gitCell(s.git));
+}
+export function renderGrouped(statuses, frame = 0) {
+    if (statuses.length === 0) {
+        return dim("No AI agents detected in any tmux session.");
+    }
+    const lines = [];
+    for (const { session, agents } of groupBySession(statuses)) {
+        const blocked = agents.filter((a) => a.state === "blocked").length;
+        const suffix = blocked ? color("31", ` · ${blocked} blocked`) : "";
+        lines.push(bold(`▸ ${session}`) + dim(`  (${agents.length})`) + suffix);
+        for (const a of agents)
+            lines.push(agentRow(a, false, frame));
+        lines.push("");
+    }
+    if (lines[lines.length - 1] === "")
+        lines.pop();
+    return lines.join("\n");
+}
+export function renderJson(statuses) {
+    return JSON.stringify(statuses.map((s) => ({
+        pane: s.pane.id,
+        agent: s.agent,
+        state: s.state,
+        matchedRule: s.matchedRule,
+        session: s.pane.sessionName,
+        window: s.pane.windowName,
+        path: s.pane.path,
+        git: s.git,
+    })), null, 2);
+}
+export const CLEAR_SCREEN = "\x1b[2J\x1b[H";
+export function summaryLine(statuses) {
+    const counts = { blocked: 0, working: 0, idle: 0, unknown: 0 };
+    for (const s of statuses)
+        counts[s.state]++;
+    const sessions = new Set(statuses.map((s) => s.pane.sessionName)).size;
+    return dim(`${statuses.length} agent(s) across ${sessions} session(s) — ` +
+        `${counts.blocked} blocked, ${counts.working} working, ${counts.idle} idle`);
+}

package/dist/scan.js

@@ -0,0 +1,41 @@
+// One detection pass over every pane. Shared by the list, watch, and picker
+// modes. Threads per-pane memory across calls so "working" (content changed
+// since last look) and idle-debounce work in the live modes.
+import { capturePane, listPanes } from "./tmux.js";
+import { createGitCache } from "./git.js";
+import { resolveState } from "./detect.js";
+export async function scan(opts, memory) {
+    const panes = await listPanes({ all: opts.all });
+    const gitCache = createGitCache();
+    const nextMemory = new Map();
+    // Resolve concurrently but keep results in tmux pane order (session → window →
+    // pane) so the grouped view is stable across refreshes rather than ordered by
+    // whichever capture-pane happened to finish first.
+    const resolved = await Promise.all(panes.map(async (pane) => {
+        const lines = await capturePane(pane.id);
+        const resolution = resolveState(pane, lines, memory.get(pane.id));
+        if (!resolution)
+            return null; // not an agent pane
+        nextMemory.set(pane.id, resolution.memory);
+        const git = await gitCache(pane.path);
+        return {
+            pane,
+            agent: resolution.agent,
+            state: resolution.state,
+            matchedRule: resolution.matchedRule,
+            git,
+        };
+    }));
+    const statuses = resolved.filter((s) => s !== null);
+    return { statuses, memory: nextMemory };
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// Fire-once: sample twice with a short delay so "working" can be detected via
+// content change even without a persistent watcher.
+export async function scanOnce(opts, delayMs) {
+    let memory = new Map();
+    ({ memory } = await scan(opts, memory));
+    await sleep(delayMs);
+    const { statuses } = await scan(opts, memory);
+    return statuses;
+}

package/dist/tmux.js

@@ -0,0 +1,152 @@
+// tmux glue. tmux has already done the hard part for us: #{pane_current_command}
+// is the foreground process's comm, and capture-pane hands us the rendered
+// screen for free. We just ask nicely.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const exec = promisify(execFile);
+async function tmux(args) {
+    const { stdout } = await exec("tmux", args, { maxBuffer: 16 * 1024 * 1024 });
+    return stdout;
+}
+// tmux sanitizes ANY control character in -F output (including our separator and
+// even newlines) to "_", so we can't pack multiple free-text fields into one
+// formatted line. Instead we query one field per call, each paired with the
+// pane id. pane_id is always "%<digits>" — it can't contain the "|" delimiter or
+// a newline — so we split once on the first "|" and the value may then contain
+// anything (spaces, "|", unicode) without ambiguity. Keying the merge by id
+// makes it robust to the pane set changing between calls.
+async function column(scope, field) {
+    const stdout = await tmux(["list-panes", ...scope, "-F", `#{pane_id}|${field}`]);
+    const rows = [];
+    for (const line of stdout.split("\n")) {
+        if (!line)
+            continue;
+        const i = line.indexOf("|");
+        if (i < 0)
+            continue;
+        rows.push([line.slice(0, i), line.slice(i + 1)]);
+    }
+    return rows;
+}
+export async function isServerRunning() {
+    try {
+        await tmux(["list-panes", "-a"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Enumerate panes. Scope defaults to the current session when run inside tmux,
+// or all sessions with `all: true` (or when run outside tmux).
+export async function listPanes(opts) {
+    const insideTmux = Boolean(process.env.TMUX);
+    const scope = opts.all || !insideTmux ? ["-a"] : ["-s"];
+    const [commands, pids, paths, titles, sessions, windows, windowIdx, actives] = await Promise.all([
+        column(scope, "#{pane_current_command}"),
+        column(scope, "#{pane_pid}"),
+        column(scope, "#{pane_current_path}"),
+        column(scope, "#{pane_title}"),
+        column(scope, "#{session_name}"),
+        column(scope, "#{window_name}"),
+        column(scope, "#{window_index}"),
+        column(scope, "#{pane_active}"),
+    ]);
+    // Seed one PaneInfo per id from the first column, then fill from the rest.
+    // Keyed by id, so a pane appearing/vanishing mid-scan can't misalign fields.
+    const byId = new Map();
+    for (const [id] of commands) {
+        if (!byId.has(id)) {
+            byId.set(id, {
+                id,
+                command: "",
+                pid: 0,
+                path: "",
+                title: "",
+                sessionName: "",
+                windowName: "",
+                windowIndex: "",
+                active: false,
+            });
+        }
+    }
+    const fill = (rows, set) => {
+        for (const [id, value] of rows) {
+            const p = byId.get(id);
+            if (p)
+                set(p, value);
+        }
+    };
+    fill(commands, (p, v) => (p.command = v));
+    fill(pids, (p, v) => (p.pid = Number(v) || 0));
+    fill(paths, (p, v) => (p.path = v));
+    fill(titles, (p, v) => (p.title = v));
+    fill(sessions, (p, v) => (p.sessionName = v));
+    fill(windows, (p, v) => (p.windowName = v));
+    fill(windowIdx, (p, v) => (p.windowIndex = v));
+    fill(actives, (p, v) => (p.active = v === "1"));
+    return [...byId.values()];
+}
+// Capture the visible screen of a pane as plain text lines (no escape codes).
+// -p prints to stdout; trailing blank lines trimmed.
+export async function capturePane(paneId) {
+    const stdout = await tmux(["capture-pane", "-p", "-t", paneId]);
+    return stdout.replace(/\n+$/, "").split("\n");
+}
+// Move the *currently attached* tmux client to a pane: switch its session, then
+// select the window and pane. A pane id (%N) resolves up to its window/session,
+// so we only need the session name for switch-client. Use when already inside
+// tmux (process.env.TMUX set).
+export async function switchToPane(sessionName, paneId) {
+    await tmux(["switch-client", "-t", sessionName]);
+    await tmux(["select-window", "-t", paneId]);
+    await tmux(["select-pane", "-t", paneId]);
+}
+// Like switchToPane, but moves a *specific* client (by its tty) rather than the
+// current one. This is how the dashboard in one window drives another window:
+// select-window/select-pane set the agent session's active window+pane server-
+// side, and switch-client -c points that other client at it.
+export async function switchClientToPane(clientTty, sessionName, paneId) {
+    await tmux(["switch-client", "-c", clientTty, "-t", sessionName]);
+    await tmux(["select-window", "-t", paneId]);
+    await tmux(["select-pane", "-t", paneId]);
+}
+// All attached clients. Uses the same "id | value" split trick as listPanes to
+// dodge tmux's control-character sanitization; client_tty never contains "|".
+export async function listClients() {
+    let stdout = "";
+    try {
+        stdout = await tmux(["list-clients", "-F", "#{client_tty}|#{client_session}"]);
+    }
+    catch {
+        return [];
+    }
+    const clients = [];
+    for (const line of stdout.split("\n")) {
+        if (!line)
+            continue;
+        const i = line.indexOf("|");
+        if (i < 0)
+            continue;
+        clients.push({ tty: line.slice(0, i), session: line.slice(i + 1) });
+    }
+    return clients;
+}
+// The tty of the client this process is running under (best effort). Used to
+// tell "this window" apart from the others when choosing a jump target.
+export async function selfClientTty() {
+    try {
+        const tty = (await tmux(["display-message", "-p", "#{client_tty}"])).trim();
+        return tty || null;
+    }
+    catch {
+        return null;
+    }
+}
+// Pre-select the target window/pane on the server (no client needed), so a
+// subsequent `tmux attach` lands with that pane active. Use when NOT inside
+// tmux — the caller then execs `tmux attach-session -t <sessionName>`.
+export async function preselectPane(paneId) {
+    await tmux(["select-window", "-t", paneId]);
+    await tmux(["select-pane", "-t", paneId]);
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+// Core data model. The whole detection system is data, not code: manifests
+// describe how to recognize an agent and how to read its state off the rendered
+// terminal.
+export {};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@sandropadin/tend",
+  "version": "0.1.0",
+  "description": "Lightweight status detector for AI coding agents running inside tmux. Reports blocked / working / idle per pane by scraping the terminal, plus git branch state.",
+  "type": "module",
+  "bin": {
+    "tend": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/index.ts",
+    "watch": "node src/index.ts watch",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "npm run build"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.2"
+  },
+  "license": "MIT"
+}

package/src/detect.ts

@@ -0,0 +1,152 @@
+// The detection engine: identify the agent in a pane, then resolve its state by
+// arbitrating three signals:
+//   1. blocked/idle come from the screen (manifest rules),
+//   2. working comes from PTY activity (content changed since last tick),
+//   3. skipStateUpdate screens (scrollback/menus) hold the previous state.
+// Blocked is strong and wins; otherwise activity beats a stale idle read; idle
+// is debounced so a quiet frame mid-task doesn't flap the status.
+
+import { extractRegion } from "./regions.ts";
+import { manifestFor, MANIFESTS } from "./manifests.ts";
+import type { AgentState, Manifest, PaneInfo, Rule } from "./types.ts";
+
+export function identifyAgent(pane: PaneInfo, captureText: string): string | null {
+  const cmd = pane.command.toLowerCase();
+  // 1. Exact / substring command-name match (e.g. comm is literally "claude").
+  for (const m of MANIFESTS) {
+    if (m.match.some((name) => cmd === name || cmd.includes(name))) return m.agent;
+  }
+  // 2. Command-pattern match — catches Claude Code, whose comm is its version
+  //    string (e.g. "2.1.200"). Most reliable: independent of screen scroll.
+  for (const m of MANIFESTS) {
+    if (m.commandPattern && new RegExp(m.commandPattern).test(pane.command)) {
+      return m.agent;
+    }
+  }
+  // 3. Screen signature — for agents launched under a generic comm (node/python)
+  //    whose version-rename doesn't apply. Matches persistent on-screen chrome.
+  const hay = captureText.toLowerCase();
+  for (const m of MANIFESTS) {
+    if (m.signature.some((sig) => hay.includes(sig.toLowerCase()))) return m.agent;
+  }
+  return null;
+}
+
+function ruleMatches(rule: Rule, 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) {
+    const re = new RegExp(rule.regex, "im");
+    if (!re.test(regionText)) return false;
+  }
+  return true;
+}
+
+interface RuleVerdict {
+  state: AgentState;
+  ruleId: string | null;
+  hold: boolean; // skipStateUpdate matched — keep previous state
+}
+
+// Evaluate the manifest against captured lines; highest-priority match wins.
+function evaluateRules(manifest: Manifest, lines: string[]): RuleVerdict {
+  const sorted = [...manifest.rules].sort((a, b) => b.priority - a.priority);
+  for (const rule of sorted) {
+    const regionText = extractRegion(lines, rule.region);
+    if (ruleMatches(rule, regionText)) {
+      return { state: rule.state, ruleId: rule.id, hold: rule.skipStateUpdate === true };
+    }
+  }
+  return { state: "unknown", ruleId: null, hold: false };
+}
+
+// Per-pane memory the watcher threads across ticks. Fire-once mode simulates it
+// by sampling a pane twice with a short delay (see collectOnce).
+export interface PaneMemory {
+  lastCaptureHash: string;
+  lastState: AgentState;
+  pendingIdle: boolean; // idle seen once; require a second read before committing
+}
+
+export interface Resolution {
+  agent: string;
+  state: AgentState;
+  matchedRule: string | null;
+  memory: PaneMemory;
+}
+
+function hashLines(lines: string[]): string {
+  // Cheap content fingerprint — we only need "did it change", not crypto.
+  let h = 0;
+  const s = lines.join("\n");
+  for (let i = 0; i < s.length; i++) {
+    h = (Math.imul(31, h) + s.charCodeAt(i)) | 0;
+  }
+  return `${s.length}:${h}`;
+}
+
+export function resolveState(
+  pane: PaneInfo,
+  lines: string[],
+  prev: PaneMemory | undefined,
+): Resolution | null {
+  const captureText = lines.join("\n");
+  const agent = identifyAgent(pane, captureText);
+  if (agent === null) return null;
+
+  const manifest = manifestFor(agent);
+  const verdict = manifest
+    ? evaluateRules(manifest, lines)
+    : { state: "unknown" as AgentState, ruleId: null, hold: false };
+
+  const hash = hashLines(lines);
+  const changed = prev !== undefined && prev.lastCaptureHash !== hash;
+  const previousState: AgentState = prev?.lastState ?? "unknown";
+
+  let state: AgentState;
+  let pendingIdle = false;
+
+  // "blocked" must be earned by an active match every scan — never inherited.
+  // Holding it (on scrollback or an ambiguous frame) is exactly what keeps a
+  // stale "1 blocked" on the board after you've answered the prompt.
+  const keep = (prevState: AgentState): AgentState =>
+    prevState === "unknown" || prevState === "blocked" ? "idle" : prevState;
+
+  if (verdict.hold) {
+    // Scrollback / menu screen: don't author state, keep what we had.
+    state = keep(previousState);
+  } else if (verdict.state === "blocked") {
+    state = "blocked"; // strong signal, wins immediately
+  } else if (changed) {
+    state = "working"; // PTY activity is the authority for "working"
+  } else if (verdict.state === "working") {
+    state = "working"; // explicit interrupt-hint on screen
+  } else if (verdict.state === "idle") {
+    // Debounce: require idle to persist for two reads before committing, so a
+    // single quiet frame between output bursts doesn't flip us to idle.
+    if (previousState === "working" && prev?.pendingIdle !== true) {
+      state = "working";
+      pendingIdle = true;
+    } else {
+      state = "idle";
+    }
+  } else {
+    // Known agent, nothing matched: fall back without inheriting a stale block.
+    state = keep(previousState);
+  }
+
+  return {
+    agent,
+    state,
+    matchedRule: verdict.ruleId,
+    memory: { lastCaptureHash: hash, lastState: state, pendingIdle },
+  };
+}

package/src/git.ts

@@ -0,0 +1,64 @@
+// Git status by shelling out to the real `git` binary (no libgit2 dependency).
+// Cheap enough for a handful of panes; results are memoized per repo root within
+// a single tick so N panes in one repo cost one set of calls.
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { GitStatus } from "./types.ts";
+
+const exec = promisify(execFile);
+
+async function git(cwd: string, args: string[]): Promise<string | null> {
+  try {
+    const { stdout } = await exec("git", ["-C", cwd, ...args], {
+      maxBuffer: 4 * 1024 * 1024,
+    });
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+async function repoRoot(cwd: string): Promise<string | null> {
+  return git(cwd, ["rev-parse", "--show-toplevel"]);
+}
+
+async function computeStatus(cwd: string): Promise<GitStatus | null> {
+  const branch = await git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  if (branch === null) return null; // not a git repo
+
+  const porcelain = await git(cwd, ["status", "--porcelain"]);
+  const dirty = porcelain !== null && porcelain.length > 0;
+
+  let ahead = 0;
+  let behind = 0;
+  const counts = await git(cwd, [
+    "rev-list",
+    "--left-right",
+    "--count",
+    "HEAD...@{upstream}",
+  ]);
+  if (counts) {
+    const [a, b] = counts.split(/\s+/);
+    ahead = Number(a) || 0;
+    behind = Number(b) || 0;
+  }
+
+  return { branch: branch === "HEAD" ? null : branch, dirty, ahead, behind };
+}
+
+// Per-tick cache keyed by repo root, so panes sharing a repo share the answer.
+export function createGitCache() {
+  const byRoot = new Map<string, Promise<GitStatus | null>>();
+  return async function statusFor(cwd: string): Promise<GitStatus | null> {
+    const root = await repoRoot(cwd);
+    if (root === null) return null;
+    let pending = byRoot.get(root);
+    if (!pending) {
+      // Compute from the repo root so all panes agree regardless of subdir.
+      pending = computeStatus(root);
+      byRoot.set(root, pending);
+    }
+    return pending;
+  };
+}