|
| 1 | +# Claude Code Usage — VS Code extension |
| 2 | + |
| 3 | +[](LICENSE.txt) |
| 4 | + |
| 5 | +**See your Claude Code usage — tokens, costs, sessions, projects — right inside VS Code.** |
| 6 | + |
| 7 | + |
| 8 | + |
| 9 | +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. |
| 10 | + |
| 11 | +Works on **API, Pro, and Max plans**. Captures usage from the Claude Code CLI, the official VS Code extension, and dispatched Code sessions. |
| 12 | + |
| 13 | +--- |
| 14 | + |
| 15 | +## Install |
| 16 | + |
| 17 | +### From the VS Code Marketplace |
| 18 | + |
| 19 | +Search the Extensions sidebar for **"Claude Code Usage"** (publisher: `PawelHuryn`), or open the marketplace link from the Open VSX page. |
| 20 | + |
| 21 | +### From a `.vsix` file (local install) |
| 22 | + |
| 23 | +``` |
| 24 | +git clone https://github.com/phuryn/claude-usage |
| 25 | +cd claude-usage/vscode-extension |
| 26 | +./scripts/install.sh # macOS / Linux / WSL |
| 27 | +.\scripts\install.ps1 # Windows PowerShell |
| 28 | +``` |
| 29 | + |
| 30 | +The scripts run `vsce package` then `code --install-extension` against your local VS Code install. |
| 31 | + |
| 32 | +--- |
| 33 | + |
| 34 | +## Requirements |
| 35 | + |
| 36 | +- **Python 3.8 or newer on your `PATH`.** Almost everyone running Claude Code already has Python installed; if not, see [python.org/downloads](https://www.python.org/downloads/). On Windows make sure to check **"Add Python to PATH"** during the installer. |
| 37 | + |
| 38 | +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. |
| 39 | + |
| 40 | +--- |
| 41 | + |
| 42 | +## Usage |
| 43 | + |
| 44 | +1. Click the **gauge icon** in the activity bar (left sidebar of VS Code). |
| 45 | +2. The extension starts the dashboard server on a free local port and embeds it in a sidebar webview. |
| 46 | +3. Filter by model, range, or project — same UI as the standalone web dashboard. |
| 47 | + |
| 48 | + |
| 49 | + |
| 50 | +### Commands |
| 51 | + |
| 52 | +Open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`): |
| 53 | + |
| 54 | +| Command | What it does | |
| 55 | +|---|---| |
| 56 | +| **Claude Usage: Open Dashboard** | Reveal the sidebar and start the server (also fires automatically when you click the activity-bar icon) | |
| 57 | +| **Claude Usage: Rescan Transcripts** | Refresh the iframe; the dashboard's own Rescan button triggers a full DB rebuild | |
| 58 | +| **Claude Usage: Restart Server** | Kill and respawn the Python process (use after changing settings) | |
| 59 | +| **Claude Usage: Show Logs** | Open the extension's output channel — useful when something doesn't work | |
| 60 | + |
| 61 | +### Settings |
| 62 | + |
| 63 | +| Setting | Default | Description | |
| 64 | +|---|---|---| |
| 65 | +| `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`). | |
| 66 | +| `claudeUsage.cliPath` | _(bundled)_ | Path to a custom `cli.py` (or its parent directory). Empty = use the bundled copy that ships with the extension. | |
| 67 | +| `claudeUsage.port` | `0` | Port for the local dashboard server. `0` = OS picks a free one. | |
| 68 | + |
| 69 | +--- |
| 70 | + |
| 71 | +## How discovery works |
| 72 | + |
| 73 | +When you click the icon, the extension resolves how to run the dashboard in this order: |
| 74 | + |
| 75 | +1. **`claudeUsage.cliPath` setting** if you've set one |
| 76 | +2. **The bundled `python/cli.py`** that ships inside this `.vsix` (most installs hit this) |
| 77 | +3. The `claude-usage` shim on `PATH` (if you installed via Homebrew) |
| 78 | +4. A `cli.py` in any open VS Code workspace folder (the legacy "open the cloned repo" path) |
| 79 | +5. A sibling `cli.py` from the extension dir (dev mode, when running from source via F5) |
| 80 | + |
| 81 | +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. |
| 82 | + |
| 83 | +--- |
| 84 | + |
| 85 | +## Privacy |
| 86 | + |
| 87 | +The extension only: |
| 88 | +- Reads local JSONL transcripts from `~/.claude/projects/` (and the Xcode coding-assistant directory on macOS, if present) |
| 89 | +- 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 |
| 90 | +- Embeds that server's dashboard in a VS Code webview |
| 91 | + |
| 92 | +No data leaves your machine. No API calls. No telemetry. |
| 93 | + |
| 94 | +--- |
| 95 | + |
| 96 | +## Troubleshooting |
| 97 | + |
| 98 | +- **"Python 3.8 or newer required"** — install from [python.org](https://www.python.org/downloads/) and reload VS Code (`Ctrl+Shift+P` → `Developer: Reload Window`). On Windows make sure "Add Python to PATH" is checked in the installer. |
| 99 | +- **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. |
| 100 | +- **Dashboard renders but shows "No usage recorded"** — Claude Code hasn't written transcripts to `~/.claude/projects/` yet. Run a Claude Code session first. |
| 101 | + |
| 102 | +--- |
| 103 | + |
| 104 | +## Source |
| 105 | + |
| 106 | +The Python tool, this extension, and a Homebrew formula all live at [github.com/phuryn/claude-usage](https://github.com/phuryn/claude-usage). Bug reports and feature discussions: [Issues](https://github.com/phuryn/claude-usage/issues), [Discussions](https://github.com/phuryn/claude-usage/discussions). |
| 107 | + |
| 108 | +**Made by** [The Product Compass Newsletter](https://www.productcompass.pm). |
0 commit comments