Claude Monitor

A real-time terminal monitoring tool for tracking Claude AI token usage, built with TypeScript and Node.js.

Features

• 📊 Real-time token usage monitoring
• 💰 Cost tracking and burn rate calculations
• 📈 Session-based analytics (5-hour windows)
• 🎯 Subscription plan support (Pro, Max5, Max20, Custom)
• 🔄 Automatic data refresh
• 🎨 Console-based UI with color-coded indicators
• ⚡ Efficient streaming JSONL file processing

Installation

Using npx (no installation required)

# Run directly with npx
npx claude-monitor

# Or with pnpm
pnpm dlx claude-monitor

# Or with yarn
yarn dlx claude-monitor

Global Installation

# Install globally with npm
npm install -g claude-monitor

# Or with pnpm
pnpm add -g claude-monitor

# Or with yarn
yarn global add claude-monitor

# Then run
claude-monitor

Local Development

# Clone the repository
git clone https://github.com/aistackhq/claude-monitor.git
cd claude-monitor

# Install dependencies with pnpm
pnpm install

# Run in development mode
pnpm dev

# Build the project
pnpm build

Usage

# Run with default settings
claude-monitor

# Run with specific plan
claude-monitor --plan pro

# Run with custom token limit
claude-monitor --plan custom --custom-limit 50000

# Show help
claude-monitor --help

Command Line Options

• --plan <type> - Subscription plan type (pro, max5, max20, custom)
• --custom-limit <number> - Token limit for custom plan
• --timezone <tz> - Timezone for display (e.g., UTC, America/New_York)
• --theme <theme> - Display theme (light, dark, auto)
• --time-format <format> - Time format (12h, 24h, auto)
• --refresh-rate <seconds> - Data refresh rate in seconds (1-60)
• --clear - Clear saved configuration
• --debug - Enable debug logging
• --help - Show help message
• --version - Show version

Architecture

Core Components

1. Data Layer (src/data/)

   • reader.ts - Streaming JSONL file reader
   • analyzer.ts - Session block creation and analysis

2. Core Logic (src/core/)

   • settings.ts - Configuration management with Zod validation
   • plans.ts - Subscription plan definitions
   • pricing.ts - Token cost calculations
   • calculations.ts - Burn rate and projection calculations
   • data-processors.ts - Token extraction and data processing

3. Monitoring (src/monitoring/)

   • orchestrator.ts - Central coordinator using EventEmitter

4. UI (src/ui/)

   • console-display.ts - Console-based display (current)
   • Future: blessed-display.ts - Rich terminal UI

5. Types (src/types/)

   • Type definitions and interfaces

Data Flow

Claude JSONL Files → Data Reader → Session Analyzer → Orchestrator → Display
                                                           ↓
                                                    Event Emitters

Development

Prerequisites

• Node.js >= 18.0.0
• pnpm (recommended) or npm

Scripts

• pnpm build - Build TypeScript to JavaScript
• pnpm dev - Run in development mode with tsx
• pnpm test - Run tests
• pnpm lint - Run ESLint
• pnpm format - Format code with Prettier
• pnpm type-check - Type check without building

Testing

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run with coverage
pnpm test:coverage

Publishing

The package is published to npm as claude-monitor. To publish a new version:

# Update version
pnpm version patch|minor|major

# Publish to npm
pnpm publish

Configuration

Settings are persisted in ~/.claude-monitor/last_used.json and include:

• Theme preferences
• Timezone settings
• Time format
• Refresh rate
• Custom token limits

Differences from Python Version

Improvements

• Type Safety: Full TypeScript type checking
• Async/Await: Better async handling vs Python threading
• EventEmitter: More flexible component communication
• Streaming: Efficient JSONL processing with Node.js streams
• Modern Tooling: ESLint, Prettier, Jest for development

Current Limitations

• Basic console UI (blessed UI coming soon)
• No P90 calculator for custom limits yet
• Simplified limit detection
• No notification system yet

Future Enhancements

• [ ] Full blessed terminal UI with live updates
• [ ] P90 percentile analysis for custom limits
• [ ] Cross-platform notifications
• [ ] Web dashboard option
• [ ] Export functionality (CSV, JSON)
• [ ] Historical data analysis
• [ ] Multiple project support

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.