termcut 1.0.1 → 1.0.3

package/README.md

@@ -1,38 +1,45 @@
 # tcut
 
-Turn a terminal session into a video. Record it live or script it in TypeScript; render to MP4, GIF, SVG, HTML — identical every time.
+Terminal videos, written in TypeScript. Record a session live or script it, then render it to MP4, GIF, WebM, SVG or HTML — the same recording gives the same pixels every time.
 
 ![tcut demo](https://raw.githubusercontent.com/AmanVarshney01/tcut/main/packages/tcut/docs/demo.gif)
 
+[tcut.amanv.dev](https://tcut.amanv.dev) · [Reference](https://github.com/AmanVarshney01/tcut/blob/main/packages/tcut/docs/REFERENCE.md) · [Examples](https://github.com/AmanVarshney01/tcut/tree/main/packages/tcut/examples) · [llms.txt](https://tcut.amanv.dev/llms.txt)
+
 ## Install
 
 ```sh
-bun add -g termcut     # Bun ≥ 1.4 · installs the `tcut` command
+bun add -g termcut        # Bun ≥ 1.4 · installs the `tcut` command
 ```
 
-Standalone binaries for macOS, Linux and Windows (all tested in CI): [Releases](https://github.com/AmanVarshney01/tcut/releases). MP4/GIF need `ffmpeg`; SVG/HTML don't. Linux and Windows render pixels through Chrome/Chromium.
+Or a standalone binary for macOS, Linux or Windows from [Releases](https://github.com/AmanVarshney01/tcut/releases) — all three are tested in CI.
+
+- MP4, GIF, WebM, WebP need `ffmpeg` on the PATH. SVG, HTML and text outputs need nothing.
+- Linux and Windows render pixels through Chrome or Chromium (`BUN_CHROME_PATH` to point at one).
 
-## Use
+## Record
 
-Record what you do:
+**Live.** Your own shell opens — prompt, config, aliases; type; `exit`. You get the video, the exact recording (`demo.cast`) and an editable script of what you typed (`demo.video.ts`): it reopens your shell (`shell: "user"`), waits for your prompt (`promptPattern`, detected from the recording) and replays the commands as `run()` calls. `--clean` opens a plain shell with a `>` prompt instead.
 
 ```sh
-tcut rec -o demo.gif                    # opens a shell, records until you `exit`
-tcut rec -o demo.mp4 -- npm create vite # or just one command
+tcut rec -o demo.gif
+tcut rec -o demo.mp4 -- npm create vite     # one command, ends when it exits
 ```
 
-You get `demo.gif`, the exact recording (`demo.cast`) and an editable script (`demo.video.ts`) of what you typed.
+`-- command` runs through that same shell, so `tcut rec -- ls` records what *your* `ls` shows — aliases, functions, fish abbreviations and colours included. `--raw` runs the binary directly.
 
-Or script it:
+**Scripted.** Plain TypeScript, so loops, helpers and imports work, and the script lives in the repo next to the code it shows.
 
 ```ts
 // demo.video.ts
 import { defineVideo } from "tcut";
 
-export default defineVideo({ output: "demo.gif" }, async (t) => {
-  await t.run("bun --version");     // type, Enter, wait for the prompt
-  await t.expect(/1\.\d+/);         // assert on the screen
-  await t.sleep("1s");
+export default defineVideo({ output: ["demo.mp4", "demo.gif"] }, async (t) => {
+  await t.run("bun --version");       // types it, presses Enter, waits for the prompt
+  await t.run("ls -la");
+  await t.expect(/package\.json/);    // asserts on the screen — the demo is a test
+  await t.snapshot("files.png");      // a still of this exact moment
+  await t.sleep("1.5s");
 });
 ```
 
@@ -40,57 +47,107 @@ export default defineVideo({ output: "demo.gif" }, async (t) => {
 tcut demo.video.ts
 ```
 
-Record a real browser next to (or over) the terminal, for dev-server demos:
+What a script can do, one line each:
 
-```ts
-defineVideo({ output: "demo.mp4", browser: { position: "overlay" } }, async (t) => {
-  await t.run("bun run dev </dev/null >/tmp/dev.log 2>&1 &");
-  await t.browser.goto("http://localhost:5173");
-  await t.run("sed -i '' 's/Hello/Hi/' src/App.tsx");   // HMR updates the page
-  await t.focus("browser");
-});
-```
-
-Polish: `shadow: true`, `watermark: "© you"`, `marginFill: "transparent"` (real alpha in PNG/WebP/GIF/WebM/SVG), `title: "auto"` follows the title the program sets, `keys: true` shows key presses, `maxPause: "800ms"` cuts dead air, `t.timelapse(fn, { speed: 8 })` fast-forwards an install, `t.zoom({ rows: [0, 5] })` magnifies output, `t.chapter("Install")` adds mp4 chapters, `t.snapshot("hero.png")` (or `.svg`) saves a still of that exact moment on every render, `preset: "x"` sizes it for X.
+| | |
+|---|---|
+| `run(cmd)` | waits for your prompt to come back, not for a timer |
+| `wait(/re/)` · `expect(/re/)` | observe or assert the screen — including lines that already scrolled away (`{ scope: "scrollback" }`) |
+| `type` · `enter` · arrows · `ctrl("c")` · `key("f5")` | keys, sent the way the running program asked for them |
+| `hide(fn)` | runs setup off-camera; the state stays |
+| `snapshot("x.png" \| "x.svg")` | a pixel or vector still of that exact moment, written on every render |
+| `chapter(name)` | mp4 chapters, and cut points for `--chapters` / `--split-chapters` |
+| `print(markdown)` · `title(text)` | captions rendered into the terminal, nothing typed |
+| `zoom({ rows, cols })` | magnifies a region; `keys: true` shows what was pressed |
+| `timelapse(fn, { speed })` | fast-forwards an install or a build, not just the silence |
+| `browser` | a real browser window beside or over the terminal (below) |
 
-Faithful to the terminal: arrows switch to the form vim/less asked for, `t.paste()` uses bracketed paste (no autoindent stair-steps), synchronized-output repaints never show torn frames, and OSC 8 hyperlinks — including Markdown links in `t.print()` captions — stay clickable in SVG and HTML output.
+The full surface is in the [reference](https://github.com/AmanVarshney01/tcut/blob/main/packages/tcut/docs/REFERENCE.md).
 
-Test and inspect: `tcut diff a.cast b.cast` catches output changes in CI, `t.expect(/…/, { scope: "scrollback" })` checks output that scrolled away (`-o demo.log` writes the whole transcript), and `tcut doctor demo.cast` tells you what a recording used — and what can't be rendered (inline images).
+## Render again
 
-Cut and join without re-recording — on the cast, so every format works:
+Recording and rendering are separate. A recording is an asciicast; frames are computed on a virtual clock. So a new theme, size or format never re-runs a shell — and cuts, joins and chapter splits happen on the recording, which is why they work for SVG as well as MP4.
 
 ```sh
-tcut render demo.cast --from 2s --to 10s -o clip.gif     # a window of the video
-tcut render demo.cast --split-chapters -o demo.mp4       # one file per t.chapter()
+tcut render demo.cast --theme "Gruvbox Dark" -o demo.svg -o demo.html
+tcut render demo.cast --width 1280 --height 720 --speed 1.5 -o demo.mp4
+tcut render demo.cast --from 2s --to 10s --shadow --watermark "@you" -o clip.gif
+tcut render demo.cast --split-chapters --margin-fill transparent -o demo.webm
 tcut concat intro.cast demo.cast --gap 500ms -o launch.mp4
+tcut themes                                   # ~600 themes, Ghostty's collection
 ```
 
-Re-render any recording without re-running it — ~600 themes ([Ghostty's collection](https://github.com/mbadolato/iTerm2-Color-Schemes)), `tcut themes` lists them:
+Outputs by extension: `.mp4` `.gif` `.webm` `.webp` · `.svg` (animated, real text) · `.html` (single-file player) · `.png` `.jpg` (final frame) · `.txt` (final screen) · `.log` (full transcript) · `dir/` (PNG frames).
+
+## Faithful to the terminal
+
+The emulator is Ghostty's core, so what tcut sees is what your terminal would show — and what it records is what the program actually received.
+
+- Arrow keys and pastes arrive exactly as the running program asked: application cursor mode, bracketed paste.
+- Links printed with OSC 8 — including Markdown links in `print()` captions — stay clickable in SVG and HTML.
+- Frames are never torn: synchronized-output blocks are captured whole.
+- Symbols the font lacks (progress blocks, Nerd Font icons) stay on their cell, so status bars never drift.
+- `tcut doctor demo.cast` explains what a recording used, and what cannot be rendered (inline images).
+
+## Test it
 
 ```sh
-tcut render demo.cast --theme "Gruvbox Dark" -o demo.svg
+tcut test demo.video.ts        # runs the script with no delays — just the assertions
+tcut diff a.cast b.cast        # catches output changes between two recordings
 ```
 
-Share it:
+`expect()` makes a demo a test. `tcut test` runs it fast, and exits non-zero when the screen does not match — so the same script that renders your README video can guard it in CI.
+
+## A browser next to the terminal
+
+For dev-server demos: the page is recorded on the same clock and composited beside or over the terminal.
+
+```ts
+defineVideo({ output: "demo.mp4", browser: { position: "overlay" } }, async (t) => {
+  await t.run("bun run dev </dev/null >/tmp/dev.log 2>&1 &");
+  await t.browser.goto("http://localhost:5173");
+  await t.run("sed -i '' 's/Hello/Hi/' src/App.tsx");   // HMR updates the page
+  await t.focus("browser");
+});
+```
+
+## Share it
 
 ```sh
-tcut publish --setup        # once: your S3-compatible bucket (RustFS, MinIO, R2, S3)
+tcut publish --setup        # once: your own S3-compatible bucket (RustFS, MinIO, R2, S3)
 tcut publish demo.gif       # → https://…/3f9a1c2b7d4e/demo.gif
 ```
 
-## Agents
+There is no hosted service; you bring the bucket.
+
+## For agents
 
 ```sh
-npx skills add AmanVarshney01/tcut   # tcut + tcut-remotion skills for Claude Code, Cursor, etc.
+npx skills add AmanVarshney01/tcut   # skills for Claude Code, Cursor, Codex, …
 ```
 
-Two skills: `tcut` (record terminal videos) and `tcut-remotion` (compose tcut footage into launch videos with [Remotion](https://remotion.dev)). Plus [llms.txt](https://tcut.amanv.dev/llms.txt) and `--json` everywhere.
+Two skills: `tcut` (record terminal videos) and `tcut-remotion` (compose tcut footage into a launch video with [Remotion](https://remotion.dev)). Every command has `--json`, exit codes and no prompts; [llms.txt](https://tcut.amanv.dev/llms.txt) is the condensed guide.
+
+## Compared with VHS
+
+[VHS](https://github.com/charmbracelet/vhs) is the reference point and the inspiration. Where tcut differs:
+
+- **Scripts are TypeScript** — loops, imports, shared scenes, autocomplete — instead of a `.tape` DSL.
+- **Waits on the screen** — `run()` returns when your prompt is back; VHS sleeps for a guessed duration.
+- **Rendering never re-runs the shell** — a new theme, size or format is computed from the recording. VHS screenshots Chrome live, so output depends on machine speed.
+- **Demos are tests** — `expect()` asserts on the screen; `tcut test` runs them in CI.
+- **Same emulator as your terminal** — Ghostty's core in WASM, its themes, plus SVG and HTML outputs that need no ffmpeg or browser.
+
+## How it works
+
+1. **Record.** `Bun.Terminal` runs your shell in a PTY. Every byte is timestamped into a `.cast`.
+2. **Watch.** The same bytes feed a headless [Ghostty](https://ghostty.org) (via [wterm](https://github.com/vercel-labs/wterm)). That is how `run()` knows the prompt is back and `expect()` sees what you see.
+3. **Render.** The cast replays into the same terminal inside `Bun.WebView`, one frame per tick, straight to ffmpeg. SVG and HTML are built from the terminal grid, no browser involved.
 
 ## More
 
-- [Examples](https://github.com/AmanVarshney01/tcut/tree/main/packages/tcut/examples) — driving an interactive TUI, recording Claude Code / Codex
+- [Examples](https://github.com/AmanVarshney01/tcut/tree/main/packages/tcut/examples) — driving an interactive TUI, recording Claude Code and Codex
 - [Reference](https://github.com/AmanVarshney01/tcut/blob/main/packages/tcut/docs/REFERENCE.md) — every CLI flag and script option
-- [llms.txt](https://tcut.amanv.dev/llms.txt) — the same, condensed for coding agents (`--json` gives machine-readable results)
 - [tcut.amanv.dev](https://tcut.amanv.dev)
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termcut",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Script terminal sessions in TypeScript, render them to reproducible MP4/GIF/WebM/SVG/HTML with Bun.",
   "license": "MIT",
   "author": "Aman Varshney",

package/src/cli.ts

@@ -6,6 +6,8 @@ import { readCast, writeCast } from "./cast";
 import { applyOverrides, resolveConfig } from "./config";
 import * as api from "./index";
 import { recordLive } from "./live";
+import { detectPromptPattern } from "./promptguess";
+import { throughShell, userShell } from "./usershell";
 import { ensurePublicBucket, loadPublishConfig, publicUrlFor, publishFiles, savePublishConfig, type PublishConfig, type Published } from "./publish";
 import { diffCasts, type DiffResult } from "./diff";
 import { diagnoseCast, formatDoctorReport, type DoctorReport } from "./doctor";
@@ -70,6 +72,8 @@ Options (override the script's config):
       --gap <dur>          concat: still time between parts
       --preset <name>      readme | x | youtube | square
       --browser <url>      rec: record a browser window too (--browser-position right|left|top|bottom|overlay)
+      --clean              rec: a clean shell with a plain > prompt instead of your own (also: run -- command bare)
+      --raw                rec: run -- command as a bare binary, not through your shell (no aliases/functions)
       --at <seconds>       diff: compare the screen at this time instead of the end
       --images <dir>       diff: also write a.png / b.png
       --cast <path>        where to read/write the .cast
@@ -130,6 +134,8 @@ const { values, positionals } = parseArgs({
     cast: { type: "string" },
     "record-only": { type: "boolean" },
     "no-script": { type: "boolean" },
+    raw: { type: "boolean" },
+    clean: { type: "boolean" },
     force: { type: "boolean" },
     setup: { type: "boolean" },
     open: { type: "boolean" },
@@ -470,12 +476,29 @@ async function main(): Promise<void> {
       const overrides = overridesFromFlags();
       const rawOutputs = overrides.output ?? ["rec.mp4"];
       const outputs = Array.isArray(rawOutputs) ? rawOutputs : [rawOutputs];
-      const config = resolveConfig({ ...overrides, output: outputs, cast: overrides.cast });
-      const command = rest.length > 0 ? rest : undefined;
+      // The shell tcut was typed into is the session (your prompt, config, aliases) and what `-- cmd` runs
+      // through. --clean / --raw opt out: a plain shell with a `>` prompt, or the bare binary.
+      const shell = values.clean || values.raw ? null : userShell();
+      const config = resolveConfig({ ...overrides, output: outputs, cast: overrides.cast, ...(rest.length === 0 && shell && { shell: "user" }) });
+      let command: string[] | undefined;
+      let portable: string[] | undefined;
+      if (rest.length > 0) {
+        if (shell) {
+          const through = throughShell(rest, shell);
+          command = through.argv;
+          portable = through.portable;
+          log(dim(`  via ${shell.name} — your aliases and functions apply (--raw runs the binary directly)`));
+        } else {
+          command = rest;
+        }
+      } else if (shell) {
+        log(dim(`  your ${shell.name}, with its config (--clean for a plain shell with a > prompt)`));
+      }
       // Size: --cols/--rows if given, else derived from --width/--height, else the terminal tcut runs in.
       const sized = overrides.width !== undefined || overrides.height !== undefined;
       const recording = await recordLive(config, {
         command,
+        describe: rest.length > 0 ? rest.join(" ") : shell ? `your ${shell.name}` : undefined,
         log,
         cols: overrides.cols ?? (sized ? config.cols : undefined),
         rows: overrides.rows ?? (sized ? config.rows : undefined),
@@ -488,7 +511,9 @@ async function main(): Promise<void> {
       ok(`wrote ${config.cast}`, `${recording.events.length} events, ${(recording.header.duration ?? 0).toFixed(1)}s`);
       if (!values["no-script"]) {
         const scriptPath = config.cast.replace(/\.cast$/, "") + ".video.ts";
-        await Bun.write(scriptPath, generateScript(recording, { output: outputs, cleanShell: !command, command, castPath: config.cast }));
+        // A session in the user's own shell replays with run(): wait for whatever their prompt ends with.
+        const promptPattern = !command && config.shell === "user" ? ((await detectPromptPattern(recording, config.core)) ?? undefined) : undefined;
+        await Bun.write(scriptPath, generateScript(recording, { output: outputs, cleanShell: !command, command: portable ?? command, castPath: config.cast, promptPattern }));
         ok(`wrote ${scriptPath}`, "editable script — tweak it, then `tcut " + scriptPath + "`");
       }
       if (values["record-only"]) {

package/src/config.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { USER_PROMPT_PATTERN } from "./promptguess";
 import { toMs } from "./duration";
 import { applyPreset } from "./presets";
 import { resolveTheme } from "./themes";
@@ -83,7 +84,7 @@ export function resolveConfig(input: VideoConfig): ResolvedConfig {
     cast: config.cast ?? castDefault,
     shell: config.shell ?? "bash",
     prompt,
-    promptPattern: (config.promptPattern ?? defaultPromptPattern(prompt)).source,
+    promptPattern: (config.promptPattern ?? (config.shell === "user" ? new RegExp(USER_PROMPT_PATTERN) : defaultPromptPattern(prompt))).source,
     cwd: config.cwd ?? process.cwd(),
     env: config.env ?? {},
     cols: cols ?? 80,

package/src/live.ts

@@ -1,6 +1,7 @@
 import { startBrowserCapture } from "./browser";
 import { MARKER } from "./cast";
 import { shellSetup } from "./recorder";
+import { CURSOR_QUERY, hasCursorReport, stripTerminalReplies } from "./replies";
 import type { CastEvent, Recording, ResolvedConfig } from "./types";
 
 /** What live recording needs from a keystroke source: `process.stdin`, or any readable stream (a PassThrough in tests). */
@@ -24,6 +25,8 @@ export interface LiveOptions {
   /** Keystroke source (default: this process's stdin, switched to raw mode when it is a TTY). */
   stdin?: LiveStdin | null;
   log?: (message: string) => void;
+  /** How to name the command in status lines (defaults to the argv). */
+  describe?: string;
 }
 
 /**
@@ -40,10 +43,11 @@ export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {})
   const events: CastEvent[] = [];
   const startedAt = performance.now();
 
-  const stamp = (): number => {
-    const t = (performance.now() - startedAt) / 1000;
-    return config.quantize ? Math.ceil(t * config.fps - 1e-6) / config.fps : Number(t.toFixed(6));
-  };
+  const stampAt = (seconds: number): number => (config.quantize ? Math.ceil(seconds * config.fps - 1e-6) / config.fps : Number(seconds.toFixed(6)));
+  const elapsed = (): number => (performance.now() - startedAt) / 1000;
+  const stamp = (): number => stampAt(elapsed());
+  // The program asked where the cursor is: the next position report on stdin is the terminal's answer, not a key.
+  let cursorQueried = false;
   const push = (type: CastEvent[1], data: string): void => {
     events.push([stamp(), type, data]);
   };
@@ -72,6 +76,7 @@ export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {})
       data(_terminal, chunk) {
         const text = decoder.decode(chunk, { stream: true });
         if (!text) return;
+        if (text.includes(CURSOR_QUERY)) cursorQueried = true;
         stdout.write(chunk);
         push("o", text);
       },
@@ -88,7 +93,12 @@ export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {})
   const onData = (chunk: Buffer | string): void => {
     if (exited || terminal.closed) return;
     terminal.write(chunk);
-    push("i", chunk instanceof Uint8Array ? chunk.toString("utf8") : chunk);
+    // Everything goes to the program, but only keystrokes are recorded: the terminal's answers to its queries
+    // would otherwise show up as key chips and be typed back on replay.
+    const text = chunk instanceof Uint8Array ? chunk.toString("utf8") : chunk;
+    const keys = stripTerminalReplies(text, { cursorQueried });
+    if (cursorQueried && hasCursorReport(text)) cursorQueried = false;
+    if (keys) push("i", keys);
   };
   const onResize = (): void => {
     const c = process.stdout.columns ?? cols;
@@ -104,11 +114,13 @@ export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {})
     stdin.on("data", onData);
   }
   process.on("SIGWINCH", onResize);
-  log(`recording ${setup.cmd.join(" ")} at ${cols}×${rows} — ${opts.command ? "ends when the command exits" : "type exit to stop"}`);
+  log(`recording ${opts.describe ?? setup.cmd.join(" ")} at ${cols}×${rows} — ${opts.command ? "ends when the command exits" : "type exit to stop"}`);
 
   try {
     await Promise.race([exitedPromise, proc.exited]);
-    push("m", MARKER.end);
+    // Hold the final screen for `endPause`, like a scripted recording does — otherwise a command that exits in
+    // 20 ms (`tcut rec -- ls`) becomes a three-frame video. The timeline is virtual: stamp it, don't sleep.
+    events.push([stampAt(elapsed() + config.endPause / 1000), "m", MARKER.end]);
   } finally {
     await browser?.stop();
     const emitter: NodeJS.EventEmitter = process; // @types/bun's process.off() lacks the signal overload; the generic emitter has it

package/src/promptguess.ts

@@ -0,0 +1,34 @@
+import { loadCore } from "./screen";
+import type { Recording } from "./types";
+
+const escapeRegExp = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** Prompts end in a symbol: what a generated script waits for when the user's own shell is recorded. */
+export const USER_PROMPT_PATTERN = "[❯>$%#»➜λ]\\s*$";
+
+/**
+ * What the user's prompt ends with, read from the recording: the text up to the cursor just before the first
+ * keystroke is the prompt; its final symbol (`❯`, `$`, `%`, …) is what `run()` should wait for. Replaying through
+ * the headless core handles right-hand prompts and cursor movement that a plain text scan would misread.
+ */
+export async function detectPromptPattern(rec: Recording, core: "ghostty" | "lite" = "ghostty"): Promise<string | null> {
+  const firstInput = rec.events.findIndex((e) => e[1] === "i");
+  const before = (firstInput < 0 ? rec.events : rec.events.slice(0, firstInput)).filter((e) => e[1] === "o");
+  if (before.length === 0) return null;
+  const term = await loadCore(core);
+  term.init(rec.header.width, rec.header.height);
+  for (const e of before) term.writeString(e[2]);
+  const { row, col } = term.getCursor();
+  let line = "";
+  for (let x = 0; x < col; x++) {
+    const cell = term.getCell(row, x);
+    if (cell.width === 0) continue;
+    line += cell.chars ?? (cell.char === 0 ? " " : String.fromCodePoint(cell.char));
+  }
+  const trimmed = line.trimEnd();
+  if (!trimmed) return null;
+  const ender = [...trimmed].at(-1)!;
+  // A letter or digit is not a prompt symbol (a bare path, say); fall back to the generic pattern.
+  if (/[\p{L}\p{N}]/u.test(ender)) return null;
+  return `${escapeRegExp(ender)}\\s*$`;
+}

package/src/recorder.ts

@@ -1,4 +1,5 @@
 import { MarkdownRenderer } from "@wterm/markdown";
+import { userShell } from "./usershell";
 import { startBrowserCapture, type BrowserCapture } from "./browser";
 import { MARKER } from "./cast";
 import { toMs } from "./duration";
@@ -45,6 +46,13 @@ export function shellSetup(config: ResolvedConfig): ShellSetup {
   const { shell, prompt } = config;
   if (Array.isArray(shell)) return { cmd: shell, env: {} };
   switch (shell) {
+    case "user": {
+      // The user's own shell, interactive + login, so its config, prompt and aliases apply. No known shell
+      // (Windows, or tcut launched from something that is not bash/zsh/fish) → the clean bash below.
+      const own = userShell();
+      if (own) return { cmd: [own.path, "-il"], env: {} };
+      return shellSetup({ ...config, shell: "bash" });
+    }
     case "bash":
       return {
         cmd: ["bash", "--norc", "--noprofile"],

package/src/replies.ts

@@ -0,0 +1,37 @@
+// Answers a terminal sends to a program's queries — device attributes, kitty keyboard flags, colours via OSC,
+// XTGETTCAP via DCS, cursor position reports. In a live recording they arrive on stdin together with the
+// user's keystrokes, but they are not keystrokes: the key overlay must not show them and a replay must not
+// type them (tcut answers the queries itself then).
+
+const ESC = String.fromCharCode(0x1b);
+const BEL = String.fromCharCode(0x07);
+
+const REPLIES = new RegExp(
+  [
+    `${ESC}\\[\\?[\\d;]*[cu]`, // primary DA, kitty keyboard flags
+    `${ESC}\\[>[\\d;]*c`, // secondary DA
+    `${ESC}\\][\\d;]*[^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)`, // OSC (colour queries)
+    `${ESC}P[^${ESC}]*${ESC}\\\\`, // DCS (XTGETTCAP)
+  ].join("|"),
+  "g",
+);
+
+/** Cursor position report `ESC [ row ; col R` — the same bytes as a modified F3 key (`ESC [ 1 ; 2-8 R`). */
+const CPR = new RegExp(`${ESC}\\[\\d+;\\d+R`, "g");
+/** A CPR whose parameters cannot be a modifier-encoded F3: row other than 1, or a "modifier" outside 2–8. */
+const UNAMBIGUOUS_CPR = new RegExp(`${ESC}\\[(?!1;[2-8]R)\\d+;\\d+R`, "g");
+
+/** The program asked for the cursor position; the next CPR-shaped input is an answer, not a key. */
+export const CURSOR_QUERY = `${ESC}[6n`;
+
+export interface StripOptions {
+  /** The program asked `ESC[6n`, so any CPR in this chunk is a reply; without it, only unambiguous reports are removed. */
+  cursorQueried?: boolean;
+}
+
+export function stripTerminalReplies(input: string, opts: StripOptions = {}): string {
+  return input.replace(REPLIES, "").replace(opts.cursorQueried ? CPR : UNAMBIGUOUS_CPR, "");
+}
+
+/** Does this input chunk carry a cursor position report (or the look-alike modified F3)? */
+export const hasCursorReport = (input: string): boolean => new RegExp(CPR.source).test(input);

package/src/scriptgen.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { stripTerminalReplies } from "./replies";
 import { keySequence } from "./keys";
 import type { Recording } from "./types";
 
@@ -9,6 +10,8 @@ export interface ScriptGenOptions {
   cleanShell: boolean;
   /** The command that was recorded in `-- command` mode (becomes `shell: [...]`). */
   command?: string[];
+  /** Regex source `run()` should wait for — detected from the user's prompt when their own shell was recorded. */
+  promptPattern?: string;
   /** Gaps between keystrokes longer than this become `sleep()` calls. Default 400 ms. */
   pauseThresholdMs?: number;
   /** Where the cast lives, for the header comment. */
@@ -128,6 +131,7 @@ function formatMs(ms: number): string {
 
 const q = (s: string) => JSON.stringify(s);
 
+
 /** Turn the `i` (input) events of a recording into a list of script operations. */
 export function eventsToOps(rec: Recording, opts: ScriptGenOptions): Op[] {
   const threshold = opts.pauseThresholdMs ?? 400;
@@ -163,7 +167,7 @@ export function eventsToOps(rec: Recording, opts: ScriptGenOptions): Op[] {
     }
     lastTime = time;
 
-    for (const token of tokenize(data)) {
+    for (const token of tokenize(stripTerminalReplies(data))) {
       if (token.length > 1 && token[0]! >= " ") {
         pendingText += token;
         continue;
@@ -240,6 +244,7 @@ export function generateScript(rec: Recording, opts: ScriptGenOptions): string {
   const config: string[] = [`output: ${JSON.stringify(opts.output)}`];
   if (opts.command) config.push(`shell: ${JSON.stringify(opts.command)}`);
   else if (cfg && cfg.shell !== "bash") config.push(`shell: ${JSON.stringify(cfg.shell)}`);
+  if (opts.promptPattern) config.push(`promptPattern: /${opts.promptPattern.replace(/\//g, "\\/")}/`);
   config.push(`cols: ${rec.header.width}`, `rows: ${rec.header.height}`);
   if (cfg) {
     if (cfg.theme?.name) config.push(`theme: ${q(cfg.theme.name)}`);
@@ -251,8 +256,10 @@ export function generateScript(rec: Recording, opts: ScriptGenOptions): string {
   const body = ops.length ? ops.map((op) => `    ${opToLine(op)}`).join("\n") : "    // (no input was recorded)";
   const castNote = opts.castPath ? ` The exact recording is in ${path.basename(opts.castPath)}.` : "";
   const modeNote = opts.command
-    ? "It runs the same command and replays your keys; waits are the pauses you took, so adjust them if the program is slower elsewhere."
-    : "Typed commands became run(), which waits for the prompt instead of guessing.";
+    ? "It opens the same program and replays your keys; waits are the pauses you took, so adjust them if it is slower elsewhere."
+    : cfg?.shell === "user"
+      ? "It opens your own shell; typed commands became run(), which waits for your prompt (promptPattern) instead of guessing."
+      : "Typed commands became run(), which waits for the prompt instead of guessing.";
 
   return `import { defineVideo } from "tcut";
 

package/src/types.ts

@@ -29,7 +29,8 @@ export interface Theme {
  */
 export type ThemeName = "catppuccin-mocha" | "dracula" | "github-dark" | "tokyo-night" | "one-dark" | (string & {});
 
-export type ShellName = "bash" | "zsh" | "fish" | "sh";
+/** `user` is the shell tcut was launched from (interactive login, with its config); the others are clean shells with the configured prompt. */
+export type ShellName = "bash" | "zsh" | "fish" | "sh" | "user";
 /** Terminal emulator core: libghostty (full VT, answers queries) or wterm's lite Zig core (faster, fewer features). */
 export type CoreName = "ghostty" | "lite";
 export type WindowBar = "none" | "colorful" | "colorfulRight" | "rings" | "ringsRight";

package/src/usershell.ts

@@ -0,0 +1,203 @@
+import path from "node:path";
+
+// `tcut rec` should record what the user sees in their own terminal: their shell, with its prompt, aliases,
+// functions, abbreviations and colour settings. Running the bare binary or a clean shell gives none of that
+// ("Executable not found" for an alias, plain output for a coloured one).
+
+export interface UserShell {
+  path: string;
+  /** bash | zsh | fish — the shells whose `-ic <command>` / `-il` forms load the interactive config. */
+  name: string;
+}
+
+const INTERACTIVE_SHELLS = new Set(["bash", "zsh", "fish"]);
+
+interface ParentProcess {
+  /** Executable as reported by `ps -o comm=` (login shells show a leading dash: "-fish"). */
+  command: string;
+  /** Full command line as reported by `ps -o args=`. */
+  args: string;
+}
+
+/** The process that launched tcut (macOS/Linux `ps`). Null when that cannot be read. */
+function parentProcess(): ParentProcess | null {
+  const field = (name: string): string => Bun.spawnSync(["ps", "-o", `${name}=`, "-p", String(process.ppid)], { env: process.env }).stdout.toString().trim();
+  try {
+    const command = field("comm");
+    if (!command) return null;
+    return { command, args: field("args") };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Is this shell invocation the user's interactive session, rather than a script runner? A shell running a
+ * script (`bash run.sh`) or a one-liner (`bash -c …`) is not the shell the user lives in — its rc files and
+ * aliases are the wrong ones — so only flag-only invocations (`fish`, `-zsh`, `/bin/bash -il`) count.
+ */
+export function isInteractiveInvocation(comm: string, args: string): boolean {
+  if (comm.startsWith("-")) return true; // login shell
+  const words = args.split(/\s+/).filter(Boolean);
+  const rest = words[0] && !words[0].startsWith("-") ? words.slice(1) : words; // drop argv[0] if present
+  for (const w of rest) {
+    if (w === "-c" || !w.startsWith("-")) return false;
+  }
+  return true;
+}
+
+/**
+ * The shell the user typed tcut into: the parent process when it is an interactive bash/zsh/fish, else $SHELL.
+ * Null on Windows or when neither is a known shell.
+ */
+export function userShell(): UserShell | null {
+  if (process.platform === "win32") return null;
+  const candidates: string[] = [];
+  const parent = parentProcess();
+  if (parent) {
+    const comm = parent.command.replace(/^-/, "");
+    if (INTERACTIVE_SHELLS.has(path.basename(comm)) && isInteractiveInvocation(parent.command, parent.args)) candidates.push(comm);
+  }
+  if (process.env.SHELL) candidates.push(process.env.SHELL);
+  for (const candidate of candidates) {
+    const name = path.basename(candidate);
+    if (!INTERACTIVE_SHELLS.has(name)) continue;
+    const resolved = candidate.includes("/") ? candidate : Bun.which(candidate);
+    if (resolved) return { path: resolved, name };
+  }
+  return null;
+}
+
+/** One argument, single-quoted for the given shell. POSIX shells take everything literally; fish reads `\'` and `\\`. */
+export function quoteArg(arg: string, shellName: string): string {
+  if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(arg)) return arg;
+  const inner = shellName === "fish" ? arg.replace(/\\/g, "\\\\").replace(/'/g, "\\'") : arg.replace(/'/g, `'\\''`);
+  return `'${inner}'`;
+}
+
+export function shellQuote(args: string[], shellName: string): string {
+  return args.map((a) => quoteArg(a, shellName)).join(" ");
+}
+
+export interface FishAbbreviation {
+  name: string;
+  expansion: string;
+}
+
+/** Fish's own quoting, as `abbr --show` prints it: bare, '…' (escapes \' \\) or "…" (escapes \" \\ \$). */
+function fishTokens(line: string): string[] {
+  const out: string[] = [];
+  let cur = "";
+  let quote: "'" | '"' | null = null;
+  let inWord = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i]!;
+    if (quote) {
+      if (ch === "\\" && i + 1 < line.length) {
+        const next = line[i + 1]!;
+        const escapable = quote === "'" ? "\\'" : '\\"$';
+        if (escapable.includes(next)) {
+          cur += next;
+          i++;
+          continue;
+        }
+      }
+      if (ch === quote) quote = null;
+      else cur += ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch;
+      inWord = true;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      if (inWord) out.push(cur);
+      cur = "";
+      inWord = false;
+      continue;
+    }
+    cur += ch;
+    inWord = true;
+  }
+  if (inWord) out.push(cur);
+  return out;
+}
+
+/**
+ * One `abbr --show` line → the abbreviation it declares, or null for the kinds that cannot be expanded up
+ * front (regex names, function-computed expansions, anywhere-position). `--set-cursor` markers are removed.
+ */
+export function parseAbbrLine(line: string): FishAbbreviation | null {
+  const tokens = fishTokens(line.trim());
+  if (tokens[0] !== "abbr") return null;
+  let cursorMarker: string | null = null;
+  let i = 1;
+  for (; i < tokens.length; i++) {
+    const t = tokens[i]!;
+    if (t === "--") {
+      i++;
+      break;
+    }
+    if (t === "-a" || t === "--add" || t === "-g" || t === "--global" || t === "-U" || t === "--universal") continue;
+    if (t === "--regex" || t === "--function" || t === "-f" || t === "--command") return null;
+    if (t === "--position") {
+      if (tokens[i + 1] !== "command") return null;
+      i++;
+      continue;
+    }
+    if (t.startsWith("--position=")) {
+      if (t !== "--position=command") return null;
+      continue;
+    }
+    if (t === "--set-cursor") {
+      cursorMarker = "%";
+      continue;
+    }
+    if (t.startsWith("--set-cursor=")) {
+      cursorMarker = t.slice("--set-cursor=".length) || "%";
+      continue;
+    }
+    if (t.startsWith("--regex=") || t.startsWith("--function=") || t.startsWith("--command=")) return null;
+    if (t.startsWith("-")) continue; // unknown flag: ignore
+    break; // name without a `--` separator (older fish)
+  }
+  const name = tokens[i];
+  const expansion = tokens[i + 1];
+  if (!name || expansion === undefined) return null;
+  return { name, expansion: cursorMarker ? expansion.split(cursorMarker).join("") : expansion };
+}
+
+/**
+ * fish abbreviations expand only at the prompt, never in `fish -c`; expand a leading one ourselves. The list is
+ * read from an interactive fish, because the stock config.fish declares them inside `if status is-interactive`.
+ */
+export function fishAbbreviation(shell: UserShell, word: string): string | null {
+  if (shell.name !== "fish") return null;
+  try {
+    // env is passed explicitly: Bun.spawnSync otherwise uses the environment as it was at startup.
+    const r = Bun.spawnSync([shell.path, "-ic", "abbr --show"], { stdin: "ignore", env: process.env });
+    for (const line of r.stdout.toString().split("\n")) {
+      const abbr = parseAbbrLine(line);
+      if (abbr && abbr.name === word) return abbr.expansion;
+    }
+  } catch {
+    /* no abbreviations available */
+  }
+  return null;
+}
+
+export interface ShellCommand {
+  /** What to spawn. */
+  argv: string[];
+  /** The same command with the shell by name, for scripts that should run on other machines. */
+  portable: string[];
+}
+
+/** `args` the way the user's shell runs them when typed: interactive, so aliases, functions and abbreviations apply. */
+export function throughShell(args: string[], shell: UserShell): ShellCommand {
+  const [first, ...rest] = args;
+  const expanded = first ? fishAbbreviation(shell, first) : null;
+  const line = expanded ? `${expanded} ${shellQuote(rest, shell.name)}`.trim() : shellQuote(args, shell.name);
+  return { argv: [shell.path, "-ic", line], portable: [shell.name, "-ic", line] };
+}