Monitor Claude API usage with zero dependencies
npm install claude-usage-cliA completely self-contained Node.js package for monitoring Claude API usage with zero external dependencies.
This package is based on the original Claude-Code-Usage-Monitor by Maciej (maciek@roboblog.eu). This version transforms it into a zero-dependency npm package while maintaining all original functionality.
- 📊 Zero Dependencies: Pure Node.js implementation
- 🚀 Direct File Access: Reads Claude JSONL files directly (no external tools)
- 🌍 Timezone Support: Built-in Intl API for timezone handling
- 🎨 Rich Terminal UI: ANSI colors, progress bars, and formatted tables
- 📈 Comprehensive Analytics: Project-wise usage tracking and summaries
- ⚡ Fast & Lightweight: Native argument parsing and caching
bash
npm install -g claude-usage-cli
`$3
bash
npm install claude-usage-cli
`Usage
$3
bash
Show overall usage summary
claude-usage-cliShow today's usage
claude-usage-cli todayShow this week's usage
claude-usage-cli weekShow this month's usage
claude-usage-cli monthList all projects
claude-usage-cli projectsShow specific project details
claude-usage-cli project my-project-idUse different timezone
claude-usage-cli --timezone "America/New_York"Quiet mode (minimal output)
claude-usage-cli --quiet summaryShow help
claude-usage-cli --help
`$3
-
- Show overall usage summary (default)
- project - Show detailed usage for a specific project
- projects - List all projects with usage statistics
- today - Show today's usage
- week - Show this week's usage
- month - Show this month's usage
- cache [clear|stats] - Manage internal cache$3
-
-t, --timezone - Timezone for date formatting (default: system)
- -c, --config-dir - Claude configuration directory
- -p, --project-id - Specific project ID to analyze
- -v, --verbose - Verbose output
- -q, --quiet - Quiet mode - minimal output
- --no-color - Disable colored output
- --include-empty - Include projects with no usage
- -h, --help - Show help message
- --version - Show version informationArchitecture
$3
This package is completely self-contained and implements all functionality using only Node.js built-in modules:
#### Core Modules
-
lib/cli.js - Main CLI interface
- lib/monitor.js - Core monitoring logic#### Utilities (Zero Dependencies)
-
utils/args.js - Native argument parsing
- utils/terminal.js - ANSI colors, progress bars, tables
- utils/timezone.js - Intl API timezone handling
- utils/claude-data.js - Direct JSONL file parsing$3
The monitor reads directly from Claude's local configuration:
- Default Location:
~/.config/claude/projects/
- File Format: JSONL (JSON Lines) conversation files
- Cache: Built-in memory cache with configurable timeout$3
- Total tokens (input + output)
- Input tokens
- Output tokens
- Cache creation tokens
- Cache read tokens
- Request counts
- Model information
- Time ranges
- Project statistics
API Usage
javascript
const { ClaudeUsageMonitor } = require('claude-usage-cli');const monitor = new ClaudeUsageMonitor({
timezone: 'UTC',
verbose: false
});
// Get usage summary
const summary = await monitor.getSummary();
console.log(summary.formatted);
// Get project details
const project = await monitor.getProjectDetails('my-project');
console.log(project.formatted);
// List all projects
const projects = await monitor.listProjects();
console.log(projects.formatted);
`Testing
bash
Run built-in tests
npm testTest CLI directly
node lib/cli.js --help
node lib/cli.js summary
./bin/claude-usage-cli --version
`Configuration
$3
-
- Enable debug output and stack traces$3
`bash
claude-usage-cli --config-dir /custom/path/to/claude/config
``- Node.js: >= 16.0.0
- OS: Linux, macOS, Windows
- Claude CLI: Local conversation files in JSONL format
MIT License
This is a zero-dependency package. Please ensure any contributions maintain this requirement and use only Node.js built-in modules.