This open-source project provides a trace viewer and observability workspace for Claude Code sessions, transforming raw .jsonl logs into a replayable debugging and analysis environment. It targets developers and teams struggling with the complexity of reviewing dense Claude Code traces, offering a visual means to understand agent flows, tool interactions, and token usage, thereby accelerating debugging, prompt iteration, and workflow learning.

How It Works

The tool parses Claude Code .jsonl session traces, converting raw event data into an interactive workspace. It reconstructs agent execution flows, animates step-by-step handoffs between agents and tools, and visualizes the sequence of tool calls, file operations, and terminal commands. This approach allows users to pinpoint performance bottlenecks, identify token spikes, and compare different runs, offering a significant advantage over manual log inspection.

Quick Start & Requirements

• Install: Clone the repository (git clone https://github.com/harrylettering/claude-trace-replay.git), navigate into the directory (cd claude-trace-replay), and run npm install.
• Run: Execute ./start.sh to launch the application locally, accessible at http://localhost:3000.
• Prerequisites: Node.js 18+ is required.
• Demo: A 90-second product demo is available at https://github.com/user-attachments/assets/be7374a6-5f6a-4c87-95f5-defe3974f6ea.

Highlighted Details

• Agent Flow Replay: Watch the call graph animate step-by-step around the main agent and tool interactions.
• Session Compare: Diff two runs across messages, tokens, tools, and models to understand changes.
• Token Analytics: Quickly identify expensive turns and sudden usage spikes.
• AI Analysis: Surfaces retrospective insights and suggested improvements based on session data.
• Searchable Timeline: Browse tool calls, thoughts, diffs, file reads, terminal commands, and results chronologically.

Maintenance & Community

The project has a public roadmap outlining planned improvements such as adding anonymized sample traces, enhancing performance for large sessions, and introducing more flow layout modes. Contributions are welcomed in areas like parser improvements, UI polish, performance optimization, and new analysis panels. Encouraging GitHub Stars is a key community engagement signal.

Licensing & Compatibility

The project is released under the MIT license. This permissive license generally allows for commercial use and integration into closed-source projects without significant restrictions.

Limitations & Caveats

The roadmap indicates ongoing work to improve "large-session performance and visualization density," suggesting potential performance bottlenecks with extremely large trace files. The tool is specifically designed for Claude Code .jsonl session traces and may not support other formats.