DOCSEARCHbyAlgolia
Submit Docs

Claude Code Usage Dashboard

repository·main·Indexed 24 days ago

https://github.com/phuryn/claude-usage

A tool and VS Code extension that reads local Claude Code JSONL usage logs to provide visual charts and cost estimates for API, Pro, and Max plans. It tracks input/output tokens, prompt cache usage, and model-specific statistics, storing data in a local SQLite database.

Tokens
3.4K
Snippets
5
Records
19
Agent score
84%

What's inside claude-usage

  1. How Claude Code Usage tracking works

    main

    The dashboard works by parsing local JSONL transcripts written by Claude Code.

    Data Source

    Claude Code writes one JSONL file per session to ~/.claude/projects/. The scanner also checks the Xcode Claude integration directory: ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/projects/.

    Data Extraction

    The scanner.py parses assistant-type records to extract:

    • message.usage.input_tokens: Raw prompt tokens
    • message.usage.output_tokens: Generated tokens
    • message.usage.cache_creation_input_tokens: Tokens written to prompt cache
    • message.usage.cache_read_input_tokens: Tokens served from prompt cache
    • message.model: The model used (e.g., claude-sonnet-4-6)

    This data is stored in a SQLite database located at ~/.claude/usage.db.

  2. Use the Claude Code Usage CLI

    main

    The claude-usage command (or python cli.py if running from source) provides several subcommands to interact with your usage data.

    Note: On macOS/Linux, use python3 instead of python if running from source. If installed via Homebrew, use claude-usage directly.

    Available Commands

    • scan: Incremental scan of JSONL files to populate the ~/.claude/usage.db database. Use --projects-dir <path> to specify a custom directory.
    • today: Show today's usage summary by model in the terminal.
    • week: Show the last 7 days with a per-day breakdown and by-model totals.
    • stats: Show all-time statistics in the terminal.
    • dashboard: Start the web app dashboard. Use --host <host> and --port <port> to configure the server, or use HOST and PORT environment variables.
    # Scan JSONL files and populate the database
python cli.py scan

# Show today's usage summary by model
python cli.py today

# Show the last 7 days
python cli.py week

# Show all-time statistics
python cli.py stats

# Scan + open browser dashboard
python cli.py dashboard

# Custom host and port
python cli.py dashboard --host 0.0.0.0 --port 9000

# Scan a custom projects directory
python cli.py scan --projects-dir /path/to/transcripts

  3. Install Claude Code Usage Dashboard

    main

    You can install the claude-usage CLI tool using several methods depending on your operating system and preferred package manager.

    macOS / Linux (Homebrew)

    First, tap the repository, then install the formula:

    brew tap phuryn/claude-usage https://github.com/phuryn/claude-usage
brew install phuryn/claude-usage/claude-usage

    Any OS (uv or pipx)

    Install directly from the git repository without a manual clone:

    uv tool install git+https://github.com/phuryn/claude-usage
# OR
pipx install git+https://github.com/phuryn/claude-usage

    Manual Clone (macOS, Linux, or Windows)

    Clone the repository and run the CLI via Python:

    git clone https://github.com/phuryn/claude-usage
cd claude-usage
# macOS/Linux:
python3 cli.py dashboard
# Windows:
python cli.py dashboard

    Docker

    Run the dashboard in a containerized environment:

    git clone https://github.com/phuryn/claude-usage
cd claude-usage
bash scripts/run-docker.sh

    Note: The Docker setup mounts ~/.claude as read-only and uses a named volume claude-usage-data for the SQLite database.

    brew tap phuryn/claude-usage https://github.com/phuryn/claude-usage
brew install phuryn/claude-usage/claude-usage
claude-usage dashboard

  4. Use the Claude Code Usage dashboard in VS Code

    main

    The extension provides a visual dashboard for tracking Claude Code usage (tokens, costs, sessions, and projects) directly in a VS Code sidebar.

    1. Click the gauge icon in the VS Code Activity Bar (left sidebar).
    2. The extension starts a local dashboard server and embeds it in a webview.
    3. Use the UI to filter by model, date range, or project.

    Note: The dashboard reads local JSONL transcripts from ~/.claude/projects/. If you see "No usage recorded", ensure you have run a Claude Code session first.

  5. Install the Claude Code Usage VS Code extension

    main

    You can install the extension using one of the following methods:

    1. VS Code Marketplace

    Search for "Claude Code Usage" (publisher: PawelHuryn) in the Extensions sidebar.

    2. Prebuilt .vsix file

    Download a .vsix from the GitHub Releases page and run:

    code --install-extension claude-usage-phuryn-<version>.vsix

    3. Build and install from source

    Clone the repository and run the platform-specific install script.

    macOS / Linux / WSL (bash):

    git clone https://github.com/phuryn/claude-usage
