PAR CC Usage

Claude Code usage tracking tool with real-time monitoring and analysis.

Real-time monitoring interface showing token usage, burn rate analytics, tool usage tracking, and project activity

Table of Contents

• Features
  • 📊 Real-Time Monitoring
  • 🔥 Advanced Burn Rate Analytics
  • ⚙️ Intelligent Block Management
  • 📏 P90 Progress Bar Limits
  • 🎯 Smart Features
  • 💰 Cost Tracking & Pricing
  • 📁 File System Support
  • 🌐 Configuration & Customization
  • 🎨 Theme System
  • 🔔 Notification System
  • 📈 Usage Summary Analytics
  • 💻 Claude Code Status Line
  • 🛠️ Developer Tools
• Installation
• Claude Code Status Line Integration
  • Quick Setup
  • Manual Setup
  • Status Line Display
  • Commands
  • Configuration
• Usage
  • Monitor Token Usage
  • List Usage Data
  • Usage Summary Analytics
  • Configuration Management
  • Cache Management
  • Webhook Notifications
  • JSONL Analysis
  • Debug Commands
• Configuration
  • Directory Structure
  • Legacy Migration
  • Config File Example
  • Environment Variables
• Display Features
  • Unified Block System
  • Current Billing Block Identification
  • Manual Override
  • Compact Interface
  • Optional Session Details
  • Project Aggregation Mode
  • Smart Token Limit Management
  • Model Display Names and Token Multipliers
  • Time Format Options
  • Project Name Customization
  • Cost Tracking & Pricing
  • Webhook Notifications
• File Locations
  • XDG Base Directory Specification
  • Configuration Files
  • Legacy File Migration
  • Environment Variable Override
• Coming Soon
• What's New
  • v0.17.0 - ANSI Theme & Dependency Updates
  • v0.16.0 - Last Message Time Display
  • v0.15.0 - Opus 4.5 Model Support
  • v0.14.0 - Tool Usage Tracking
  • v0.13.0 - MCP Tool Differentiation
  • v0.12.0 - Theme System
  • older...
• Development

Features

📊 Real-Time Monitoring

• Live token tracking: Monitor usage across all Claude Code projects in real-time
• 5-hour billing blocks: Unified block system that accurately reflects Claude's billing structure
• Multi-session support: When multiple sessions are active, they share billing blocks intelligently
• Visual progress indicators: Real-time progress bars for current billing period
• Stable console interface: Clean, jump-free display with automatic suppression of disruptive output

🔥 Advanced Burn Rate Analytics

• Per-minute tracking: Granular burn rate display (tokens/minute) for precise monitoring
• Estimated completion: Projects total usage for full 5-hour block based on current rate
• ETA with clock time: Shows both duration and actual time when limit will be reached
• Smart color coding: Visual indicators based on usage levels (green/orange/red)

⚙️ Intelligent Block Management

• Smart strategy: Intelligent algorithm that automatically selects optimal billing blocks
• Manual override: CLI option to set custom block start times for testing or corrections
• Automatic detection: Smart detection of session boundaries and billing periods
• Gap handling: Proper handling of inactivity periods longer than 5 hours

📏 P90 Progress Bar Limits

• Stable progress bars: Uses 90th percentile (P90) values instead of absolute maximums for more realistic progress indicators
• Outlier filtering: Automatically ignores extreme usage spikes that can skew progress displays
• Realistic projections: Shows typical usage patterns while capturing 90% of historical data
• Visual P90 indicator: Clear "(P90)" labels when P90 mode is active
• Configurable: Toggle between P90 and absolute maximum via --no-p90 flag or config setting

🎯 Smart Features

• Auto-adjusting limits: Automatically increases token limits when exceeded and saves to config
• Deduplication: Prevents double-counting using message and request IDs
• Model name simplification: Clean display names (Opus, Sonnet) for better readability
• Session sorting: Newest-first ordering for active sessions
• Per-model token tracking: Accurate token attribution with proper multipliers (Opus 5x, others 1x)
• Compact display mode: Minimal interface option for reduced screen space usage

💰 Cost Tracking & Pricing

• Real-time cost calculations: Live cost tracking using LiteLLM pricing data
• Per-model cost breakdown: Accurate cost attribution for each Claude model
• Monitor pricing integration: Optional cost columns in project and session views with --show-pricing
• List command pricing: Full cost analysis support in table, JSON, and CSV outputs with --show-pricing and intelligent cost hierarchy
• Burn rate cost estimation: Real-time 5-hour block cost projection based on current spending rate
• Configurable pricing display: Enable/disable cost tracking via configuration or command-line
• Export with costs: JSON and CSV exports include cost data and cost source transparency when pricing is enabled
• Integrated pricing cache: Efficient pricing lookups with built-in caching
• Intelligent fallbacks: When exact model names aren't found, uses pattern matching to find closest pricing
• Unknown model handling: Models marked as "Unknown" automatically display $0.00 cost
• Robust error handling: Missing pricing data doesn't break functionality or display

