A local observability dashboard for Claude Code sessions. Claude Scope reads the JSONL files in ~/.claude/projects/, analyzes them with embedded ClickHouse via chdb, and lets you explore them in your browser.
Nothing leaves your machine.
Features:
- Sessions, traces, and observations (OpenTelemetry-aligned: session = conversation, trace = one interaction/prompt, observation = a span/step).
- Billable cost by model, including input, output, cache reads/writes, server tools, and service-tier adjustments. Costs are deduplicated by
requestId. - Per-trace and per-session details, including prompts, responses, tool calls, tool inputs/outputs, and token usage for each step.
- Two layouts for the Traces table: a classic table, and a viewer layout with an expandable metrics panel per trace and an observation viewer on the right.
- Filters by date, project, model, and tool.
Want a preview? Jump to The panel views below.
You only need Python 3.9 or newer. Claude Scope uses chdb, an embedded ClickHouse engine installed through pip: no separate binary, no server, and no extra configuration.
The dashboard opens automatically in your browser.
Copy and paste this block into a terminal:
git clone https://github.com/Wachynaky/claude-scope.git
cd claude-scope
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 app/local_server.pyThat’s it. The dashboard opens at http://127.0.0.1:8765.
The first time,
pip installdownloads chdb, which bundles the ClickHouse engine and may take a moment. After that, Claude Scope starts quickly and works offline.
If you don’t have Python installed:
On Debian/Ubuntu:
sudo apt install python3 python3-venvOn macOS, install Python from python.org or with Homebrew:
brew install pythonchdb does not currently provide a native Windows build, so Claude Scope runs inside WSL (Windows Subsystem for Linux), where it works the same as on Linux.
Enable WSL once:
# PowerShell as Administrator, first time only
wsl --install
# Reboot when prompted.Then open an Ubuntu/WSL terminal and run the same commands as on Linux:
git clone https://github.com/Wachynaky/claude-scope.git
cd claude-scope
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 app/local_server.pyIf Python is missing inside WSL:
sudo apt install python3 python3-venvNext time, once everything is already installed, just enter the folder and run:
source .venv/bin/activate
python3 app/local_server.pyTo stop the dashboard, press Ctrl + C in the terminal, or use the power-off button inside the panel.
The first time you open Claude Scope, it asks where it should read Claude Code session files from. These are Claude Code’s .jsonl files.
 |
You have three options:
- Use Claude Code’s default folder: reads
~/.claude/projects/in read-only mode. Choose this if you use Claude Code on this machine. - My history is in another folder: opens a dialog so you can select the folder that contains your
.jsonlfiles. - Drag / upload my .jsonl files: copies the files into Claude Scope’s local data folder and uses them as the data source. This is useful when someone sends you sessions from another machine.
You can change the selected source at any time from the header. Claude Scope only reads these files; it never modifies them.
These are the only files needed to run the dashboard:
requirements.txt # Dependency: chdb (embedded ClickHouse)
app/ # The dashboard itself
├─ index.html # Single-page app
├─ local_server.py # HTTP server + chdb queries; opens the browser
├─ pricing.json # Anthropic pricing
└─ assets/vendor/ # Vendored marked + ansi_up dependencies for offline use
local_server.py accepts a few parameters:
python3 app/local_server.py --port 9000 # Use another port; default is 8765
python3 app/local_server.py --no-open # Do not open the browser automatically
python3 app/local_server.py --view viewer # Open the Traces table in the viewer layout ("table" for the classic one)
The dashboard is the main screen.
At the top, in the header, you’ll find:
-
Search, to filter by message content.
-
Token mode, a toggle that changes how tokens are counted across all metrics:
- All & Real data: input + output + cache, deduplicated per request. This reflects what you actually consume.
- Same as Claude Code: raw input + output only, like the “Total tokens” shown in
/config→ Stats. This is usually higher because it does not deduplicate requests or account for cache behavior in the same way.
-
Grouping (Traces / Sessions) and, for Traces, the layout toggle (Table / Viewer).
-
Data source, a folder icon whose tooltip shows the folder currently being read; click it to change the source.
-
Panel zoom, to adjust the interface scale.
Below the header, you choose how to group the data (aligned with OpenTelemetry tracing terminology, where a trace is a single interaction/prompt and a session is the whole conversation):
- Traces: the default view. One row per trace (a single prompt and everything the agent did to answer it). The Table / Viewer toggle in the header switches between two layouts:
- Table: the classic table. Each row shows the Name (
[project] Turn N, with the project derived automatically from the session path), token usage, cost (hover it for the input / output / cache breakdown), and the number of observations (spans/steps). Expand a row to see the trace's metric cards and its list of observations. - Viewer: the trace list on the left and an observation viewer on the right (described in The Traces viewer).
- Table: the classic table. Each row shows the Name (
- Sessions: one row per session (conversation), with all its traces nested below, and the same cost breakdown on hover. Use this view to walk through a full session.
The stats bar summarizes traces, tokens, and total cost (with the input / output / cache breakdown), and holds the filters: project, model, tool, and time range, plus Clear filters.
Below it, charts show daily tokens, tokens per tool, cost per model, tool calls, and projects.
Click a row to open the session as a chat: System / You / Assistant bubbles, with the tokens and cost for each trace, plus rendered content such as Markdown, code blocks, and ASCII output.
Selecting a trace opens the Trace details panel on the right. It includes cards for cost, total tokens, input, output, and cache, using the same colors as the session cards. It also shows a spans diagram of the trace and its metadata.
The divider between the chat and the details panel is draggable, so you can widen whichever side you need.
Each tool call (WebSearch, WebFetch, Read, Bash, and others) can be expanded to inspect its Input, Output, and Metadata tabs, so you can see exactly what was sent and what came back.
With the Viewer layout selected (header toggle or --view viewer), the Traces table splits into two columns.
On the left, each trace row (Trace #, prompt, start time, cost) expands to show:
- Metric cards: Tokens and Cost, each with the input / output / cache breakdown (Cost also shows each part's percentage), plus a card with Tool calls, Observations, Duration, and Model.
- The trace's observations, one row per step, marked by type (Prompt, Thinking, Tool, Response) with its tokens and cost.
Clicking an observation opens the observation viewer on the right (sticky and resizable; its width is remembered). It shows the observation's tokens and cost (estimated per observation) and its content, depending on the type:
- Tool: the invocation, plus the Input and Output in a code viewer.
- Response: the assistant message, rendered as Markdown.
- Prompt: the user message.
- Thinking: the reasoning text when present.
Prev / Next move between observations.
In the screenshot, trace #23 is expanded on the left — its Tokens and Cost cards, the Tool calls / Observations / Duration / Model card, and the observation list. On the right, the viewer shows an Edit observation with its tokens and cost, and its Input diff and Output in the code viewer.
Apache 2.0. See LICENSE.