cd claude-usage/vscode-extension
./scripts/install.sh

    Windows (PowerShell):

    git clone https://github.com/phuryn/claude-usage
cd claude-usage/vscode-extension
powershell -ExecutionPolicy Bypass -File scripts\install.ps1

  6. Install the Claude Usage VS Code Extension

    main

    For an integrated experience, you can use the Claude Usage VS Code extension. It provides the same dashboard and charts as the web app, embedded directly into an activity-bar sidebar.

    Requirements:

    • Python 3.8+ must be on your PATH.

    Installation:

    1. Install via the VS Code Marketplace or Open VSX Registry.
    2. Click the gauge icon in the activity bar to spawn the server and render the dashboard.

  7. Understand how the extension resolves the Claude Usage dashboard

    main

    The extension uses several methods to determine how to launch the dashboard. The resolution order is as follows:

    1. Explicit Configuration: Uses the path provided in the claudeUsage.cliPath setting (if it points to a valid cli.py).
    2. Bundled CLI: Uses the python/cli.py shipped inside the extension package (.vsix). This is the recommended mode for most users as it only requires Python to be on your PATH.
    3. Homebrew/PATH: Searches for a claude-usage binary on your system PATH (e.g., installed via Homebrew).
    4. Workspace Discovery: Searches any open VS Code workspace folders for a cli.py.
    5. Monorepo Development: If running from source, it looks for cli.py in the parent directory of the extension folder.

    If none of these are found, the mode is set to none.

  8. Configure Claude Code Usage settings

    main

    The following settings are available in VS Code:

    SettingDefaultDescription
    claudeUsage.pythonPath(auto-discover)Path to a Python 3.8+ interpreter. If empty, it auto-detects (claude-usage on PATH, then python3, then python).
    claudeUsage.cliPath(bundled)Path to a custom cli.py or its parent directory. If empty, the bundled version is used.
    claudeUsage.port0Port for the local dashboard server. 0 allows the OS to pick a free port.

  9. How the dashboard is invoked via different InstallModes

    main

    The extension uses different command structures depending on how the tool was installed:

    • brew mode: Invokes the binary directly with the dashboard argument.
      • Command: [binary] dashboard [extraArgs]
    • clone mode: Invokes the Python interpreter with the cli.py path and the dashboard argument.
      • Command: [python] [cliPy] dashboard [extraArgs]

    Note: clone mode requires a Python interpreter to be available.

  10. Troubleshoot Claude Code Usage extension issues

    main

    Common issues and solutions:

    • "Python 3.8 or newer required": Install Python 3.8+ from python.org. On Windows, ensure "Add Python to PATH" is checked during installation. After installing, run Developer: Reload Window from the Command Palette.
    • Sidebar stays blank or shows "starting...": Run the Claude Usage: Show Logs command. Check the output channel for the resolved Python path and server errors.
    • Dashboard shows "No usage recorded": Ensure Claude Code has actually written transcripts to ~/.claude/projects/. Run a Claude Code session to generate data.

  12. Configure Claude Usage VS Code settings

    main

    The extension can be customized via the claudeUsage configuration namespace in VS Code settings. Use these keys to specify paths for the CLI and Python runtime, or to set a specific port for the dashboard.

    • claudeUsage.pythonPath: (string) The path to the Python executable. Required if using a clone install mode.
    • claudeUsage.cliPath: (string) The path to the claude-usage CLI. If set to an invalid path, the extension may fail to find an installation. Clearing this allows the extension to fall back to bundled sources.
    • claudeUsage.port: (number) The port on which the dashboard server should bind. The extension attempts to reuse the last successful port to preserve localStorage state in the dashboard webview.