Record Your Coding Agent's Session With asciinema, Then Replay Where It Went Wrong

• Book: AI Agents Pocket Guide
• The series: Pocket Guides for Developers — 8 short books on agents, RAG, prompts, observability, events, databases and system design — the whole series
• My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
• Me: xgabriel.com | GitHub

---

The agent says the flaky test is fixed, and the suite agrees. Somewhere in the few hundred lines it printed while you were in another tab, it wrote one sentence about why. You scroll up to find it. The interface has redrawn itself a dozen times since, and the line you want is either gone or buried between two diffs.

You can ask the agent what it did, but you get its summary, not what it printed at the time.

A terminal recording fixes this. asciinema saves everything the terminal displayed, with timing, into a small text file you can replay and search. It works the same for a Claude Code session as for a Codex one. The catch is that the file holds every byte the agent printed, secrets included, so it stays on your machine.

Step 1: record the agent, not a shell

This uses asciinema 3.x. Version 3.0 was a Rust rewrite released on 15 September 2025, and its release notes add the convert command and the asciicast v3 file format. A 2.x install has no convert and writes the older file format, so step 4 won't work on it. That matters on Linux: Debian and Ubuntu still package 2.4, so apt install gets you the old one. Homebrew ships 3.2.1. On Debian or Ubuntu, take the static binary from the releases page or build the development version with Cargo, as the quick start shows:

brew install asciinema        # macOS, 3.x

# Debian, Ubuntu: apt has 2.4, so build from git
cargo install --locked \
  --git https://github.com/asciinema/asciinema

asciinema --version           # needs 3.x

Then start the agent through it. -c runs one command instead of your shell, so the recording ends when the agent exits (asciinema rec man page):

mkdir -p ~/casts
asciinema rec -i 2 -t "fix flaky login test" \
  -c claude ~/casts/fix-login.cast

asciinema rec -i 2 -c codex ~/casts/tidy-auth.cast

-i 2 caps every pause at two seconds. The man page says the original timing is kept in the file and the limit is applied when you play it back, so an agent that thought for 40 seconds replays as a two-second gap. -t stores a title in the file's header.

The casts go in ~/casts, outside the repository, for reasons that come up in step 5. And since 3.0, rec needs a file name and no longer uploads anything on its own (release notes). Keep it that way.

The recording keeps every frame the agent printed, in order, with timing.

Step 2: drop a marker when something looks off

You will often notice a bad moment while it happens: the agent says "I'll skip this test for now" and keeps going. asciinema can add a marker at that instant, but there is no default key for it (markers docs). Set one in the 3.x config file, under [session] (configuration docs):

# ~/.config/asciinema/config.toml
[session]
idle_time_limit = 2
add_marker_key = "^]"

The docs' example key is ^x. Don't use that one with Claude Code, which starts several shortcuts with Ctrl+X, such as Ctrl+X Ctrl+K to stop background subagents (Claude Code shortcuts). Ctrl+] isn't in that list. Pick whatever key your agent leaves free.

Adding a marker shows a desktop notification, so you know it landed. The other recording key is Ctrl+\, which pauses and resumes capture (shortcuts). Press it before you paste anything you don't want on file, and again after.

Step 3: replay at 4x and stop on the markers

Play the cast back in a terminal at least as large as the one you recorded in, because asciinema doesn't adapt control sequences to a smaller window (quick start):

asciinema play -s 4 -i 1 ~/casts/fix-login.cast
asciinema play -s 4 -i 1 -m ~/casts/fix-login.cast

-s 4 is four times speed. -i 1 on play overrides the limit stored in the recording, so you can squeeze idle time harder than you recorded it. -m pauses at every marker (asciinema play man page).

While it plays, Space pauses and resumes. While paused, . steps forward one event and ] skips to the next marker. Ctrl+C stops. Stepping one event at a time through the stretch around a marker is how you read a line that flashed past at full speed.

Step 4: turn the cast into text you can grep

Watching works when you know roughly where to look. When you don't, search. asciinema convert exports plain text when the output file ends in .txt (asciinema convert man page):

asciinema convert ~/casts/fix-login.cast ~/casts/fix-login.txt
grep -n -i -E "skip|fail|todo" ~/casts/fix-login.txt

# or straight to stdout
asciinema convert -f txt ~/casts/fix-login.cast - | grep -n -i skip

