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

Sessions

Subagents

Metrics

Health

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

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