Skip to content

README.md

Latest commit

 

History

History
125 lines (78 loc) · 6.05 KB

README.md

File metadata and controls

125 lines (78 loc) · 6.05 KB

Claude Code Usage — VS Code extension

License: MIT

See your Claude Code usage — tokens, costs, sessions, projects — right inside VS Code.

Daily usage view

The extension reads your local Claude Code JSONL transcripts (the ones Claude Code already writes regardless of plan) and renders the same dashboard the Python tool ships, embedded as a VS Code sidebar. No API calls, no telemetry — all data stays on your machine.

Works on API, Pro, and Max plans. Captures usage from the Claude Code CLI, the official VS Code extension, and dispatched Code sessions.

Install

From the VS Code Marketplace

Search the Extensions sidebar for "Claude Code Usage" (publisher: PawelHuryn), or open the marketplace link from the Open VSX page.

From a prebuilt .vsix (no build step)

Every GitHub Release attaches a ready-built .vsix. Download it, then either drag it onto the VS Code Extensions view, or run:

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

Build and install from source

Clone the repo and run the install script for your platform. Each script builds the .vsix (npm install + vsce package) and then installs it via code --install-extension — you don't need an existing .vsix, the script produces one.

macOS / Linux / WSL (bash):

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

Windows — run the script in PowerShell. Invoking .\scripts\install.ps1 from Git Bash (or double-clicking it) just opens the file in an editor, because Windows maps .ps1 to "Edit", not "Run". The line below runs it regardless of which shell you're in or your execution-policy setting:

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

Requirements

  • Python 3.8 or newer on your PATH. Almost everyone running Claude Code already has Python installed; if not, see python.org/downloads. On Windows make sure to check "Add Python to PATH" during the installer.

That's the only dependency. The Python sources (cli.py, scanner.py, dashboard.py) are bundled inside the extension — no separate clone or Homebrew install needed.

Usage

  1. Click the gauge icon in the activity bar (left sidebar of VS Code).
  2. The extension starts the dashboard server on a free local port and embeds it in a sidebar webview.
  3. Filter by model, range, or project — same UI as the standalone web dashboard.

Hourly + project breakdown

Commands

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Command What it does
Claude Usage: Open Dashboard Reveal the sidebar and start the server (also fires automatically when you click the activity-bar icon)
Claude Usage: Rescan Transcripts Refresh the iframe; the dashboard's own Rescan button runs an incremental scan that adds new usage without touching existing history
Claude Usage: Restart Server Kill and respawn the Python process (use after changing settings)
Claude Usage: Show Logs Open the extension's output channel — useful when something doesn't work

Settings

Setting Default Description
claudeUsage.pythonPath (auto-discover) Path to a Python 3.8+ interpreter. Leave empty to auto-detect (claude-usage on PATH first, then python3, then python).
claudeUsage.cliPath (bundled) Path to a custom cli.py (or its parent directory). Empty = use the bundled copy that ships with the extension.
claudeUsage.port 0 Port for the local dashboard server. 0 = OS picks a free one.

How discovery works

When you click the icon, the extension resolves how to run the dashboard in this order:

  1. claudeUsage.cliPath setting if you've set one
  2. The bundled python/cli.py that ships inside this .vsix (most installs hit this)
  3. The claude-usage shim on PATH (if you installed via Homebrew)
  4. A cli.py in any open VS Code workspace folder (the legacy "open the cloned repo" path)
  5. A sibling cli.py from the extension dir (dev mode, when running from source via F5)

If none of those find anything, you'll get a friendly message in the sidebar — most often "Python 3.8+ is required" with a platform-specific install hint.

Privacy

The extension only:

  • Reads local JSONL transcripts from ~/.claude/projects/ (and the Xcode coding-assistant directory on macOS, if present)
  • Runs a small HTTP server bound to 127.0.0.1 (localhost-only — never 0.0.0.0) on a port the OS picks for you
  • Embeds that server's dashboard in a VS Code webview

No data leaves your machine. No API calls. No telemetry.

Troubleshooting

  • "Python 3.8 or newer required" — install from python.org and reload VS Code (Ctrl+Shift+P → Developer: Reload Window). On Windows make sure "Add Python to PATH" is checked in the installer.
  • Sidebar stays blank or shows "starting…" — run Claude Usage: Show Logs. The extension logs the resolved Python path, the install mode, the spawn command, and any stdout/stderr from the server.
  • Dashboard renders but shows "No usage recorded" — Claude Code hasn't written transcripts to ~/.claude/projects/ yet. Run a Claude Code session first.

Source

The Python tool, this extension, and a Homebrew formula all live at github.com/phuryn/claude-usage. Bug reports and feature discussions: Issues, Discussions.

Made by The Product Compass Newsletter.