zoetrope

Claude Code and Codex write a transcript for every session. zoetrope reads it and draws the session as a graph in your terminal: the main agent, the agents it spawns, and the tools each one runs, updating live as it goes. Point it at a finished run and it replays, paced by the session's own timestamps. Point it at a running one and it follows along. It's read-only, and nothing leaves your machine.

Built on ratatui and rataflow.

Supported agents

zoetrope reads a session from any of its files and tells the formats apart by content, so zoe <file> works for either, and zoe <id> finds a session by id across both.

Installation

Homebrew — macOS and Linux:

brew install furkankly/tap/zoetrope

Cargo — needs a Rust toolchain:

cargo install zoetrope

Prebuilt binaries — no toolchain needed. Every release carries archives for macOS (Apple Silicon and Intel), Linux (musl, arm64 and x86_64) and Windows (x86_64). Unpack one and put zoe on your PATH.

Whichever route you take, the command is zoe. Or build from source:

git clone https://github.com/furkankly/zoetrope
cd zoetrope
cargo build --release
./target/release/zoe

No install at all: try it in your browser. Drop a transcript on the page and get the same graph.

In Herdr

Herdr is a terminal multiplexer built for running coding agents side by side. It knows which agent occupies a pane and the id of the session running there, so the plugin in herdr-plugin/ opens that exact session in zoe, without you naming a file or an id.

herdr integration install claude          # and/or codex, so Herdr learns session ids
herdr plugin install furkankly/zoetrope/herdr-plugin
herdr plugin action invoke setup-keys --plugin furkankly.zoetrope

Focus an agent pane and press prefix+shift+z. The graph opens over the pane, follows the session live, and the same key closes it. There are placements for a split and a tab as well, and the plugin's README covers both.

Usage

zoe                          # follow the current project's live session
zoe <dir>                    # follow another project's session
zoe <file.jsonl>             # replay a recording from the start (any file of a session)
zoe <id>                     # replay a session by id, or a unique prefix of one
zoe <file.jsonl> --follow    # open a recording at its live edge
zoe <file.jsonl> --speed N   # playback speed (default 8.0)
zoe --provider codex ...     # force the format instead of detecting it from the file
zoe inspect <file|id>        # print the session tree and exit (no TUI)

Give it a file and it reads the whole transcript, then keeps watching for new lines. Give it a directory, or no argument at all, and it finds the newest session in that project and follows it live. Whichever way you start, the controls are the same: scrub, follow, pause, jump back to live.

The same engine also runs in the browser, compiled to WebAssembly via ratzilla. Open a session from disk, or drop a transcript on the page. It stays local there too.

Features

The graph

• A node per agent: the main session, its subagents, and workflow groups with their children nested underneath
• Status, current tool, tool count and output tokens on every card
• Edges animate while an agent is working, and settle when it finishes
• Tool calls surface as chips beneath their agent (⚒ bash ×5, or ⚒ bash 0.5s ticking during a single call), resolving to ✓ or ✗
• A minimap showing where your viewport sits once the graph outgrows the screen

Time travel

• One scrubbable timeline over both live and replayed sessions
• Indexed by event rather than wall-clock, so a busy minute gets room instead of collapsing into a sliver
• Scrub, pause, step between prompt eras, or snap back to the live edge
• Seek backwards and you see the session exactly as it stood at that moment. Agents un-finish, tool counts fall, the graph shrinks back
• Optional gap compression, to skip dead air or keep faithful real-time pacing

Inspection

• Click any agent for its provenance: the prompt that spawned it, the reasoning around it, its model, and every tool call it made with timings
• Session info overlay: mode, permissions, queued ops, file edits, last prompt
• zoe inspect prints the whole tree headlessly, so it runs anywhere without a TTY

Reading your sessions

• Follows a running session live, or replays a finished one
• Reads everything a session writes: the main transcript, its subagents, and workflows with their own children, so the graph is the whole picture
• Keeps going when an agent writes something it hasn't seen: unfamiliar records are skipped, never fatal
• Read-only, and no network at all (see below)

Keys

space play/pause · [ ] prev/next prompt · End or g jump to live · drag the bar to seek · ? for everything else.

j / k scroll the detail panel when an agent is selected, otherwise they pan the graph.

Hand the camera to the action with f and it glides to whichever agent just did something. This is what watching a live run looks like:

Or drive it yourself: pan, zoom where you point, open an agent's panel, and drag the scrubber to travel back through the session.

Under the Hood

zoetrope treats the transcript as an append-only event log. It tails the files, parses each line defensively, and folds them into a derived model of agents, tool calls, and prompts. Nothing is mutated in place. The model is a pure function of the facts seen so far, so seeking backwards is exact.

A few of the pieces that turn a log into a watchable session:

• Two clocks, kept apart. The playhead runs on content time, the session's own timestamps, and everything the model says is true is a function of where it sits. Presentation time is how long you have been watching, and only animation reads it. Speed, gap compression and scrubbing change