Claude Usage CLI

View your Claude Code API usage directly in your terminal 📊

A beautiful command-line tool to visualize Claude Code token usage, costs, and activity across all your projects.

Features

✨ Interactive Mode - Beautiful menu-driven interface with Claude branding 📊 Token Breakdown - Input, Output, Cache Write, and Cache Read tokens by model 📁 Project Analytics - View usage breakdown by project 💬 Session Details - Drill down to individual session messages 🎨 Beautiful Output - Colorful tables with proper formatting and emojis ⚡ Fast & Lightweight - No external services, reads local Claude data

Quick Start

Using npx (Recommended)

Run instantly without installation:

npx claude-usage-cli

Installation

Install globally to use anywhere:

npm install -g claude-usage-cli

Then simply run:

claude-usage

Usage

Interactive Mode (Default)

Running claude-usage launches an interactive menu where you can explore your usage data:

claude-usage

The interactive mode features:

• 📊 Summary with total sessions, messages, tokens, and costs
• 📅 Last 7 Days Activity
• 💎 Token Usage by Model
• 📁 All Projects view
• 🔄 Refresh Data
• Beautiful Claude ASCII art header in orange

Commands

Overview

Shows total usage statistics, token breakdown by model, and recent activity:

claude-usage overview

List Projects

View all projects with session counts and total costs:

claude-usage projects

View Project

See all sessions within a specific project:

claude-usage project /path/to/project

View Session

Get detailed message-level breakdown for a session:

claude-usage session <session-id>

# Or specify project
claude-usage session <session-id> --project /path/to/project

Configuration

Check current settings and data directory:

claude-usage config

Options

Custom Data Directory

By default, the tool reads from ~/.claude. To use a different location:

claude-usage --data-dir /custom/path/to/claude/data

Or set the CLAUDE_DATA_DIR environment variable:

export CLAUDE_DATA_DIR=/custom/path/to/claude/data
claude-usage

Example Output

Interactive Mode

   ██████╗██╗      █████╗ ██╗   ██╗██████╗ ███████╗
  ██╔════╝██║     ██╔══██╗██║   ██║██╔══██╗██╔════╝
  ██║     ██║     ███████║██║   ██║██║  ██║█████╗
  ██║     ██║     ██╔══██║██║   ██║██║  ██║██╔══╝
  ╚██████╗███████╗██║  ██║╚██████╔╝██████╔╝███████╗
   ╚═════╝╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝

           Usage Visualizer  ・  Track your AI costs

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Summary:
  💬 Total Sessions:      32
  📨 Total Messages:      5,393
  🔢 Total Tokens Used:   141,115,796
  ⬆️  Total Input Tokens:  54,341,054
  ⬇️  Total Output Tokens: 12,326
  💰 Estimated Cost:      $1063.1512

? What would you like to see? (Use arrow keys)
❯ 📅 Last 7 Days Activity
  💎 Token Usage by Model
  📁 All Projects
  ──────────────
  🔄 Refresh Data
  ❌ Exit

Token Usage by Model

💎 Token Usage by Model:

┌───────────────────────┬────────────┬────────┬─────────────┬────────────┬───────────┐
│ Model                 │      Input │ Output │ Cache Write │ Cache Read │      Cost │
├───────────────────────┼────────────┼────────┼─────────────┼────────────┼───────────┤
│ opus-4-6              │ 54,272,618 │  4,678 │     428,133 │  1,735,051 │ $825.0702 │
│ sonnet-4-5 (20250929) │     17,478 │    568 │   1,852,448 │ 21,403,174 │  $13.4286 │
└───────────────────────┴────────────┴────────┴─────────────┴────────────┴───────────┘

How It Works

Claude Usage CLI reads your local Claude Code data files:

• stats-cache.json - Aggregated statistics
• history.jsonl - Session metadata and names
• projects/ - Individual session message logs

All data stays local. No external API calls or data transmission.

Development

Local Development

# Clone the repository
git clone <your-repo>
cd claude-usage-cli

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run locally
node dist/index.js

# Or use tsx for development
npm run dev

Project Structure

src/
├── index.ts          # Main CLI entry point
├── types.ts          # TypeScript type definitions
├── config.ts         # Configuration and data directory
├── loader.ts         # Data loading from Claude files
├── pricing.ts        # Token pricing and cost calculation
└── commands/         # CLI command implementations
    ├── interactive.ts # Interactive menu mode
    ├── overview.ts
    ├── projects.ts
    ├── project.ts
    ├── session.ts
    └── config.ts

Requirements

• Node.js >= 18.0.0
• Claude Code data directory (usually ~/.claude)

Publishing to npm

To make this available via npx for everyone:

1. Create an npm account at npmjs.com
2. Login locally: npm login
3. Update package name to be unique (if needed)
4. Publish: npm publish

Then users can run:

npx claude-usage-cli

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.

---

Created by Hamid 👋