📁 File System Support

• Multi-directory monitoring: Supports both legacy (~/.claude/projects) and new paths
• Efficient caching: File position tracking to avoid re-processing entire files
• Cache management: Optional cache disabling for full file reprocessing
• JSONL analysis: Deep analysis of Claude Code data structures
• XDG Base Directory compliance: Uses standard Unix/Linux directory conventions
• Legacy migration: Automatically migrates existing config files to XDG locations
• Read-only mode: Optional config protection to prevent automatic limit updates

🌐 Configuration & Customization

• XDG directory compliance: Config, cache, and data files stored in standard locations
• Automatic migration: Legacy config files automatically moved to XDG locations
• Automatic timezone detection: Seamlessly detects system timezone changes, with manual override support
• Dynamic baseline updates: update-maximums command automatically updates configuration limits based on actual usage patterns
• Read-only protection: Automatic read-only mode activation to prevent accidental configuration changes
• Time formats: 12-hour or 24-hour time display options
• Project name cleanup: Strip common path prefixes for cleaner display
• Flexible output: Table, JSON, and CSV export formats

🎨 Theme System

• Multiple built-in themes: Choose from 6 carefully crafted themes for different preferences
• Light and dark themes: Options for both dark terminal and light terminal users
• Terminal-native ANSI theme: Respects your terminal's color palette (great for Catppuccin, Dracula, etc.)
• Accessibility support: High contrast theme meeting WCAG AAA standards
• Session-based overrides: Temporarily change themes for individual command runs
• Rich color integration: Semantic color system with consistent visual language
• CLI theme management: Built-in commands for theme configuration and preview

🔔 Notification System

• Discord integration: Webhook notifications for billing block completion
• Smart filtering: Only notifies for blocks with actual activity
• Cooldown protection: Configurable minimum time between notifications
• Rich information: Detailed usage statistics in notifications

📈 Usage Summary Analytics

• Time-based analysis: Generate summaries by daily, weekly, monthly, or all-time periods
• Statistical insights: Totals, averages, and P90 values for tokens, messages, and costs
• Usage patterns: Identify peak usage periods and typical session sizes
• Model breakdown: Analyze which Claude models are used most frequently
• Tool usage tracking: See which tools (Read, Edit, Bash, etc.) are used most often
• Export capabilities: JSON and CSV export for external analysis and reporting
• Flexible period filtering: Limit analysis to recent periods (last N days/weeks/months)

💻 Claude Code Status Line

• Real-time status bar: Display token usage directly in Claude Code's interface
• Auto-installation: Simple one-command setup with pccu install-statusline
• Session tracking: Show per-session or grand total usage statistics
• Live updates: Automatically refreshes when monitoring is active

🛠️ Developer Tools

• Debug commands: Comprehensive debugging tools for block calculation and timing
• Activity analysis: Historical activity pattern analysis
• JSONL analyzer: Built-in jsonl_analyzer.py tool for examining Claude Code data files
• Webhook testing: Built-in Discord and Slack webhook testing

Installation

Option 1: Install from PyPI (Recommended)

Using uv (fastest):

uvx --from par-cc-usage pccu monitor
# or installing into the $PATH
uv tool install par-cc-usage

Using pip:

pip install par-cc-usage

After installation, you can run the tool directly:

pccu monitor

Option 2: Development Installation

Clone the repository and install in development mode:

# Clone the repository
git clone https://github.com/paulrobello/par_cc_usage.git
cd par_cc_usage

# Install with uv (recommended)
uv sync

# Or install with pip
pip install -e .

Run the tool in development mode:

# Using uv
uv run pccu monitor

# Or using make (if available)
make run

# Or directly with Python
python -m par_cc_usage.main monitor

Prerequisites

• Python 3.11 or higher
• Claude Code must be installed and have generated usage data
• uv (recommended) or pip for installation

Claude Code Status Line Integration

PAR CC Usage can display real-time token usage directly in Claude Code's status bar at the bottom of the interface.

Quick Setup

Install the status line with a single command:

pccu install-statusline

This will automatically configure Claude Code to display your token usage. Restart Claude Code to see the changes.

Manual Setup

If you prefer to configure manually, add this to your ~/.claude/settings.json:

"statusLine": {
  "type": "command",
  "command": "pccu statusline"
}

Status Line Display

The status line shows (v0.9.0+):

• Project name in square brackets for context
• 🪙 Token count with limit and percentage
• 💬 Message count with limit
• 💰 Cost tracking with limit (calculated from token usage)
• ⏱️ Time remaining in current 5-hour billing block

