agent-replay

# Agent Replay Run everything through `replay.sh` next to this file. On first use it downloads the latest `agent-replay` release for this OS and CPU from GitHub into `~/.local/share/agent-replay` (a 40 to 60 MB download), and it checks for a newer release at most once a day, so never install anything by hand. The first MP4 on a machine also downloads Chrome Headless Shell, so allow a few minutes for it. ## Pick the session - "This session" is the newest session of the agent you are running as: `latest:claude` from Claude Code, `latest:codex` from Codex, `latest:opencode` from OpenCode. T3 Code threads are stored as ordinary Claude Code or Codex sessions, so this works there too. - For anything else, list the local sessions and match on title, project, or time: ```sh <skill-dir>/replay.sh list --limit 30 ``` Pass the session id (or a unique part of it), or a path to a `.jsonl` file. ## Make the replay Render an MP4 unless the user asks for HTML: ```sh <skill-dir>/replay.sh <session> -o ~/Desktop/replay-<slug>.mp4 ``` Use `~/Desktop` when it exists, otherwise the current directory, unless the user names a place. Never write into the project the session came from. - `--format vertical` (1080x1920) for Reels, TikTok, Shorts and stories. `--format square` (1080x1080) for the X, LinkedIn or Instagram feed. The default is landscape (1920x1080). - HTML on request: `-o <dir>/replay-<slug>.html` writes one self-contained file that plays like a video and has an Export MP4 button. Add `--mp4` for both. - `--turns 2-4` keeps only those user turns. - `--speed 2` plays faster. - `--title "..."` opens with a title card. ## Highlights When the user wants a highlight, a short clip, something to post, or the session is long, cut it down to the moments worth watching. You pick them. 1. Print the numbered steps. `✗` marks a failed tool call. ```sh <skill-dir>/replay.sh outline <session> ``` 2. Pick 3 to 5 moments that tell the story: the ask, a discovery or a failure, the fix, the proof (tests going green, the command that works), the result. Failures followed by a fix make the best clips. Skip routine reads and searches unless they are the story. Each cut is a step range, and each turn's prompt is kept automatically. 3. Write a caption per cut: 2 to 5 words, present tense, concrete, like a narrator ("Tests fail on rounding", "Finds the real bug", "All 8 green"). Write a title of at most 7 words that says what happened, and name the agent or model when it is part of the story. 4. Render: ```sh <skill-dir>/replay.sh <session> --format vertical \ --title 'GLM ships discount codes' \ --cut '4-8: Writes the feature' --cut '15: Tests fail on the $5 fee' \ --cut '18-19: Rethinks the design' --cut '26-27: All 8 green' \ -o ~/Desktop/replay-<slug>-highlight.mp4 ``` Use single quotes, so the shell leaves `$` and `!` in captions alone. Steps between cuts are dropped and shown as "⋯ N steps later". Aim for 20 to 45 seconds. If the CLI prints a longer video, tighten the cuts or add `--speed 1.5`. ## Pull requests When the user wants a replay on a pull request, open or push the PR first, then run this from the repository: ```sh <skill-dir>/replay.sh pr <session> \ --cut '2-6: Reads the cart code' --cut '9: Test breaks at $60' \ --cut '14-15: Ships it, 4/4 pass' ``` It renders a GIF and an MP4, commits them to an `agent-replay` branch of the PR's repository with `gh`, and adds a "How this was made" section to the PR description. Running it again replaces that section. It uses the PR for the current branch; pass `--pr <number>` for another one. Pick cuts as for a highlight, but tell the story of this PR only: the ask, what shaped the change, and the proof it works. Aim for 10 to 30 seconds and skip the title card. The replay is as public as the repository. ## Secrets The CLI masks API keys, tokens, passwords, private keys, and credentials in URLs, and shows the home directory as `~`. Masking is pattern-based, so before the user publishes a replay, tell them to skim it. ## Report Give the output path (or the PR URL), the video length and render time the CLI printed, and for highlights the cuts you picked. If the user wants a public link and a file-upload skill is available, upload the file with it.