The text export runs the output through a virtual terminal and drops colours, control sequences and timing. It tells you what was left on screen and in scrollback. It doesn't tell you when. Lines the agent's interface redrew over may not survive the export; the raw cast still has them.

For when, search the cast itself. In asciicast v3 each line after the header is [interval, code, data], where the interval is the time since the previous event and code o is output, m is a marker (asciicast v3 spec). A marker with an interval of 0.0 sits at the same moment as the event before it and shifts nothing after it. So you can insert one in front of the first line that mentions your word:

awk 'NR > 1 && !done && /skip/ {
       print "[0.0, \"m\", \"first skip\"]"; done = 1 }
     { print }' ~/casts/fix-login.cast \
  > ~/casts/fix-login-marked.cast

asciinema play -s 4 -m ~/casts/fix-login-marked.cast

Playback now pauses just before the agent prints that word. Two limits: an agent's interface can split one word across two writes or wrap it in colour codes, so search for something short, and expect the raw cast to be noisier than the .txt export. If the first match is the wrong one, change /skip/ to a longer phrase you saw in the text export.

Step 5: keep the .cast local

A cast is a plain text file with every byte your terminal displayed. For an agent session that includes:

• your prompts, because the agent's interface echoes what you type
• file contents the agent printed while reading your code
• output of every command it ran, including an env, a cat .env or a curl -v that prints an Authorization header

That is without input capture. With -I / --capture-input, asciinema also records your keystrokes, and the man page warns that passwords and other sensitive input are recorded too. The CLI leaves input capture off by default (asciicast v3 spec). Leave it off. Environment variables are safer by default: only SHELL goes into the header unless you pass --capture-env.

A cast is a full copy of the screen. Treat it like a log file with secrets in it.

Record into ~/casts, not into the repo. If you ever record inside a project, add *.cast to .gitignore first. Before you send a cast to anyone, grep for the shapes your secrets take. Search the cast as well as the text export, since a key that was printed and then redrawn over can be missing from the .txt and still sit in the cast:

grep -nE "sk-|ghp_|AKIA|PRIVATE KEY" \
  ~/casts/fix-login.cast ~/casts/fix-login.txt

An empty result means none of those patterns matched, which is not the same as clean. Read the part you plan to share. asciinema upload sends the file to asciinema.org or your own server and prints a secret link (quick start). For agent sessions on real code, share a trimmed text excerpt instead, and delete the casts you no longer need.

Step 6: pair the recording with what each reply changed

The cast has every line the agent printed, but nothing about the state of your files after each reply. Claude Code has its own transcript viewer on Ctrl+O, with tool usage and a timestamp on each assistant message (docs), and that is worth opening first for a Claude session. The file side is where Hermes IDE comes in. I build it, so weigh this with that in mind.

Hermes saves every agent turn, so you can diff or restore any single one (README). Under each session, a strip labelled "Agent replies" shows one chip per reply with the lines it changed (+added −removed). Click a chip to see that reply's changes or to restore your files to that point (2.3.1 release notes). ⌘G (Ctrl+Shift+G on Windows and Linux) opens the Review Desk, where the By turn view lists each turn with its diff.

The Review Desk (⌘G) in By turn view for a Claude Code task in orders-api: two turns listed (T1: 3 files +69 −1, T2: 1 file +1 −0), turn 1's diff of src/db.ts adding a refunded status, the changed-files list, and a commit message drafted from the turns.

Used together: the marker in the cast tells you which reply went wrong ("the third one, where it said it would skip the test"), and that reply's chip shows exactly which lines it touched, with a restore if you want them back. I haven't tested running asciinema inside a Hermes session, so I won't promise how the two interact. Record in a terminal of your own if you want both.

A last difference. Hermes removes turn snapshots from worktree tasks 14 days after the session closes (2.2.9 release notes). Your casts stay until you delete them, which is one more reason to keep them in one folder and clean it out.

---

If this was useful

Hermes IDE is free, source-available under BSL 1.1, and runs on macOS, Windows and Linux: download it or read the source on GitHub.

A recording is how you find the bad turn. The AI Agents Pocket Guide is about the loop that got it there: how agents plan, call tools, decide they're done, and where you put the guardrails so a skipped test gets caught before you replay anything. It is one of 8 short books in the Pocket Guides for Developers series, on agents, RAG, prompts, observability, events, databases and system design — the whole series is here.