asciinema-claude

Turn asciinema recordings of Claude Code sessions into the ANSI scrollback a user would see.

Install

pip install asciinema-claude

For development: uv sync, then uv run pytest -q. To record test fixtures, run scripts/install-asciinema.sh (installs asciinema 3.2.1 to tools/bin/asciinema).

Command line

asciinema-claude session.cast | less -R
asciinema-claude --no-color session.cast > session.txt
cat session.cast | asciinema-claude -

Options:

• --clear-separator: mark each /clear with a separator line.
• --no-color: write plain text, with no ANSI codes.
• --follow: keep reading while the file grows (polls every 0.25 s). It waits for the file to exist. It stops on Ctrl-C, or at the exit event ("x") that asciinema 3 writes to v3 recordings. A v2 recording has no exit event, so stop it with Ctrl-C. A line is written only when it is final: when it scrolls off the top of the screen, or when the recording ends. A short session that fits on the screen shows nothing until then. At the end, the rest of the screen is written. Not allowed with -.
• --version: print the version.

Exit codes: 0 on success, 1 for a file error (for example a missing file), 2 for a bad recording or bad usage, 130 for Ctrl-C (without --follow).

Library

One call:

from asciinema_claude import transcribe

text = transcribe("session.cast")                     # path, str, bytes or file object
text, info = transcribe("session.cast", return_info=True)
print(info.max_width, info.clears, info.reprints_removed, info.gaps)

Incremental, for a recording that is still growing:

from asciinema_claude import Transcriber

t = Transcriber(80, 24)           # the cast header resets the size
for chunk in chunks_of_cast_text:  # any split of the file is fine
    t.feed_raw(chunk)
    send(t.take_committed())       # final text, append it
    show_tail(t.tail())            # live tail, see below
send(t.finish())
info = t.info()                    # max_width, clears, reprints_removed, gaps

Output in take_committed() is final: append it and never change it. tail() is the live part: the screen rows that are not final yet, and lines held while a redraw is checked. It is replaced on each update, so do not append it. It can be taller than the screen (37 lines on a 30-row screen in the basic fixture).

Web app with xterm.js

Show the committed text in one terminal and the tail in a separate element, which you replace on each update:

// committed: new text from take_committed(); tail: tail(); width: info.max_width
const term = new Terminal({ cols: width, scrollback: 1000000 });  // default is 1000
term.write(committed);                  // append only; lines already end in \r\n
tailTerm.reset();                       // a second Terminal (or a <pre>) under it
tailTerm.write(tail);

• Use info.max_width as the number of columns, so no line wraps. The width can grow while the recording grows: call term.resize(width, term.rows) when it does.
• Set scrollback high. With the default of 1000 lines, xterm.js drops the start of a long transcript.
• To use one terminal only, call term.reset() and write all committed text and then the tail on each update. This costs more for long transcripts.

A Transcriber cannot be pickled or stored between requests. A stateless backend can feed the whole recording again on each request (about 3 MB/s on a laptop). Do not call finish() while the recording grows. The committed text of a part of a recording is always the start of the committed text of the whole recording. So the client can send the length it already has, and the server returns only what is new and the tail:

def update(cast_text: str, offset: int) -> dict:
    t = Transcriber(80, 24)
    t.feed_raw(cast_text)
    committed = t.take_committed()
    return {"new": committed[offset:], "offset": len(committed), "tail": t.tail(),
            "width": t.info().max_width}

Claude Code modes

• Inline mode (the default) and "tui": "fullscreen" mode (alternate screen) give the same kind of transcript. In fullscreen mode, the library copies each frame and finds how far the conversation moved. The rows that leave the top of the viewport are kept, as in inline mode.
• Fullscreen mode, scrolling back: frames that show older rows are ignored. Claude Code marks these frames with a pill (Jump to bottom (ctrl+End) ↓, 1 new message (ctrl+End) ↓) and a sticky prompt at the top row. A frame that shows newer rows is copied, also while the user is scrolled back. Thus, if the user pages down, every row that was on the screen is kept once. The pill, the sticky prompt and the 1 new message divider are not kept.
• Fullscreen mode, overlays: the slash menu, the @ file picker and other overlays above the input box are not kept. The conversation rows behind an overlay are kept.
• Fullscreen mode, an external editor (ctrl+g): the editor's screen is not kept. Only frames that show Claude Code's input box or a permission prompt are copied.
• A recording made with an idle-time limit (asciinema rec -i) gives the same transcript as one without it, for all limits down to 0 s.
• After a resize, the repaint is matched with the history by paragraph. A table drawn again at another width (or as a Name: value list, on a narrow screen) is matched by its cells, so it is kept once. The size of the table does not matter.

Known limits

• In fullscreen mode, Claude Code draws only the viewport. Rows that were never on the screen are not in the recording, so they cannot be in the transcript. Three cases cause this. The user jumps to the bottom after rows arrived while the view was scrolled back. More than one screen of rows arrives in one frame. An overlay hid the rows. At a jump, the transcript has this line where rows can be missing: ⋯ rows may be missing here: they were never on the screen. info.gaps counts these lines. Rows that only an overlay hid are not marked.
• In fullscreen mode, if the viewport shows only repeated rows (for example a log of equal lines), the frames do not show how many rows left the top. The library takes the smallest number that agrees with the frames, and writes the gap line once for each such stretch. Some repeated rows can be missing. Other rows are not lost.
• In fullscreen mode, an overlay above the input box is found by its form: indented rows with a blank row above them. An overlay of another form is kept as text. The library prefers this to the loss of a conversation row.
• A table drawn again after a resize is matched by its cells. If the repaint starts so that only the end of one cell value is on the screen, that part is not matched, and it is kept twice. A duplicate is preferred over losing content.