claude-monitor/README.md

Real-time terminal monitoring tool for Claude AI token usage

# 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)

```bash
# Run directly with npx
npx claude-monitor

# Or with pnpm
pnpm dlx claude-monitor

# Or with yarn
yarn dlx claude-monitor
```

### Global Installation

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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.