claude-code-tracer 0.1.1

Analytics dashboard for Claude Code sessions

Claude Code Tracer - Backend

FastAPI-based analytics API for Claude Code sessions. Reads session data from ~/.claude/projects/ and provides endpoints for viewing metrics, messages, tool usage, and subagent activity.

Installation

# Using pip
pip install claude-code-tracer

# Using uv
uv tool install claude-code-tracer

# Run the dashboard
cctracer

Project Structure

src/claude_code_tracer/
├── main.py              # FastAPI app entry point
├── routers/
│   ├── sessions.py      # Session and message endpoints
│   ├── metrics.py       # Aggregated metrics endpoints
│   └── subagents.py     # Subagent-specific endpoints
├── models/
│   ├── entries.py       # Base data models (TokenUsage, ToolUse)
│   └── responses.py     # API response models
└── services/
    ├── database.py      # DuckDB connection, file discovery
    ├── log_parser.py    # JSONL session parsing
    ├── metrics.py       # Cost calculation, pricing
    └── queries.py       # DuckDB SQL queries

API Endpoints

Projects

Endpoint	Description
GET /api/projects	List all projects with aggregated metrics
GET /api/projects/{hash}/sessions	List sessions for a project
GET /api/projects/{hash}/metrics	Aggregated metrics across all sessions
GET /api/projects/{hash}/tools	Tool usage across all sessions

Sessions

Endpoint	Description
GET /api/sessions/{hash}/{id}	Session details
GET /api/sessions/{hash}/{id}/messages	Paginated messages (supports filtering)
GET /api/sessions/{hash}/{id}/messages/filters	Available filter options
GET /api/sessions/{hash}/{id}/messages/{uuid}	Single message detail
GET /api/sessions/{hash}/{id}/messages/by-index/{idx}	Message by index
GET /api/sessions/{hash}/{id}/metrics	Session metrics
GET /api/sessions/{hash}/{id}/tools	Tool usage stats
GET /api/sessions/{hash}/{id}/subagents	Subagents spawned
GET /api/sessions/{hash}/{id}/skills	Skills invoked
GET /api/sessions/{hash}/{id}/code-changes	File changes
GET /api/sessions/{hash}/{id}/errors	Error entries
GET /api/sessions/{hash}/{id}/commands	User commands

Subagents

Endpoint	Description
GET /api/subagents/{hash}/{agent_id}	Subagent details
GET /api/subagents/{hash}/{agent_id}/tools	Subagent tool usage
GET /api/subagents/{hash}/{session_id}/{agent_id}	Subagent within session context
GET /api/subagents/{hash}/{session_id}/{agent_id}/messages	Subagent messages

Metrics

Endpoint	Description
GET /api/metrics/pricing	Current model pricing (from LiteLLM)
GET /api/metrics/daily/{hash}	Daily metrics for a project
GET /api/metrics/aggregate	Global or per-project aggregates

Health

Endpoint	Description
GET /	API info
GET /health	Health check

CLI Usage

cctracer                  # Start server, opens browser at http://localhost:8420
cctracer --port 9000      # Custom port
cctracer --no-browser     # Don't auto-open browser
cctracer --reload         # Enable auto-reload for development

Development Setup

# Install dependencies
uv sync --all-extras

# Run development server
uv run uvicorn claude_code_tracer.main:app --reload --port 8420

# Or use the CLI with reload
uv run cctracer --reload

# API docs at http://localhost:8420/docs

Environment Variables

Variable	Default	Description
CLAUDE_DIR	~/.claude	Claude data directory

Development

# Linting and formatting
uv run ruff check .
uv run ruff format .

# Type checking
uv run mypy src/

# Run tests
uv run pytest

Tech Stack

• FastAPI - Web framework
• DuckDB - In-memory SQL for querying JSONL files
• Pydantic - Data validation and serialization
• orjson - Fast JSON parsing
• httpx - HTTP client for fetching pricing data