claude-term-tabs 0.0.0-bootstrap

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emma Coutu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# claude-term-tabs
+
+Find a running Claude Code session by what you remember about it, and switch to its terminal tab.
+
+```bash
+ctt working on pause in claude-term-tabs
+# → Pause sessions before a restart · claude-term-tabs · tab 4
+```
+
+Works with iTerm2 and WezTerm on macOS.
+
+## Install
+
+Needs Node 24 or later. `fzf` is optional; without it the picker is a numbered list.
+
+```bash
+npm install --global claude-term-tabs   # installs both claude-term-tabs and ctt
+npx claude-term-tabs pause              # or run it without installing
+```
+
+To run it from a clone instead, link the clone with `npm link`.
+
+The first switch in iTerm2 asks macOS for permission to control iTerm2. Allow it, or grant it
+later in System Settings > Privacy & Security > Automation.
+
+### Tab completion
+
+`ctt completion zsh` or `ctt completion bash` prints a completion script (plain `ctt completion` picks
+the shell from `$SHELL`). Append it to your shell's startup file:
+
+```bash
+ctt completion zsh >> ~/.zshrc     # after compinit runs
+ctt completion bash >> ~/.bashrc   # bash 4 or later
+```
+
+Tab then completes ctt's subcommands (`pause`, `resume`, `completion`) as the first word, each one's
+flags, and the terminal names after `--terminal`; after `--snapshot` it falls back to file names. It
+never completes session titles. The script completes both `ctt` and `claude-term-tabs`. Installed with npm, it runs
+`claude-term-tabs` from your `PATH`, so completion needs a global install (`npx` alone isn't enough). Run from a
+clone, it runs ctt from where it was when you generated the script, so generate it again if you move the clone.
+
+## Usage
+
+```
+ctt [query...] [--list] [--all] [--json] [--no-llm] [--terminal iterm2|wezterm]
+```
+
+| Situation | What happens |
+|-----------|--------------|
+| One clear local match | Switches to its tab |
+| Several plausible matches | Asks Haiku to rank them, then shows a picker (or switches if Haiku picks exactly one) |
+| No query | Picker over every live session, most recent first |
+| `--list` | Prints matches, never switches |
+| `--all` | Also searches closed sessions; choosing one resumes it in a new tab |
+| `--json` | Machine-readable output, for debugging; no format promise |
+| `--no-llm` | Local matching only |
+| Not in iTerm2 or WezTerm | Uses whichever one is running, else lists without switching |
+
+The search looks at each session's title, repo, worktree, branch and your first and last prompt.
+
+## Pause and resume
+
+Before restarting the machine:
+
+```bash
+ctt pause                # ask every session to wrap up and write a HANDOFF
+ctt pause --auto-close   # also exit each session and close its tab once its HANDOFF is in
+ctt pause --timeout 20   # wait up to 20 minutes (default 10)
+```
+
+`ctt pause` records every live session to a snapshot first, then types the stop prompt into each
+one and shows the sessions it is still waiting on, refreshed every 3 seconds. Enter or a
+double-click jumps to that session's tab; ctrl-r re-sends the stop prompt; Esc stops waiting.
+When the list empties it prints `Safe to restart.`
+
+| State | Meaning |
+|-------|---------|
+| busy | Working; its transcript is still growing |
+| may need you | Busy for 2 minutes with no new output, probably a permission prompt |
+| idle, no HANDOFF | Stopped without writing a HANDOFF; re-send or check it |
+| in shell mode | Its input is in shell mode, so ctt will not type into it |
+| can't reach | Not in a supported terminal pane |
+| exited | The process ended without a HANDOFF |
+| exit failed | `--auto-close` sent `/exit` but the session did not end |
+
+ctt only ever types the stop prompt and, with `--auto-close`, `/exit` followed by `exit` for the
+shell left behind. It never answers a permission prompt or interrupts a busy session, and it never
+closes a session that has not written a HANDOFF. Sessions without one are still recorded.
+
+After restarting:
+
+```bash
+ctt resume               # reopen every recorded session in its window and tab order
+ctt resume --dry-run     # print the commands instead
+ctt resume --no-prompt   # reopen without sending the resume prompt
+```
+
+Sessions already running are skipped, so running it twice is harmless. Snapshots live in
+`~/.local/state/claude-term-tabs/snapshots/` and are pruned after 30 days. `ctt resume` uses the newest;
+`--snapshot FILE` picks another.
+
+## Config
+
+`~/.config/claude-term-tabs/config.json`, every key optional:
+
+```json
+{
+  "resumeCommand": "claude --dangerously-skip-permissions --resume {id}",
+  "stopPrompt": "Pausing for a machine restart. ...",
+  "resumePrompt": "Resumed after a machine restart. ...",
+  "pauseTimeoutMinutes": 10,
+  "excludeDirs": ["~/.claude-mem/observer-sessions"]
+}
+```
+
+`excludeDirs` leaves closed sessions out of `--all` when their working directory (the one ctt
+shows and resumes in) is one of those directories or below one. Live sessions are always listed.
+
+## Cost and speed
+
+Measured on 2026-11-10 with 19 live sessions:
+
+| Path | Time | Tokens |
+|------|------|--------|
+| Local match | ~0.65 s | none |
+| Haiku fallback (15 sessions sent) | ~4 s | ~2,300 input, ~250 output (about $0.0006) |
+| `--all` first run (1,626 transcripts indexed) | ~4 s plus any Haiku call | none |
+| `--all` cached | adds ~40 ms | none |
+
+Haiku runs through `claude -p` with no tools, no MCP servers, no settings, a short system prompt,
+and `--no-session-persistence`, so its calls never show up as sessions.
+
+Digests are cached in `~/.cache/claude-term-tabs/digests.json` (owner-only), keyed by transcript size
+and modification time. Delete it any time.
+
+## Development
+
+```bash
+npm ci          # installs the commit hooks (husky + commitlint)
+npm run check   # type-check
+npm test
+```
+
+No runtime dependencies; Node runs the TypeScript directly. [CONTRIBUTING.md](CONTRIBUTING.md) has the commit and
+pull request rules.
+
+### Releases
+
+Every push to `main` runs CI, then semantic-release reads the conventional commit
+messages since the last tag and, when any warrant it, tags the next version (`fix:` patch,
+`feat:` minor, `BREAKING CHANGE:` major), adds the notes to [CHANGELOG.md](CHANGELOG.md) and
+publishes a GitHub release. Nothing is published to npm, and `package.json` keeps a placeholder
+version; the git tag is the version.
+
+### Manual checks
+
+iTerm2:
+
+1. `ctt --list <words from a tab title>` prints that tab with the right `tab N`.
+2. `ctt <words from a tab title>` switches to it.
+3. `ctt claude-term-tabs` (or any phrase matching two sessions) opens the fzf picker; Enter switches.
+4. `ctt --all <words from a closed session>` resumes it in a new tab.
+
+WezTerm: the same four checks, run inside WezTerm.
+
+Pause and resume:
+
+1. `ctt resume --dry-run` after a `ctt pause` lists every session in tab order.
+2. `ctt pause` with two scratch sessions shows them leaving the list as they write HANDOFFs.
+3. One full restart cycle: `ctt pause --auto-close`, restart, `ctt resume`.

package/bin/claude-term-tabs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { existsSync, realpathSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const root = dirname(dirname(realpathSync(process.argv[1])))
+const argv = process.argv.slice(2)
+// A checkout runs the TypeScript in src/; the npm package ships only dist/, because Node won't strip types under node_modules.
+const fromSrc = existsSync(join(root, 'src')) && !root.split('/').includes('node_modules')
+const src = file => pathToFileURL(fromSrc ? join(root, 'src', file) : join(root, 'dist', file.replace(/\.ts$/, '.js'))).href
+const { COMPLETE_FLAG, answerCompletion } = await import(src('complete.ts'))
+if (argv[0] === COMPLETE_FLAG) {
+  // A Tab press: answer without loading the rest of ctt.
+  const { lineWriter } = await import(src('output.ts'))
+  process.exitCode = answerCompletion(argv.slice(1), { stdout: lineWriter(1), stderr: lineWriter(2) })
+} else {
+  const { main } = await import(src('cli.ts'))
+  process.exitCode = await main(argv)
+}

package/dist/args.js

@@ -0,0 +1,171 @@
+import { parseArgs } from 'node:util';
+import { shellQuote } from "./shell.js";
+import { TERMINAL_NAMES } from "./terminals/adapter.js";
+const HELP_FLAG = { short: 'h', describe: 'show this help' };
+/** Flags of the search, `ctt [query...]`. */
+export const SEARCH_FLAGS = {
+    list: { describe: 'print matches, never switch' },
+    all: { describe: 'include closed sessions (choosing one resumes it in a new tab)' },
+    json: { describe: 'machine-readable output (implies --list)' },
+    'no-llm': { describe: 'local matching only, never call Haiku' },
+    terminal: { value: 'NAME', describe: `${TERMINAL_NAMES.join(' | ')} (default: detected)`, choices: TERMINAL_NAMES },
+    help: HELP_FLAG
+};
+/** Flags of `ctt pause`. */
+export const PAUSE_FLAGS = {
+    'auto-close': { describe: 'also exit each session and close its tab after its HANDOFF' },
+    timeout: { value: 'MIN', describe: 'minutes to wait (default: pauseTimeoutMinutes, else 10)' },
+    help: HELP_FLAG
+};
+/** Flags of `ctt resume`. */
+export const RESUME_FLAGS = {
+    'dry-run': { describe: 'print the commands instead' },
+    'no-prompt': { describe: 'reopen without sending the resume prompt' },
+    snapshot: { value: 'FILE', describe: 'use this snapshot instead of the latest' },
+    help: HELP_FLAG
+};
+/** Shells `ctt completion` writes a script for. */
+export const SHELLS = ['bash', 'zsh'];
+export function isShell(s) {
+    return SHELLS.some(x => x === s);
+}
+/** The public subcommands. The internal `_focus` and `_send-stop` are deliberately not here. */
+export const COMMANDS = {
+    pause: { describe: 'before a restart, record live sessions and ask each for a HANDOFF', flags: PAUSE_FLAGS },
+    resume: { describe: 'after a restart, reopen recorded sessions in window and tab order', flags: RESUME_FLAGS },
+    completion: { describe: `print the tab-completion script for ${SHELLS.join(' or ')} (default: from $SHELL)`, flags: { help: HELP_FLAG }, args: `[${SHELLS.join('|')}]` }
+};
+export function isCommand(word) {
+    return word !== undefined && Object.hasOwn(COMMANDS, word);
+}
+/** The hidden first argument the completion scripts call ctt with: `ctt --complete <shell> <words>`. */
+export const COMPLETE_FLAG = '--complete';
+/**
+ * Parse `argv` against `flags` with `node:util` `parseArgs` in strict mode: unknown flags, a value
+ * given to a boolean flag and a missing value throw, and so do positionals unless `positionals` is set.
+ */
+export function parseFlags(argv, flags, opts = {}) {
+    const options = Object.fromEntries(Object.entries(flags).map(([name, f]) => [name, {
+            ...(f.value !== undefined ? { type: 'string' } : { type: 'boolean', default: false }),
+            ...(f.short !== undefined ? { short: f.short } : {})
+        }]));
+    const { values, positionals } = parseArgs({ args: argv, options, strict: true, allowPositionals: opts.positionals === true });
+    return { values: values, positionals };
+}
+/** The flag whose value is being completed, if any: `--terminal x`, bash's `--terminal = x`, or zsh's `--terminal=x`. */
+function valueBeingCompleted(before, current) {
+    const joined = /^--([^=]+)=(.*)$/.exec(current);
+    if (joined !== null)
+        return { flag: joined[1], value: joined[2], prefix: `--${joined[1]}=` };
+    const [flag, value] = current === '=' ? [before.at(-1), ''] : before.at(-1) === '=' ? [before.at(-2), current] : [before.at(-1), current];
+    return flag?.startsWith('--') === true ? { flag: flag.slice(2), value, prefix: '' } : undefined;
+}
+/** `name` for bash; for zsh's `_describe`, `name` with its colons escaped, then `:description` if any. */
+export function entry(shell, name, describe) {
+    if (shell === 'bash')
+        return name;
+    const escaped = name.replaceAll(':', '\\:');
+    return describe === undefined ? escaped : `${escaped}:${describe}`;
+}
+/** Names of the flags already on the line, however given: `--name`, `--name=value`, or a short `-h`. */
+function given(before, flags) {
+    const names = new Set();
+    for (const word of before) {
+        if (word.startsWith('--'))
+            names.add(word.slice(2).split('=')[0]);
+        else if (/^-[^-]/.test(word)) {
+            for (const short of word.slice(1)) {
+                const name = Object.entries(flags).find(([, f]) => f.short === short)?.[0];
+                if (name !== undefined)
+                    names.add(name);
+            }
+        }
+    }
+    return names;
+}
+/**
+ * Answer the completion script's `ctt --complete <shell> <words>`, where `words` is the command line up
+ * to the word being completed (the program name first). Subcommands are offered only as the first word;
+ * flags (long form) when the word starts with `-`, minus those already given; a flag that takes a value
+ * offers its choices or nothing, so the shell falls back to file names; nothing after `--`.
+ */
+export function completions(shell, words) {
+    const typed = words.slice(1);
+    const current = typed.at(-1) ?? '';
+    const before = typed.slice(0, -1);
+    if (before.includes('--'))
+        return [];
+    const command = isCommand(before[0]) ? before[0] : undefined;
+    const flags = command !== undefined ? COMMANDS[command].flags : SEARCH_FLAGS;
+    const value = valueBeingCompleted(before, current);
+    const flag = value !== undefined && Object.hasOwn(flags, value.flag) ? flags[value.flag] : undefined;
+    if (value !== undefined && flag?.value !== undefined) {
+        return (flag.choices ?? []).filter(c => c.startsWith(value.value)).map(c => entry(shell, value.prefix + c));
+    }
+    if (current.startsWith('-')) {
+        const already = given(before, flags);
+        return Object.entries(flags)
+            .filter(([name]) => `--${name}`.startsWith(current) && !already.has(name))
+            .map(([name, f]) => entry(shell, `--${name}`, f.describe));
+    }
+    if (before.length === 0) {
+        return Object.entries(COMMANDS).filter(([name]) => name.startsWith(current)).map(([name, c]) => entry(shell, name, c.describe));
+    }
+    if (command === 'completion' && before.length === 1)
+        return SHELLS.filter(s => s.startsWith(current)).map(s => entry(shell, s));
+    return [];
+}
+/**
+ * The completion script for `shell`. It registers both `ctt` and `claude-term-tabs`, and runs `program`
+ * (ctt's own path) to answer each request. Adapted from yargs' scripts (MIT).
+ */
+export function completionScript(shell, program) {
+    const ctt = `${shellQuote(program)} ${COMPLETE_FLAG} ${shell}`;
+    if (shell === 'zsh') {
+        return `#compdef ctt claude-term-tabs
+###-begin-ctt-completions-###
+#
+# ctt tab completion for zsh. Install: ctt completion zsh >> ~/.zshrc (after compinit)
+#
+_ctt_completions()
+{
+  local reply
+  local si=$IFS
+  IFS=$'\\n' reply=($(${ctt} "\${words[@]:0:$CURRENT}"))
+  IFS=$si
+  if [[ \${#reply} -gt 0 ]]; then
+    _describe 'values' reply
+  else
+    # nothing to offer: complete file names, after the = of --flag=value
+    [[ $PREFIX == --*=* ]] && compset -P '*='
+    _default
+  fi
+}
+if [[ "\${zsh_eval_context[-1]}" == "loadautofunc" ]]; then
+  _ctt_completions "$@"
+else
+  compdef _ctt_completions ctt claude-term-tabs
+fi
+###-end-ctt-completions-###`;
+    }
+    return `###-begin-ctt-completions-###
+#
+# ctt tab completion for bash 4 or later. Install: ctt completion bash >> ~/.bashrc
+#
+_ctt_completions()
+{
+    local cur_word type_list
+    cur_word="\${COMP_WORDS[COMP_CWORD]}"
+    # bash splits --terminal=w into --terminal, = and w
+    [[ $cur_word == = ]] && cur_word=''
+    mapfile -t type_list < <(${ctt} "\${COMP_WORDS[@]:0:COMP_CWORD+1}")
+    # nothing to offer: leave COMPREPLY empty so bash completes file names
+    if [[ \${#type_list[@]} -eq 0 ]]; then
+      COMPREPLY=()
+      return 0
+    fi
+    mapfile -t COMPREPLY < <(compgen -W "$( printf '%q ' "\${type_list[@]}" )" -- "\${cur_word}")
+}
+complete -o bashdefault -o default -F _ctt_completions ctt claude-term-tabs
+###-end-ctt-completions-###`;
+}

package/dist/cache.js

@@ -0,0 +1,76 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { writeOwnerOnly } from "./fsutil.js";
+const CACHE_VERSION = 1;
+/** Digest cache keyed by transcript path, valid while the file's size and mtime are unchanged. */
+export class DigestCache {
+    file;
+    entries;
+    seen = new Set();
+    dirty = false;
+    constructor(file, entries) {
+        this.file = file;
+        this.entries = entries;
+    }
+    /** Load the cache; a missing file is empty, a corrupt one is discarded with one warning. */
+    static load(file, warn) {
+        let raw;
+        try {
+            raw = readFileSync(file, 'utf8');
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                warn(`claude-term-tabs: cache unreadable (${err.message}), rebuilding`);
+            return new DigestCache(file, new Map());
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed.version !== CACHE_VERSION || typeof parsed.entries !== 'object' || parsed.entries === null) {
+                return new DigestCache(file, new Map());
+            }
+            return new DigestCache(file, new Map(Object.entries(parsed.entries)));
+        }
+        catch {
+            warn(`claude-term-tabs: cache at ${file} is corrupt, rebuilding`);
+            return new DigestCache(file, new Map());
+        }
+    }
+    /** Cached digest for `path`, or the result of `extract` when stale. Missing files are never cached. */
+    get(path, extract) {
+        let stat;
+        try {
+            stat = statSync(path);
+        }
+        catch {
+            return extract();
+        }
+        this.seen.add(path);
+        const hit = this.entries.get(path);
+        if (hit !== undefined && hit.size === stat.size && hit.mtimeMs === stat.mtimeMs)
+            return hit.digest;
+        const digest = extract();
+        this.entries.set(path, { size: stat.size, mtimeMs: stat.mtimeMs, digest });
+        this.dirty = true;
+        return digest;
+    }
+    /** Paths looked up through `get` during this run. */
+    touched() {
+        return new Set(this.seen);
+    }
+    /** Drop every entry whose path is not in `paths` (call after a full listing). */
+    retainOnly(paths) {
+        for (const key of [...this.entries.keys()]) {
+            if (!paths.has(key)) {
+                this.entries.delete(key);
+                this.dirty = true;
+            }
+        }
+    }
+    /** Write the cache atomically when anything changed. */
+    save() {
+        if (!this.dirty && existsSync(this.file))
+            return;
+        const body = { version: CACHE_VERSION, entries: Object.fromEntries(this.entries) };
+        writeOwnerOnly(this.file, JSON.stringify(body));
+        this.dirty = false;
+    }
+}