claude-usage-monitor/README.md

Real-time CLI dashboard for monitoring Claude AI token usage with 5-hour session tracking

# Claude Usage Monitor

A real-time CLI dashboard for monitoring Claude AI token usage with automatic 5-hour session window tracking.

```
CLAUDE USAGE

5-Hour Session Window

session-foo        22:04 - 22:04 (0h 0m)     5,531   4h 56m left
session-foo        20:54 - 22:01 (1h 6m)    71,490   3h 46m left
session-bar        20:40 - 22:06 (1h 26m)   306,090  3h 32m left
session-bar        16:48 - 20:36 (3h 48m)   464,667  Expired
─────────────────────────────────────────────────────────────────
Total (5hr): 847,778 tokens
```

## Installation

```bash
npm install -g claude-usage-monitor
```

## Prerequisites

- Node.js >= 16.0.0
- [ccusage](https://www.npmjs.com/package/ccusage) CLI tool (automatically installed as dependency)
- Access to Claude API usage data through `~/.claude` directory

## Usage

```bash
npx claude-usage-monitor@latest
```

Refreshes every minute.

## How It Works

The tool:
1. Reads session data from `~/.claude/projects` directory
2. Fetches usage statistics using the ccusage CLI
3. Calculates estimated token usage based on message content
4. Displays a responsive dashboard that adapts to terminal size
5. Updates in the background every 60 seconds

## Development

```bash
git clone https://github.com/agudulin/claude-usage-monitor.git
cd claude-usage-monitor

npm install
npm run dev
```