---
name: watchme
description: Watch me — terminal / shell session recorded with `script -f` (a typescript, `.tmp/*.script`) as shared ground truth. Use when the operator says "watch me", "losing", or "winning?"; when diagnosing a shell session from its recorded transcript instead of asking for a re-telling; when asked how to record a terminal session.
---

# Watch Me: a typescript as shared ground truth

Long, interactive, or risky sessions happen in a terminal whose scrollback
dies with the window. `script -f xyz.script` records the whole session to a
file in the working directory, so both the operator and an agent can read
what was done and what the machine said.

## Pattern

Start the recording before the work:

```sh
script -f xyz.script
```

- `-f` flushes after each write, so the tail is readable while the session
  is still running — not only after it ends.
- Name the file for the task, next to the work: `.tmp/mouse-problem.script`,
  `.tmp/dm93.script` — under `.tmp/` at the workspace root. The name is the
  shared handle; it is how the operator later says "watch me" and points the
  agent at the log. Unless the operator names a file, the newest
  `.tmp/*.script` is the one in play.

Then drive the actual work inside the recorded shell. When something stalls
or finishes, the operator invokes one of two moves.

## The two triggers

**"losing"** — read the tail of the script for *what was done* and *the
symptoms*: the commands typed, the errors, warnings, and hang signs they
produced. Diagnose from that evidence rather than asking the operator to
re-tell it.

**"winning?"** — compare the tail of the script against the current goal and
answer one of exactly two ways:

- **"Yes, that's as expected; next, do X."** — the session did what it
  should; the goal is not met yet.
- **"Yes, as expected. Done!"** — the session did what it should and the
  goal is met.

The goal is the yardstick; the script is the claim. Resist an in-between
"partially winning": winning is a verdict against the goal, not a read on
the moment. A run that ends short of the goal was never winning — a team
ahead 4–1 in the third that loses 6–4 was losing all along.

## What the log gives you

A util-linux `script` capture brackets the session:

```
Script started on 2026-09-02 23:47:55-05:00 [TERM="linux" TTY="/dev/tty1" COLUMNS="240" LINES="67"]
...
Script done on 2026-09-02 23:48:46-05:00 [COMMAND_EXIT_CODE="0"]
```

The header records when, on which TTY, and the terminal geometry; the footer
records the exit code.

For a longer session the value is that one file holds both halves of the
story: the operator's commands and the machine's responses, interleaved in
order. `tail` it while it is live; `grep` it after the fact.

## Relationship to the lab notebook

The typescript is raw evidence; a lab notebook
is interpretation. Read the script to establish what happened, then promote
the finding — hypothesis, evidence, next question — into a notebook entry so
it survives independently of the transcript.

## Caveats

- Typescripts carry terminal control sequences: bracketed-paste markers,
  color codes, and cursor movement appear inline (e.g. `[?2004h`). Read
  through them, or filter before quoting.
- Captures grow fast — tens of thousands of lines for a long session. Read
  the tail by default, not the whole file.
- These are local working artifacts, not deliverables. Keep them out of
  version control unless a session is itself the thing worth preserving.

## Reference

- `man script` (util-linux) — `-f`, `--flush`