# AI use cases for Zoetrope (furkankly/zoetrope)

Repo: [furkankly/zoetrope](https://github.com/furkankly/zoetrope) | Use cases: 5 | Page: https://dedupedai.com/use-cases/furkankly-zoetrope/

zoetrope is a read-only terminal and browser viewer that draws a Claude Code or Codex session as a live flow graph of agents and their tool calls.

This file holds every use case of this repo. Each one starts with a "## " heading and ends with its URL.

- Follow a running agent session as a live graph: https://dedupedai.com/use-cases/furkankly-zoetrope/follow-a-live-agent-session-as-a-graph/
- Replay a finished agent run to review its subagents: https://dedupedai.com/use-cases/furkankly-zoetrope/replay-a-finished-run-to-review-subagent-work/
- Print a session's agent tree without opening the TUI: https://dedupedai.com/use-cases/furkankly-zoetrope/print-a-session-tree-for-scripts-and-logs/
- View a session graph in the browser with no install: https://dedupedai.com/use-cases/furkankly-zoetrope/view-a-session-in-the-browser-without-installing/
- Open the live graph over a Herdr agent pane: https://dedupedai.com/use-cases/furkankly-zoetrope/follow-a-herdr-agent-pane-live/

## How to follow a running agent session as a live graph with Zoetrope

Repo: [furkankly/zoetrope](https://github.com/furkankly/zoetrope) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README

Watch the main agent, its subagents and their tool calls update live in your terminal.

**Who it is for:** A developer who has started a Claude Code or Codex run in a project and wants to see which agents are working and what tools they are using right now.

**The problem:** A long agent run is a stream of text in a transcript, which makes it hard to tell which subagent is busy, what it is stuck on, or how far the run has progressed.

**The outcome:** A live graph of the session with a card per agent showing status, current tool, tool count and output tokens, updating as the agent works.

### Steps

1. Install Zoetrope with `brew install furkankly/tap/zoetrope` (or `cargo install zoetrope`).
2. Open a terminal in the project folder where the agent session is running.
3. Run `zoe` to follow the current project's newest live session.
4. Press `f` to let the camera follow the agent that just did something.
5. Click an agent to open its detail panel, and press `q` to quit when finished.

### Prompt to paste into your agent

```text
In the zoetrope repo (furkankly/zoetrope), install the zoe binary and run `zoe` from the project directory at <project-path> to follow its newest live session. Expected output: a live flow graph showing the main session and any subagents with their current tool. Verify that at least one agent card shows a status and tool count before reporting success.
```

### Caveat

Zoetrope reads undocumented transcript formats that Claude Code and Codex can change without warning, so some records may render oddly after an update.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/furkankly-zoetrope/follow-a-live-agent-session-as-a-graph/

## How to replay a finished agent run to review its subagents with Zoetrope

Repo: [furkankly/zoetrope](https://github.com/furkankly/zoetrope) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README

Scrub back through a completed session to see each agent and tool call in order.

**Who it is for:** A developer or reviewer who needs to audit what an agent and its subagents did during a run that already finished.

**The problem:** Reading a long transcript to reconstruct which agent spawned which subagent and when takes time and is easy to get wrong.

**The outcome:** A replayed graph paced by the session's own timestamps, with the ability to scrub, pause and step between prompts to review each stage.

### Steps

1. Install Zoetrope with `brew install furkankly/tap/zoetrope` or use a prebuilt binary from the releases page.
2. Run `zoe` with the path to any file of the finished session to replay it from the start.
3. Press `space` to play or pause, and `[` or `]` to move between prompt eras.
4. Drag the bar or scrub to a point of interest and click an agent for its prompt, reasoning and tool calls with timings.
5. Press `End` or `g` to return to the live edge, then `q` to quit.

### Prompt to paste into your agent

```text
Using the zoetrope repo (furkankly/zoetrope), replay the finished session at <session-file-path> with `zoe` and step through each prompt era. Expected output: a graph showing each subagent and its tool calls at the point it ran. Verify that the tool counts fall when you scrub backwards before reporting the review as complete.
```

### Caveat

The replay reflects only what the transcript records, and Zoetrope skips unrecognized records rather than failing, so a gap in the graph may come from the file rather than the viewer.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/furkankly-zoetrope/replay-a-finished-run-to-review-subagent-work/

## How to print a session's agent tree without opening the TUI with Zoetrope

Repo: [furkankly/zoetrope](https://github.com/furkankly/zoetrope) | Difficulty: Intermediate | Time: 15 minutes | Basis: From the README

Dump the session tree to the terminal headlessly for logs, notes or scripts.

**Who it is for:** An engineer who wants a plain-text record of which agents a session spawned, to paste into a ticket or check in a script.

**The problem:** Opening an interactive graph is awkward when you only need the structure of a session and want to capture it as text.

**The outcome:** A printed session tree that shows the main session and its nested agents, with no interactive interface needed.

### Steps

1. Install Zoetrope with `cargo install zoetrope` (needs a Rust toolchain) or `brew install furkankly/tap/zoetrope`.
2. Run `zoe inspect` followed by the path to the session file.
3. Redirect the output to a file, for example with `>` in your shell, to keep the record.
4. Check that the printed tree lists the subagents you expect.

### Prompt to paste into your agent

```text
In the zoetrope repo (furkankly/zoetrope), run `zoe inspect` on the session file at <session-file-path> and save the output to <output-file>. Expected output: a printed session tree with the main session and its subagents, written without starting the TUI. Verify that the output file is not empty and lists at least the main session before reporting success.
```

### Caveat

zoe inspect only prints the session tree, so per-tool timings and the detail panel are available only in the interactive TUI or the browser app.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/furkankly-zoetrope/print-a-session-tree-for-scripts-and-logs/

## How to view a session graph in the browser with no install with Zoetrope

Repo: [furkankly/zoetrope](https://github.com/furkankly/zoetrope) | Difficulty: Beginner | Time: 15 minutes | Basis: From the README

Drop a transcript onto the hosted page and get the same graph without installing anything.

**Who it is for:** A non-terminal user or a teammate on a machine where installing software is not allowed but who has a session transcript to look at.

**The problem:** Installing a CLI tool is not always possible, yet the session still needs to be understood as a graph.

**The outcome:** The same session graph rendered in the browser, produced from the transcript file that was dropped on the page.

### Steps

1. Open https://zoetrope.furkankly.dev/app in your browser.
2. Drop the session transcript file onto the page, or open a session from disk.
3. Use the on-screen controls to scrub the timeline and click an agent to see its details.
4. Close the tab when you are done.

### Prompt to paste into your agent

```text
Using the hosted zoetrope app at https://zoetrope.furkankly.dev/app, load the transcript at <transcript-file-path> by dropping it on the page. Expected output: the same agent graph the zoe binary would show for that session. Verify that at least one agent appears in the graph before reporting success.
```

### Caveat

The README says the browser version stays local, but the hosted page itself is a website you load, so check the README before using it with sensitive transcripts.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/furkankly-zoetrope/view-a-session-in-the-browser-without-installing/

## How to open the live graph over a Herdr agent pane with Zoetrope

Repo: [furkankly/zoetrope](https://github.com/furkankly/zoetrope) | Difficulty: Advanced | Time: 45 minutes | Basis: From the README

Press one key in Herdr to open the exact session running in a pane as a live graph.

**Who it is for:** A developer who runs several coding agents side by side in Herdr and wants the graph of the one in focus without finding its session file.

**The problem:** Panes in a multiplexer do not show the structure of the agent session behind them, and finding the right session file by hand is slow.

**The outcome:** The graph opens over the focused agent pane and follows its session live, and the same key closes it.

### Steps

1. Run `herdr integration install claude` and or `herdr integration install codex` so Herdr learns session ids. (inferred, check the README)
2. Run `herdr plugin install furkankly/zoetrope/herdr-plugin`.
3. Run `herdr plugin action invoke setup-keys --plugin furkankly.zoetrope`.
4. Focus an agent pane and press `prefix+shift+z` to open its live graph.
5. Press the same key again to close the graph.

### Prompt to paste into your agent

```text
In the zoetrope repo (furkankly/zoetrope), install the herdr-plugin with the Herdr commands in its README, then focus the agent pane <pane-name> and press prefix+shift+z. Expected output: the live graph of that pane's session opens over the pane. Verify that the graph matches the session running in that pane before reporting success.
```

### Caveat

This path requires Herdr, a separate terminal multiplexer, and the README does not describe its setup in detail beyond the listed commands.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/furkankly-zoetrope/follow-a-herdr-agent-pane-live/