Metadata-Version: 2.4
Name: claude-trace-viewer
Version: 0.2.1
Summary: An alternate web-based viewer for logs generated by @mariozechner/claude-trace
Author: Brian Krabach
License: MIT
Project-URL: Homepage, https://github.com/bkrabach/claude-trace-viewer
Project-URL: Repository, https://github.com/bkrabach/claude-trace-viewer
Keywords: claude,trace,viewer,debugging,visualization,claude-ai,anthropic,claude-trace,log-viewer
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Environment :: Web Environment
Classifier: Framework :: Flask
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flask>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.4.2; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: build>=1.2.2; extra == "dev"
Dynamic: license-file

# Claude Trace Viewer

An alternate web-based viewer for trace logs generated by [@mariozechner/claude-trace](https://github.com/mariozechner/claude-trace).

## About

This tool provides a complementary viewing experience for trace logs created by `@mariozechner/claude-trace`. While the original tool creates the trace files during Claude Code conversations, this viewer offers an alternate way to explore and analyze those logs with features like sub-agent detection and timeline visualization and a UI inspired by the browser developer tools network tab for viewing details about individual requests.

## What are claude-trace files?

Running `claude-trace` launches Claude Code and generates JSON logs during the conversations. These files contain detailed information about tool usage, timing, and the flow of operations during a Claude session.

By default, trace files are stored in `.claude-trace` directory where you launch `claude-trace`. Each trace file represents a single conversation or task execution, allowing you to analyze Claude's decision-making process and performance.

## Prerequisites

First, install [@mariozechner/claude-trace](https://github.com/mariozechner/claude-trace) to generate trace files:

```bash
npm install -g @mariozechner/claude-trace
```

This will enable trace logging for your Claude Code conversations.

## Installation

```bash
# Run directly with uvx (no installation needed)
uvx claude-trace-viewer

# Or install with pip/uv
pip install claude-trace-viewer
# or
uv add claude-trace-viewer
```

## Usage

```bash
# View traces in current directory (has a `.claude-trace` folder)
claude-trace-viewer

# Specify a different directory
claude-trace-viewer --trace-dir /path/to/directory/that/contains/.claude-trace

# Use a different port, ex: 5000
claude-trace-viewer --port 5000
```

Click the link printed in the terminal to open the web interface in your browser, defaults to `http://127.0.0.1:8080`.

## Features

- Choose from any of the available trace files in the specified directory
- Interactive timeline visualization
- Sub-agent detection and visualization
- Search and filter capabilities
- Export trace data
- Browser Developer Tools-like interface for detailed request inspection

## Development

```bash
# Clone the repository
git clone https://github.com/bkrabach/claude-trace-viewer.git
cd claude-trace-viewer

# Install in development mode
pip install -e .
```

## Troubleshooting

### No trace files found

If the viewer shows no trace files, ensure that:

- You're pointing to the correct directory (default is `.claude-trace` in the current working directory)
- Claude has generated trace files during your conversations, go to `.claude-trace` and verify that there are JSON files present
- You have read permissions for the trace directory

## License

MIT
