tmux-ide 2.6.0 → 2.6.1

package/packages/daemon/src/tui/detect/manifests.ts

@@ -0,0 +1,226 @@
+/**
+ * Bundled detection manifests for known agent commands.
+ *
+ * These encode CONSERVATIVE, hand-tuned heuristics — the textual evidence
+ * seen at the bottom of a pane when an agent is blocked (waiting on input) or
+ * working (streaming/spinning). `done` is genuinely hard to read from a single
+ * snapshot, so it is left to the classifier's seen-tracking; the rules here
+ * stay minimal. Treat every matcher below as a heuristic to tune, not a
+ * contract — edit freely as agent UIs change.
+ *
+ * EVIDENCE PROVENANCE. The `claude` and `codex` manifests are tuned against
+ * REAL captured screens (see `manifest-corpus.test.ts` for the sanitized
+ * fixtures). Each matcher cites the invariant it was built from ("seen: …").
+ * The remaining manifests (`opencode`, `gemini`, `aider`, `copilot`) are
+ * best-effort from public docs/common knowledge — every one of their matchers
+ * is marked "untuned — needs real captures" and kept HIGH-PRECISION
+ * (esc-to-interrupt / spinner / explicit y-n) so they can never false-positive
+ * on a plain prompt. Users can override any of these with a JSON file in
+ * `~/.tmux-ide/agent-detection/` (see `manifest-loader.ts`).
+ */
+import type { AgentManifest } from "./manifest.ts";
+
+// Braille spinner glyphs common to CLI TUIs (claude, codex, ora, …). Scoped to
+// a single manifest's region, so it can only fire on that agent's pane.
+const BRAILLE_SPINNER = "[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏]";
+
+const CLAUDE: AgentManifest = {
+  id: "claude",
+  commands: ["claude"],
+  states: {
+    // Approval / confirmation prompts — Claude is waiting on the user.
+    // Claude's approval UI is a bordered box asking a "Do you want …?" question
+    // with a numbered arrow menu ("❯ 1. Yes" / "3. No, and tell Claude …").
+    // These phrases are approval-specific and never appear in the idle chrome
+    // (a bare "❯ " input box) or the "How is Claude doing this session?" survey
+    // (which uses "1: Bad" colon-style options, not "❯ 1.").
+    blocked: {
+      any: [
+        // seen (approval dialogs): "Do you want to proceed?" / "Do you want to
+        // make this edit to …"
+        { region: "bottom", contains: "Do you want" },
+        // seen: the highlighted first option of the numbered approval menu.
+        { region: "bottom", contains: "❯ 1." },
+        // seen: "2. Yes, and don't ask again this session"
+        { region: "bottom", contains: "Yes, and" },
+        // seen: "3. No, and tell Claude what to do differently"
+        { region: "bottom", contains: "No, and tell Claude" },
+      ],
+    },
+    // Streaming / thinking indicators. While Claude works the bottom line shows
+    // a spinner + gerund + the interrupt hint, e.g.
+    //   "✳ Cerebrating… (esc to interrupt · ctrl+t to hide todos)".
+    working: {
+      any: [
+        // seen: the interrupt hint is present for the entire duration of a turn
+        // — the single most reliable "working" invariant.
+        { region: "bottom", contains: "esc to interrupt", caseInsensitive: true },
+        // seen: the animated status verb ("Thinking…", "Cerebrating…").
+        { region: "bottom", contains: "Thinking" },
+        { region: "bottom", contains: "Cerebrating" },
+        // The leading braille spinner glyph, in the body or (rarely) the title.
+        { region: "bottom", regex: BRAILLE_SPINNER },
+        { region: "title", regex: BRAILLE_SPINNER },
+      ],
+    },
+    // done: intentionally omitted — inferred by the classifier's seen-tracking.
+    // NOTE (seen, NOT used): idle Claude shows a bordered "❯ " input box with a
+    // "⏵⏵ bypass permissions on (shift+tab to cycle) · ← for agents" or
+    // "? for shortcuts · ← for agents" footer, and finished turns leave a
+    // "✻ Brewed for 9s" summary — none of these are working/blocked evidence,
+    // so they are deliberately absent and fall through to idle.
+  },
+};
+
+const CODEX: AgentManifest = {
+  id: "codex",
+  commands: ["codex"],
+  states: {
+    blocked: {
+      any: [
+        // untuned — needs real captures. Codex approval prompts (docs/common
+        // knowledge): a command-approval question before running a shell
+        // command. Kept high-precision so it can't fire on the idle "›" box.
+        { region: "bottom", contains: "Allow command", caseInsensitive: true },
+        { region: "bottom", contains: "Do you want" },
+        { region: "bottom", contains: "approve", caseInsensitive: true },
+        { region: "bottom", contains: "(y/n)", caseInsensitive: true },
+      ],
+    },
+    working: {
+      any: [
+        // untuned for the exact string — Codex shows an elapsed-time working
+        // line with an interrupt hint while a turn runs. "esc to interrupt" is
+        // the shared CLI-TUI invariant; the spinner is the fallback.
+        { region: "bottom", contains: "esc to interrupt", caseInsensitive: true },
+        { region: "bottom", regex: BRAILLE_SPINNER },
+        { region: "title", regex: BRAILLE_SPINNER },
+      ],
+    },
+    // done: omitted. NOTE (seen, NOT used): idle Codex shows a "›" input prompt
+    // and a "gpt-5.5 high · <cwd>            Goal achieved (5m)" status line —
+    // "Goal achieved" is a finished/idle marker, not "working", so it is left
+    // out (a done rule would collapse to idle in the instant classifier anyway).
+  },
+};
+
+const OPENCODE: AgentManifest = {
+  id: "opencode",
+  commands: ["opencode"],
+  states: {
+    // untuned — needs real captures. High-precision only.
+    blocked: {
+      any: [
+        { region: "bottom", contains: "(y/n)", caseInsensitive: true },
+        { region: "bottom", contains: "[y/n]", caseInsensitive: true },
+        { region: "bottom", contains: "Do you want" },
+      ],
+    },
+    working: {
+      any: [
+        { region: "bottom", contains: "esc to interrupt", caseInsensitive: true },
+        { region: "bottom", regex: BRAILLE_SPINNER },
+        { region: "title", regex: BRAILLE_SPINNER },
+      ],
+    },
+  },
+};
+
+const GEMINI: AgentManifest = {
+  id: "gemini",
+  commands: ["gemini"],
+  states: {
+    // untuned — needs real captures. gemini-cli. High-precision only.
+    blocked: {
+      any: [
+        { region: "bottom", contains: "(y/n)", caseInsensitive: true },
+        { region: "bottom", contains: "Apply this change", caseInsensitive: true },
+        { region: "bottom", contains: "Allow execution", caseInsensitive: true },
+      ],
+    },
+    working: {
+      any: [
+        // gemini-cli shows an "(esc to cancel)" hint during a turn.
+        { region: "bottom", contains: "esc to cancel", caseInsensitive: true },
+        { region: "bottom", contains: "esc to interrupt", caseInsensitive: true },
+        { region: "bottom", regex: BRAILLE_SPINNER },
+        { region: "title", regex: BRAILLE_SPINNER },
+      ],
+    },
+  },
+};
+
+const AIDER: AgentManifest = {
+  id: "aider",
+  commands: ["aider"],
+  states: {
+    // untuned — needs real captures. aider uses "(Y)es/(N)o" confirmation
+    // prompts, which are its most reliable blocked signal.
+    blocked: {
+      any: [
+        { region: "bottom", contains: "(Y)es/(N)o", caseInsensitive: true },
+        { region: "bottom", contains: "? [Yes]", caseInsensitive: true },
+        { region: "bottom", contains: "Add file to the chat", caseInsensitive: true },
+      ],
+    },
+    // working: aider streams tokens without a stable status line, so we leave
+    // it to idle-by-default rather than risk a false positive.
+    working: {
+      any: [{ region: "bottom", regex: BRAILLE_SPINNER }],
+    },
+  },
+};
+
+const COPILOT: AgentManifest = {
+  id: "copilot",
+  commands: ["copilot", "github-copilot", "github-copilot-cli"],
+  states: {
+    // untuned — needs real captures. github-copilot-cli. High-precision only.
+    blocked: {
+      any: [
+        { region: "bottom", contains: "(y/n)", caseInsensitive: true },
+        { region: "bottom", contains: "Select an option", caseInsensitive: true },
+        { region: "bottom", contains: "Allow", caseInsensitive: false },
+      ],
+    },
+    working: {
+      any: [
+        { region: "bottom", contains: "esc to interrupt", caseInsensitive: true },
+        { region: "bottom", regex: BRAILLE_SPINNER },
+        { region: "title", regex: BRAILLE_SPINNER },
+      ],
+    },
+  },
+};
+
+const SHELL: AgentManifest = {
+  id: "shell",
+  commands: ["bash", "zsh", "sh", "fish", "nu"],
+  states: {
+    // Catch-all: a raw shell is almost always idle. We only flag an explicit
+    // interactive confirmation as blocked; "working" is unreliable to read
+    // from a shell snapshot, so it stays absent (idle by default).
+    blocked: {
+      any: [
+        { region: "bottom", contains: "[y/n]", caseInsensitive: true },
+        { region: "bottom", contains: "(yes/no)", caseInsensitive: true },
+      ],
+    },
+  },
+};
+
+/**
+ * All bundled manifests, in preference order for `pickManifest` and for the
+ * tree-walk priority in `resolveAgentCommand` (earlier = higher priority). The
+ * `shell` catch-all is intentionally LAST so a real agent that has spawned a
+ * transient shell child still resolves to the agent.
+ */
+export const BUNDLED_MANIFESTS: AgentManifest[] = [
+  CLAUDE,
+  CODEX,
+  OPENCODE,
+  GEMINI,
+  AIDER,
+  COPILOT,
+  SHELL,
+];

