zoetrope README

The project's README from github.com/furkankly/zoetrope. As one markdown file: README.md.

zoetrope

Watch a Claude Code session as a live flow graph, in your terminal or your browser.

crates.io docs.rs downloads build status minimum supported Rust version

zoetrope.furkankly.dev · the whole app in your browser, the same binary compiled to WASM

A session drawn as a flow graph: a main agent above the subagents it spawned, over a timeline of tool activity

Claude Code writes a JSONL transcript for every session under ~/.claude/projects/. zoetrope reads it and draws the session as a graph in your terminal: the main agent, the subagents and workflows 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.

zoetrope replaying a Claude Code session as a flow graph

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.

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
zoe <file.jsonl> --follow    # open a recording at its live edge
zoe <file.jsonl> --speed N   # playback speed (default 8.0)
zoe inspect <file.jsonl>     # 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

Time travel

Inspection

Reading your sessions

Keys

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

Full keymap
Key Action
space play / pause (resumes from the playhead)
[ / ] previous / next prompt era
End / g jump to the live edge
s toggle gap compression (faithful pacing vs. skip idle stretches)
mouse drag seek along the scrubber
o / f camera: Overview / Follow
r relayout (tidy the graph)
arrows / Tab / Shift-Tab move between agents
h j k l pan the graph
+ / - / 0 zoom in / out / reset
c center on the selected agent
click open an agent's detail panel
j / k / PgUp / PgDn scroll the detail panel
i session info overlay
? help overlay
esc close an overlay / clear the selection
q / ctrl-c quit

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:

zoetrope in follow mode, the camera tracking whichever agent is working

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

Panning, zooming, opening a detail panel, and dragging the scrubber

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:

The model, the timeline and the rendering all live in the portable core, a library with no IO that compiles for any target, including WebAssembly. The native frontend (the zoe binary in this crate) and the browser frontend (the zoetrope-web crate under web/wasm/, which runs the hosted app) sit on top of it and differ only in their IO and event loop.

See docs/DESIGN.md for the module map and the transcript format, and docs/ARCHITECTURE.md for the invariants above in full.

A note on the transcript format

The JSONL format zoetrope reads is undocumented and internal to Claude Code, so it can change without warning. zoetrope is built to degrade rather than break: unrecognized records are skipped, missing fields fall back, and a malformed line never takes down the session. If a new Claude Code release makes something render oddly, please open an issue.

Contributing

Pull requests are welcome.

License

MIT.

Acknowledgements

zoetrope (furkankly/zoetrope)

Searching Database…

Что это такое?Zoetrope превращает сессию агента кодинга Claude Code (или Codex) в живой анимированный граф потоков, показывающий основного агента, его суб-агентов и воркфлоу, а также каждый вызов инструмента, за чем можно следить в терминале или в браузере.
Это терминальное приложение или браузерное приложение?И то и другое: нативная сборка — это терминальный UI на ratatui, а тот же самый движок компилируется в WebAssembly, так что он работает и как хостинговая веб-страница — можно просто перетащить файл транскрипта на страницу, вообще без установки.
Как его установить и запустить?Установите через Homebrew на macOS/Linux, через Cargo, если у вас есть тулчейн Rust, или скачайте готовый бинарник для macOS (Apple Silicon или Intel), Linux (musl, arm64/x86_64) или Windows (x86_64); в любом случае команда — `zoe`, указывающая на файл транскрипта или каталог проекта.
Нужен ли уже настроенный Claude Code, чтобы этим пользоваться?Да — zoetrope читает только JSONL-транскрипт, который Claude Code пишет для каждой сессии в ~/.claude/projects/, так что нужно, чтобы сессия Claude Code уже запускалась (или запускается сейчас); свой API-ключ или аккаунт ему не нужны.
Что будет, если Claude Code сменит формат транскрипта?Формат JSONL не задокументирован и внутренний для Claude Code, так что он может измениться без предупреждения; zoetrope устроен так, чтобы деградировать, а не ломаться: он пропускает незнакомые записи вместо падения.
Покидают ли мою машину данные моей сессии?Нет — zoetrope работает только на чтение и не имеет сетевого доступа вовсе; в его дереве зависимостей нет HTTP-клиента, а зависимость tokio подключена без фичи networking, что вы можете сами проверить через cargo tree.
Что узел в живом графе вообще мне показывает?Каждая карточка — это агент: главная сессия, суб-агент или группа воркфлоу с вложенными детьми, показывающая статус, текущий инструмент, количество инструментов и выходные токены, а вызовы инструментов появляются под ней как чипы, которые разрешаются в галочку или крестик.
Можно отмотать и проиграть сессию после её завершения?Да, есть перематываемая шкала времени, индексированная по событиям, а не по реальному времени, так что можно двигаться назад и смотреть, как агенты «отменяют завершение», а счётчики инструментов откатываются ровно к тому, как выглядела сессия в тот момент, с опциональным сжатием пауз, чтобы пропускать простои.
Можно подробно изучить, что сделал конкретный агент?Клик по любому агенту открывает его панель происхождения: промпт, который его породил, его модель, рассуждения вокруг него и каждый вызов инструмента с таймингами; `zoe inspect` выгружает всё дерево в headless-режиме, так что работает даже без терминала.
Зачем строить просмотрщик графа вместо простого чтения сырого лога?Сырой транскрипт — плоский журнал событий с дозаписью, который трудно читать построчно; zoetrope сворачивает его в производную модель агентов, вызовов инструментов и промптов, так что родство, тайминги и завершённость становятся тем, за чем реально можно наблюдать в развитии.
Creator
furkankly
Size
11.6 MB
Stars
1K
Age
1mo
Commits · 90 Days