Example: [parllama] - 🪙 495.7M/510.7M (97%) - 💬 736/1,734 - 💰 $155.27/$166.80 - ⏱️ 2h 8m

Status Line Behavior:

• By default, shows per-session usage (tracks your current Claude Code session)
• Can be configured to always show grand total across all sessions
• Both modes include real-time cost calculations based on token usage
• Displays remaining time in the current billing block (e.g., "2h 8m" or "45m")
• Updates automatically as you interact with Claude Code

Important: The status line is updated when pccu monitor is running. For real-time updates, keep the monitor running in a terminal.

Commands

# Install status line into Claude Code
pccu install-statusline

# Install with force (skip confirmation prompts)
pccu install-statusline --force

# Remove status line from Claude Code
pccu uninstall-statusline

# Remove with force (skip confirmation prompts)
pccu uninstall-statusline --force

# Configure status line template
pccu configure-statusline

Configuration

Control status line behavior in your config.yaml:

# Enable/disable status line generation (default: true)
statusline_enabled: true

# Always show grand total instead of per-session (default: false)
statusline_use_grand_total: false

# Progress bar customization (v0.10.0+)
statusline_progress_bar_colorize: true  # Colorize progress bars based on usage (green/yellow/red)
statusline_progress_bar_style: rich     # Style: 'basic' (blocks █░) or 'rich' (lines ━╺)
statusline_progress_bar_length: 15      # Length of progress bar (default: 15)
statusline_progress_bar_show_percent: true  # Show percentage in center of bar

# Custom status line template (advanced)
statusline_template: '{project}{sep}{tokens}{sep}{messages}{sep}{cost}{sep}{remaining_block_time}{sep} SES:{session_tokens}/{session_tokens_total}{sep}{session_tokens_progress_bar}'

Progress Bar Features (v0.10.0+)

• Colorization: Progress bars change color based on usage (green < 50%, yellow 50-79%, red ≥ 80%)
• Rich Style: Cleaner line-based progress bars (━╺) instead of blocks (█░)
• Percentage Display: Optional percentage shown in center of progress bar
• Session Token Tracking: Display session-specific token usage with progress bars
• Model Display: Show current Claude model name (Opus, Sonnet) with {model} template variable
• Performance Optimized: Conditional data fetching - only retrieves git status, session tokens, etc. when needed in template

The status line automatically updates whenever you run pccu monitor, providing real-time usage feedback directly in your Claude Code interface.

Usage

Monitor Token Usage

Monitor token usage in real-time with comprehensive options:

# Basic monitoring (default 5-second interval)
pccu monitor

# Compact mode for minimal display
pccu monitor --compact

# Basic monitoring (sessions shown by default)
pccu monitor

# High-frequency monitoring with custom settings
pccu monitor --interval 2 --token-limit 1000000 --show-sessions

# Monitor with custom configuration
pccu monitor --config production-config.yaml

# P90 vs Absolute Maximum options
pccu monitor  # Default: P90 limits for stable progress bars
pccu monitor --no-p90  # Use absolute maximum values instead

# Testing and debugging scenarios
pccu monitor --no-cache --block-start 18  # Fresh scan + custom block timing
pccu monitor --block-start 14 --show-sessions  # Override block start time
pccu monitor --debug  # Enable debug output to see processing messages

# Production monitoring examples
pccu monitor --interval 10 --token-limit 500000  # Conservative monitoring
pccu monitor --show-sessions --config team-config.yaml  # Team dashboard
pccu monitor --compact --interval 3  # Minimal display with frequent updates

# Cost tracking and pricing
pccu monitor --show-pricing  # Enable cost calculations and display
pccu monitor --show-sessions --show-pricing  # Session view with cost breakdown
pccu monitor --show-pricing --config pricing-config.yaml  # Cost monitoring with config

# Theme customization
pccu monitor --theme light  # Use light theme for this session
pccu monitor --theme dark --show-sessions  # Dark theme with session details
pccu monitor --theme ansi --show-sessions  # ANSI theme (respects terminal palette like Catppuccin)
pccu monitor --theme accessibility --show-pricing  # High contrast theme with pricing
pccu monitor --theme minimal --compact  # Minimal theme with compact display

# Model multiplier overrides
pccu monitor --model-multipliers opus=5.0,sonnet=1.0,default=1.0  # Override model multipliers
pccu monitor --model-multipliers opus=10.0,default=2.0  # Custom Opus multiplier with default fallback

Monitor Display Features

• Real-time updates: Live token consumption tracking
• Burn rate analytics: Tokens/minute with ETA to limit (e.g., "1.2K/m ETA: 2.3h (10:45 PM)")
• Cost tracking: Real-time cost calculations using LiteLLM pricing (when --show-pricing is enabled)
• Burn rate cost estimation: Intelligent cost projection for 5-hour blocks based on current spending rate (e.g., "531K/m Est: 159.3M (90%) Est: $65.51 ETA: 2h 28m")
• Block progress: Visual 5-hour billing block progress with time remaining
• Model breakdown: Per-model token usage (Opus, Sonnet) with optional cost breakdown
• Session details: Individual session tracking (shown by default)
• Activity tables: Project or session aggregation views with optional cost columns

