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
1 maintainer
Metadata
1 maintainer
Release files for claude-code-tracer 0.1.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| claude_code_tracer-0.1.4.tar.gz | 320.4 kB | Without provenance | Details for claude_code_tracer-0.1.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| claude_code_tracer-0.1.4-py3-none-any.whl | Python 3 | none | any | Details for claude_code_tracer-0.1.4-py3-none-any.whl |
Total release size: 652.5 kB
Release files / claude_code_tracer-0.1.4.tar.gz
| Download URL | claude_code_tracer-0.1.4.tar.gz |
|---|---|
| Size | 320.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
39483575bf56422fec257e34e0b4c7ac3dc7727d80e91120c979cb53d265f4b0
|
|
BLAKE2b-256 checksum How to use checksums |
904a2cf8e968920256f147ec0df043b63a85fee6ca5e8a3af1c57053dca5fee7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.13 {"installer":{"name":"uv","version":"0.9.13"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / claude_code_tracer-0.1.4-py3-none-any.whl
| Download URL | claude_code_tracer-0.1.4-py3-none-any.whl |
|---|---|
| Size | 332.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0f857a1b81ffd0ffd8be93c00729e261e9200bfe561b38a15b7f10f387e6686a
|
|
BLAKE2b-256 checksum How to use checksums |
c3bea4c654f57bd3a049754391548caafc4d6586d68018f402aac94d41242780
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.13 {"installer":{"name":"uv","version":"0.9.13"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for claude-code-tracer 0.1.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
