Skip to main content

claude-top

Claude Top screenshot

A CLI + TUI utility for inspecting Claude Code usage from local session files.

claude-top reads your local Claude history (~/.claude/projects/**/*.jsonl), aggregates token/request metrics, and presents them in either:

  • an interactive Textual dashboard (default),
  • a Rich terminal table (--no-ui), or
  • JSON (--json).

What it shows

  • Total input/output tokens and request count
  • Per-model usage breakdown
  • Optional detailed stats (--detailed):
    • cache reads/writes and hit rate
    • average tokens per request
    • estimated cost (informational)
    • 7-day trend sparkline
    • week-over-week comparison
    • top projects by token usage
  • Tier-aware usage bars and warnings (80%/90%) when tier metadata is available

Requirements

  • Python 3.9+
  • Existing Claude Code data in ~/.claude/projects

Notes:

  • No setup is required to read local usage files.
  • If ~/.claude/.credentials.json is present with a valid OAuth token, claude-top fetches utilization percentages from the Anthropic OAuth usage API on a configurable interval (default: once per minute). Local session files are read more frequently to track new tokens without hitting rate limits.

Installation

Run without install (uvx)

uvx claude-top

Install globally (uv)

uv tool install claude-top

Install with pip

pip install claude-top

From source

git clone https://github.com/xpodev/claude-top.git
cd claude-top
uv pip install -e .

Usage

# Launch TUI (auto-refresh by default)
claude-top

# Print terminal table once and exit
claude-top --no-ui --once

# Print terminal table with refresh
claude-top --no-ui --watch 5

# Print JSON once and exit
claude-top --json

# Include detailed analytics
claude-top --detailed

# Fetch API utilization every 5 minutes instead of the default 1
claude-top --api-refresh 5

CLI options

  • --once: Display once and exit.
  • --no-ui: Use table output instead of the TUI.
  • --json: Print JSON output and exit.
  • --detailed: Include detailed analytics.
  • --watch N: How often to read local session files, in seconds (default: 1).
  • --api-refresh MINUTES: How often to fetch utilization percentages from the Anthropic API, in minutes (default: 1). Increase this to reduce API calls.

TUI keybindings

  • r: Refresh — fetches fresh API data and re-reads local session files
  • q: Quit

How data is calculated

  • Scans all JSONL events in ~/.claude/projects recursively.
  • Counts each assistant event as one request.
  • Aggregates token fields from each assistant message usage payload:
    • input_tokens
    • output_tokens
    • cache_creation_input_tokens
    • cache_read_input_tokens
  • Derives project names from common event path/project fields.
  • Builds last-7-day trend and week-over-week token comparison from timestamps.

Troubleshooting

"No Claude Code session data found"

claude-top only reads local Claude session files. Make sure:

  1. Claude Code has been used on this machine.
  2. ~/.claude/projects exists and contains .jsonl files.

Tier/reset countdown is missing

Tier and reset countdown information depends on OAuth metadata. If unavailable:

  • ensure ~/.claude/.credentials.json exists,
  • ensure the OAuth token is valid,
  • check network access to Anthropic API.

The tool still works with local usage data even if tier/reset metadata cannot be fetched.

Utilization percentages not updating

Usage bars reflect the last API response. By default the API is polled once per minute. Press r to force an immediate refresh, or lower --api-refresh (e.g. --api-refresh 1).

Development

# Clone repository
git clone https://github.com/xpodev/claude-top.git
cd claude-top

# Install with development dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest -q

License

MIT

Metadata

Release files for claude-top 0.3.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for claude-top 0.3.3
File Size Uploaded Provenance Actions
claude_top-0.3.3.tar.gz 158.4 kB With provenance Details for claude_top-0.3.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for claude-top 0.3.3
File Interpreter ABI Platform Actions
claude_top-0.3.3-py3-none-any.whl Python 3 none any Details for claude_top-0.3.3-py3-none-any.whl

Total release size: 186.3 kB

Release files / claude_top-0.3.3.tar.gz

Download URL claude_top-0.3.3.tar.gz
Size 158.4 kB
Tags Source
SHA-256 checksum
How to use checksums
ccb5e837418aa7e4e21a17201db6bee394b995676bc6625886e40f85d1d1dfca
BLAKE2b-256 checksum
How to use checksums
effbf6cc5f31927e4ab9fb566b4733e6cfd322c1243cd46ff53d1af4c20d3d56
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.

Transparency log

Release files / claude_top-0.3.3-py3-none-any.whl

Download URL claude_top-0.3.3-py3-none-any.whl
Size 27.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4aadc13a0b32b21b7e4cef88fe35c78f1566bcfc5ae72bf30d718a7eefb9f353
BLAKE2b-256 checksum
How to use checksums
9c126b801e36e57b98245cf98670c17522e74cc2800e07c71cbbd4a331545da6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.

Transparency log

Security for claude-top 0.3.3

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for claude_top-0.3.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.

Transparency log

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page