List Usage Data

Generate usage reports:

# List all usage data (table format)
pccu list

# Output as JSON
pccu list --format json

# Output as CSV
pccu list --format csv

# Sort by different fields
pccu list --sort-by tokens
pccu list --sort-by session
pccu list --sort-by project
pccu list --sort-by time
pccu list --sort-by model

# Include cost information in output (table format)
pccu list --show-pricing

# Export usage data with costs as JSON
pccu list --show-pricing --format json

# Export usage data with costs as CSV
pccu list --show-pricing --format csv --output usage-with-costs.csv

# Combine sorting and pricing
pccu list --sort-by tokens --show-pricing --format table

# Save detailed report with costs to file
pccu list --show-pricing --output usage-report.json --format json

# Theme customization for list output
pccu list --theme light --show-pricing  # Light theme with pricing
pccu list --theme accessibility --format table  # High contrast theme
pccu list --theme minimal --sort-by tokens  # Minimal theme with token sorting

Usage Summary Analytics

Generate comprehensive usage summaries with statistical analysis:

# Monthly summary (default) with totals, averages, and P90 statistics
pccu usage-summary

# Weekly breakdown for the last 8 weeks
pccu usage-summary --time-bucket weekly --period-limit 8

# Daily analysis for the last 30 days
pccu usage-summary --time-bucket daily --period-limit 30

# All-time summary across entire usage history
pccu usage-summary --time-bucket all

# Export comprehensive monthly analysis to CSV
pccu usage-summary --format csv --output monthly-summary.csv

# Detailed summary with model and tool breakdowns
pccu usage-summary --show-models --show-tools

# Summary with all statistics (including P90) and model breakdown
pccu usage-summary --show-p90 --show-models --show-pricing

# Minimal summary without P90 statistics
pccu usage-summary --no-p90

# JSON export for data analysis
pccu usage-summary --format json --output usage-analysis.json

# Theme customization for summary output
pccu usage-summary --theme dark --show-models

What the Summary Shows:

• Totals: Total tokens, messages, and costs per time period
• Averages: Average usage per session within each period
• P90 Statistics: 90th percentile values showing typical high usage (filters outliers)
• Activity Metrics: Number of active projects and sessions per period
• Model Breakdown: Usage distribution across different Claude models (with --show-models)
• Tool Usage: Analysis of which tools are used most frequently (with --show-tools)
• Time Periods: Flexible bucketing by day, week (ISO weeks), month, or all-time

Understanding P90 vs Average: P90 values are typically higher than averages because they represent the 90th percentile - meaning 90% of your sessions used less than this amount, while 10% used more. This helps identify your typical "high usage" sessions while filtering out extreme outliers. The gap between average and P90 indicates usage variability.

Configuration Management

# Initialize configuration file
pccu init

# Set different types of limits
pccu set-limit token 500000      # Set token limit
pccu set-limit message 100       # Set message limit  
pccu set-limit cost 25.50        # Set cost limit in USD

# Update maximums based on current usage and enable read-only mode
pccu update-maximums

# Preview configuration changes without applying them
pccu update-maximums --dry-run

# Force update even if config is read-only
pccu update-maximums --force

# Use only current active block totals instead of historical maximums
pccu update-maximums --use-current-block

# Use custom config file
pccu init --config my-config.yaml
pccu update-maximums --config my-config.yaml

Cache Management

# Clear file monitoring cache
pccu clear-cache

# Clear cache with custom config
pccu clear-cache --config my-config.yaml

Theme Management

# List all available themes
pccu theme list

# Set default theme (saves to config)
pccu theme set light

# Set theme with custom config file
pccu theme set dark --config my-config.yaml

# Check current theme
pccu theme current

# Use temporary theme overrides (doesn't save to config)
pccu monitor --theme light  # Light theme for this session only
pccu list --theme accessibility  # High contrast theme for this command
pccu list-sessions --theme minimal  # Minimal theme for session list

Webhook Notifications

# Test webhook configuration (Discord and/or Slack)
pccu test-webhook

# Test with custom config file
pccu test-webhook --config my-config.yaml

JSONL Analysis

The jsonl_analyzer.py tool helps analyze Claude Code's JSONL data files, which can be quite large with complex nested structures. This tool is essential for understanding the data format when debugging token counting issues or exploring Claude's usage patterns.

This tool is integrated into the main pccu CLI but can also be run standalone:

# Via the main CLI (recommended)
pccu analyze ~/.claude/projects/-Users-username-project/session-id.jsonl

# Or run sta