package/packages/daemon/src/tui/detect/process-tree.ts

@@ -0,0 +1,197 @@
+/**
+ * Process-tree resolution for the snapshot-scraping fallback.
+ *
+ * A tmux pane's `pane_current_command` is only its IMMEDIATE child process —
+ * for a real agent that is usually `node`/`bun`/`sh`, never `claude`/`codex`.
+ * So the detection manifests picked purely by `pane_current_command` almost
+ * never match in practice. To fix that we walk the pane's process TREE and
+ * resolve what is actually running underneath it.
+ *
+ * Everything here is pure except the thin `readProcessTable` io wrapper, and
+ * nothing ever throws — a missing/garbled `ps` simply yields no matches, and
+ * resolution falls back to the fast `pane_current_command` path.
+ */
+import { execFileSync } from "node:child_process";
+import { pickManifest, type AgentManifest } from "./manifest.ts";
+import { getManifests } from "./manifest-loader.ts";
+
+/** One row of the process table. */
+export interface ProcEntry {
+  pid: number;
+  ppid: number;
+  /** Full command line (argv joined), as `ps` printed it. */
+  command: string;
+}
+
+/**
+ * Parse `ps -axo pid=,ppid=,command=` output. Each line is
+ * `<pid> <ppid> <command line…>` with leading padding on the numeric columns.
+ * Malformed lines are skipped; never throws.
+ */
+export function parsePsOutput(raw: string): ProcEntry[] {
+  const entries: ProcEntry[] = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.replace(/^\s+/, "");
+    if (trimmed.length === 0) continue;
+    // pid, ppid, then the rest is the command line (which may contain spaces).
+    const match = /^(\d+)\s+(\d+)\s+(.*)$/.exec(trimmed);
+    if (!match) continue;
+    const pid = Number(match[1]);
+    const ppid = Number(match[2]);
+    const command = match[3] ?? "";
+    if (!Number.isFinite(pid) || !Number.isFinite(ppid) || command.length === 0) continue;
+    entries.push({ pid, ppid, command });
+  }
+  return entries;
+}
+
+/**
+ * Collect the command lines in the subtree rooted at `rootPid`, INCLUDING the
+ * root process itself. Deeper (more specific) processes come FIRST — a DFS that
+ * emits children before their parent — so the most-specific agent command is
+ * seen before the generic `node`/`bun`/`sh` shims above it. Cycles and runaway
+ * depth are guarded.
+ */
+export function subtreeCommands(entries: ProcEntry[], rootPid: number, maxDepth = 6): string[] {
+  const childrenByParent = new Map<number, ProcEntry[]>();
+  const byPid = new Map<number, ProcEntry>();
+  for (const entry of entries) {
+    byPid.set(entry.pid, entry);
+    const siblings = childrenByParent.get(entry.ppid) ?? [];
+    siblings.push(entry);
+    childrenByParent.set(entry.ppid, siblings);
+  }
+
+  const root = byPid.get(rootPid);
+  if (!root) return [];
+
+  const commands: string[] = [];
+  const visited = new Set<number>();
+
+  const walk = (pid: number, depth: number): void => {
+    if (depth > maxDepth || visited.has(pid)) return;
+    visited.add(pid);
+    // Emit children first (deepest → shallowest) so the root lands last.
+    for (const child of childrenByParent.get(pid) ?? []) {
+      walk(child.pid, depth + 1);
+    }
+    const self = byPid.get(pid);
+    if (self) commands.push(self.command);
+  };
+
+  walk(rootPid, 0);
+  return commands;
+}
+
+/**
+ * Read the live process table. Thin io wrapper — on any failure returns `[]`
+ * so callers degrade to the fast path rather than throwing.
+ */
+export function readProcessTable(): ProcEntry[] {
+  try {
+    const raw = execFileSync("ps", ["-axo", "pid=,ppid=,command="], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2000,
+    });
+    return parsePsOutput(raw);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Extract the candidate tokens a command line should be matched against.
+ *
+ * Full argv strings can incidentally contain an agent name (a path like
+ * `/Users/x/.claude/notes.md`, or `vim ~/.codex/todo`), which would produce a
+ * false positive if we ran `pickManifest` over the raw string. Instead we test
+ * only the meaningful executable-ish tokens: the basename of argv[0] and the
+ * basename of the second token (a script/subcommand path). Query strings and
+ * flags are ignored.
+ *
+ * e.g. `node /Users/x/.nvm/versions/node/v20/bin/claude --foo` → ["node", "claude"]
+ *      `vim /Users/x/.claude/notes.md`                          → ["vim", "notes.md"]
+ */
+export function commandTokens(command: string): string[] {
+  const parts = command.trim().split(/\s+/).filter(Boolean);
+  const tokens: string[] = [];
+  const argv0 = parts[0];
+  if (argv0) tokens.push(basename(argv0));
+  const argv1 = parts[1];
+  // Only treat the second token as a script path when it is not a flag.
+  if (argv1 && !argv1.startsWith("-")) tokens.push(basename(argv1));
+  return tokens;
+}
+
+/** Path basename without the node:path import — splits on `/` and takes the tail. */
+function basename(pathLike: string): string {
+  const segments = pathLike.split("/");
+  return segments[segments.length - 1] ?? pathLike;
+}
+
+/**
+ * Resolve which agent manifest is actually running in a pane.
+ *
+ * 1. Fast path: `pane_current_command` may already BE the agent (e.g. `claude`
+ *    via a shim). Try `pickManifest(paneCmd)` directly.
+ * 2. Tree path: otherwise walk the pane's process subtree and match extracted
+ *    tokens against the manifests. Token extraction avoids the incidental-path
+ *    false positives described above.
+ *
+ * The tree walk prefers the highest-PRIORITY manifest (its index in
+ * `manifests`, which is preference-ordered: claude, codex, …, then the `shell`
+ * catch-all) over merely the deepest match — an agent that has spawned a
+ * transient shell child (a Bash tool call) must still resolve to the agent, not
+ * to `shell`. Depth (deepest first) only breaks ties within the same manifest.
+ *
+ * Resolution order:
+ *   0. HINT — `opts.hint` (the pane's `@agent_hint` option): if it names a
+ *      known manifest it WINS outright. This is the sandbox/wrapper escape
+ *      hatch, set with `tmux set-option -p @agent_hint claude`.
+ *   1. FAST — `pane_current_command` may already be the agent (a shim).
+ *   2. TREE — walk the process subtree and match extracted tokens.
+ *
+ * `manifests` defaults to the loaded set (bundled + user overrides).
+ * `matchedCommand` is the token/command that produced the hit and `source`
+ * records which path won — both surfaced by `agent explain`. Returns an
+ * undefined manifest when nothing matches.
+ */
+export type ResolveSource = "hint" | "fast" | "tree" | "none";
+
+export function resolveAgentCommand(
+  paneCmd: string,
+  panePid: number,
+  table: ProcEntry[],
+  opts: { manifests?: AgentManifest[]; hint?: string } = {},
+): { manifest: AgentManifest | undefined; matchedCommand: string; source: ResolveSource } {
+  const manifests = opts.manifests ?? getManifests();
+
+  // 0. Hint: a per-pane @agent_hint forces a manifest, bypassing resolution.
+  const hint = opts.hint?.trim();
+  if (hint) {
+    const hinted = pickManifest(hint, manifests);
+    if (hinted) return { manifest: hinted, matchedCommand: hint, source: "hint" };
+  }
+
+  const fast = pickManifest(paneCmd, manifests);
+  if (fast) return { manifest: fast, matchedCommand: paneCmd, source: "fast" };
+
+  let best: { manifest: AgentManifest; matchedCommand: string; rank: number } | undefined;
+  for (const command of subtreeCommands(table, panePid)) {
+    for (const token of commandTokens(command)) {
+      const hit = pickManifest(token, manifests);
+      if (!hit) continue;
+      const rank = manifests.indexOf(hit);
+      // Keep the first (deepest) match at a given rank; only replace when a
+      // strictly higher-priority manifest turns up.
+      if (!best || rank < best.rank) best = { manifest: hit, matchedCommand: token, rank };
+      if (best.rank === 0)
+        return { manifest: best.manifest, matchedCommand: best.matchedCommand, source: "tree" };
+    }
+  }
+
+  return best
+    ? { manifest: best.manifest, matchedCommand: best.matchedCommand, source: "tree" }
+    : { manifest: undefined, matchedCommand: "", source: "none" };
+}

package/packages/daemon/src/tui/detect/snapshot.ts

@@ -0,0 +1,70 @@
+/**
+ * Pane snapshot reader for agent-state detection.
+ *
+ * Reads the bottom-buffer text of a tmux pane and normalizes it into a
+ * `PaneSnapshot` — the raw evidence later detectors classify into
+ * blocked/working/done/idle. The parsing (`parseSnapshot`) is pure and
+ * unit-tested; `readPaneSnapshot` is the thin tmux I/O wrapper.
+ */
+import { captureRecent } from "@tmux-ide/tmux-bridge";
+
+export interface PaneSnapshot {
+  /** Last N non-empty lines, ANSI-stripped, trailing whitespace trimmed. */
+  bottomNonEmpty: string[];
+  /** ANSI-stripped joined snapshot text. */
+  text: string;
+  /** Original raw capture, kept for ansi-format debugging. */
+  raw: string;
+}
+
+// Well-known ANSI escape matcher (ansi-regex): SGR/cursor CSI sequences plus
+// OSC strings terminated by BEL.
+/* eslint-disable no-control-regex */
+const ANSI =
+  /[›][[\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\d/#&.:=?%@~_]+)*|[a-zA-Z\d]+(?:;[-a-zA-Z\d/#&.:=?%@~_]*)*)?)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]))/g;
+
+/* eslint-enable no-control-regex */
+
+/** Strip ANSI escape sequences from a string. */
+function stripAnsi(input: string): string {
+  return input.replace(ANSI, "");
+}
+
+const DEFAULT_LINES = 20;
+
+/**
+ * Normalize raw pane text into a `PaneSnapshot`. Pure — never throws.
+ *
+ * @param raw Raw pane capture (may contain ANSI escapes).
+ * @param opts.lines Number of trailing non-empty lines to keep (default 20).
+ */
+export function parseSnapshot(raw: string, opts: { lines?: number } = {}): PaneSnapshot {
+  const lines = opts.lines ?? DEFAULT_LINES;
+  const text = stripAnsi(raw ?? "");
+
+  const nonEmpty = text
+    .split("\n")
+    .map((line) => line.replace(/\s+$/, ""))
+    .filter((line) => line.length > 0);
+
+  const bottomNonEmpty = lines > 0 ? nonEmpty.slice(-lines) : [];
+
+  return { bottomNonEmpty, text, raw: raw ?? "" };
+}
+
+/**
+ * Capture a pane's recent buffer and parse it into a `PaneSnapshot`.
+ * On any tmux error, returns an empty snapshot rather than throwing.
+ *
+ * @param target tmux pane target (session, window, or pane id).
+ * @param opts.lines Number of trailing non-empty lines to keep (default 20).
+ */
+export function readPaneSnapshot(target: string, opts: { lines?: number } = {}): PaneSnapshot {
+  const lines = opts.lines ?? DEFAULT_LINES;
+  try {
+    const raw = captureRecent(target, lines);
+    return parseSnapshot(raw, { lines });
+  } catch {
+    return { bottomNonEmpty: [], text: "", raw: "" };
+  }
+}

package/packages/daemon/src/tui/integrations/claude.ts

@@ -0,0 +1,176 @@
+/**
+ * Claude Code integration — the authoritative detection layer.
+ *
+ * Claude Code has a first-class hooks system. `tmux-ide integration install
+ * claude` writes a tiny POSIX hook script and registers it in the user's
+ * `~/.claude/settings.json` for the lifecycle events we care about. Each hook
+ * invocation stamps the CURRENT tmux pane with a pane-local user option:
+ *
+ *   @agent_state       "<working|blocked|done|idle>:<unix epoch>"
+ *   @agent_session_id  the Claude session id (future: --resume on restore)
+ *
+ * The detector treats a fresh `@agent_state` as GROUND TRUTH and only falls
+ * back to screen-manifest scraping when no authority is present — the same
+ * two-layer model the best agent terminals use. Any other agent can join the
+ * authority layer by writing the same option (`tmux set-option -p
+ * @agent_state working:$(date +%s)`) — no integration required.
+ *
+ * The settings merge is surgical and reversible: entries are tagged by the
+ * hook-script path, a one-time backup is written next to settings.json, and
+ * uninstall removes exactly our entries.
+ */
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/** Marker every installed hook command contains — the removal key. */
+export const HOOK_SCRIPT_RELPATH = ".tmux-ide/hooks/claude-state.sh";
+
+export function hookScriptPath(): string {
+  return join(homedir(), HOOK_SCRIPT_RELPATH);
+}
+
+/**
+ * Absolute path to Claude Code's settings file: `TMUX_IDE_CLAUDE_SETTINGS` when
+ * set (tests / per-run overrides), else `~/.claude/settings.json`. The override
+ * lets install/offer flows be exercised against a scratch file so a test never
+ * reads or rewrites the user's real settings.
+ */
+export function claudeSettingsPath(): string {
+  return process.env.TMUX_IDE_CLAUDE_SETTINGS ?? join(homedir(), ".claude", "settings.json");
+}
+
+/**
+ * The hook script. POSIX sh, no dependencies. Claude Code passes the event
+ * payload as JSON on stdin; the state to report comes in as $1 (each settings
+ * entry passes its own state, so the script never parses the event name).
+ * Outside tmux ($TMUX_PANE unset) it exits quietly. The session id is
+ * extracted with sed — good enough for a flat JSON string field.
+ */
+export const HOOK_SCRIPT = `#!/bin/sh
+# tmux-ide agent-state hook (installed by: tmux-ide integration install claude)
+# $1 = state to report: working | blocked | done | idle
+state="\${1:-idle}"
+payload="$(cat 2>/dev/null || true)"
+[ -n "$TMUX_PANE" ] || exit 0
+tmux set-option -p -t "$TMUX_PANE" @agent_state "\${state}:$(date +%s)" 2>/dev/null || exit 0
+sid="$(printf '%s' "$payload" | sed -n 's/.*"session_id"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p' | head -1)"
+[ -n "$sid" ] && tmux set-option -p -t "$TMUX_PANE" @agent_session_id "$sid" 2>/dev/null
+exit 0
+`;
+
+/** Claude Code lifecycle events → the state each reports. */
+export const EVENT_STATES: Array<{ event: string; state: string; matcher?: string }> = [
+  { event: "UserPromptSubmit", state: "working" },
+  { event: "PreToolUse", state: "working", matcher: "*" },
+  { event: "Notification", state: "blocked" },
+  { event: "Stop", state: "done" },
+  { event: "SessionEnd", state: "idle" },
+];
+
+interface HookCommand {
+  type: "command";
+  command: string;
+}
+interface HookGroup {
+  matcher?: string;
+  hooks: HookCommand[];
+}
+type HooksConfig = Record<string, HookGroup[]>;
+export type ClaudeSettings = Record<string, unknown> & { hooks?: HooksConfig };
+
+/** Does a hook group belong to us? (its command references our script) */
+function isOurs(group: HookGroup): boolean {
+  return group.hooks?.some((h) => h.command?.includes(HOOK_SCRIPT_RELPATH)) ?? false;
+}
+
+/**
+ * PURE — return a copy of `settings` with our hook entries merged in.
+ * Idempotent: existing tmux-ide entries are replaced, everything else is
+ * preserved untouched.
+ */
+export function mergeHooks(settings: ClaudeSettings, scriptPath: string): ClaudeSettings {
+  const next: ClaudeSettings = { ...settings, hooks: { ...(settings.hooks ?? {}) } };
+  const hooks = next.hooks as HooksConfig;
+  for (const { event, state, matcher } of EVENT_STATES) {
+    const existing = (hooks[event] ?? []).filter((g) => !isOurs(g));
+    const group: HookGroup = {
+      ...(matcher !== undefined ? { matcher } : {}),
+      hooks: [{ type: "command", command: `${scriptPath} ${state}` }],
+    };
+    hooks[event] = [...existing, group];
+  }
+  return next;
+}
+
+/** PURE — return a copy of `settings` with exactly our entries removed. */
+export function removeHooks(settings: ClaudeSettings): ClaudeSettings {
+  if (!settings.hooks) return { ...settings };
+  const hooks: HooksConfig = {};
+  for (const [event, groups] of Object.entries(settings.hooks)) {
+    const kept = groups.filter((g) => !isOurs(g));
+    if (kept.length > 0) hooks[event] = kept;
+  }
+  const next: ClaudeSettings = { ...settings, hooks };
+  if (Object.keys(hooks).length === 0) delete next.hooks;
+  return next;
+}
+
+/** PURE — is our integration present in these settings? */
+export function isInstalled(settings: ClaudeSettings): boolean {
+  return Object.values(settings.hooks ?? {}).some((groups) => groups.some(isOurs));
+}
+
+function readSettings(path: string): ClaudeSettings {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as ClaudeSettings;
+  } catch {
+    throw new Error(`${path} is not valid JSON — fix or move it, then retry`);
+  }
+}
+
+/**
+ * Install: write the hook script, back up settings.json once, merge our
+ * entries. Takes effect for NEW Claude Code sessions (hooks are read at
+ * session start).
+ */
+export function installClaudeIntegration(): { scriptPath: string; settingsPath: string } {
+  const script = hookScriptPath();
+  mkdirSync(dirname(script), { recursive: true });
+  writeFileSync(script, HOOK_SCRIPT, "utf8");
+  chmodSync(script, 0o755);
+
+  const settingsPath = claudeSettingsPath();
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  const settings = readSettings(settingsPath);
+  const backup = `${settingsPath}.tmux-ide.bak`;
+  if (existsSync(settingsPath) && !existsSync(backup)) copyFileSync(settingsPath, backup);
+  writeFileSync(settingsPath, `${JSON.stringify(mergeHooks(settings, script), null, 2)}\n`, "utf8");
+  return { scriptPath: script, settingsPath };
+}
+
+/** Uninstall: remove exactly our entries (script file is left, it's inert). */
+export function uninstallClaudeIntegration(): { settingsPath: string; wasInstalled: boolean } {
+  const settingsPath = claudeSettingsPath();
+  const settings = readSettings(settingsPath);
+  const wasInstalled = isInstalled(settings);
+  if (wasInstalled) {
+    writeFileSync(settingsPath, `${JSON.stringify(removeHooks(settings), null, 2)}\n`, "utf8");
+  }
+  return { settingsPath, wasInstalled };
+}
+
+export function claudeIntegrationStatus(): { installed: boolean; scriptExists: boolean } {
+  return {
+    installed: isInstalled(readSettings(claudeSettingsPath())),
+    scriptExists: existsSync(hookScriptPath()),
+  };
+}