| Name | par-cc-usage JSON |
| Version |
0.1.6
JSON |
| download |
| home_page | None |
| Summary | Claude Code usage tracking tool with real-time monitoring and analysis |
| upload_time | 2025-07-13 06:01:16 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | MIT License
Copyright (c) 2025 Paul Robello
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
anthropic
claude
claude-code
cli
monitoring
real-time
terminal
token-usage
usage-tracking
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# PAR CC Usage
Claude Code usage tracking tool with real-time monitoring and analysis.
[](https://pypi.org/project/par-cc-usage/)
[](https://pypi.org/project/par-cc-usage/)
[](https://buymeacoffee.com/probello3)
*Real-time monitoring interface showing token usage, burn rate analytics, tool usage tracking, and project activity*
## Table of Contents
- [Features](#features)
- [📊 Real-Time Monitoring](#-real-time-monitoring)
- [🔥 Advanced Burn Rate Analytics](#-advanced-burn-rate-analytics)
- [⚙️ Intelligent Block Management](#️-intelligent-block-management)
- [🎯 Smart Features](#-smart-features)
- [💰 Cost Tracking & Pricing](#-cost-tracking--pricing)
- [📁 File System Support](#-file-system-support)
- [🌐 Configuration & Customization](#-configuration--customization)
- [🎨 Theme System](#-theme-system)
- [🔔 Notification System](#-notification-system)
- [🛠️ Developer Tools](#️-developer-tools)
- [Installation](#installation)
- [Usage](#usage)
- [Monitor Token Usage](#monitor-token-usage)
- [List Usage Data](#list-usage-data)
- [Configuration Management](#configuration-management)
- [Cache Management](#cache-management)
- [Webhook Notifications](#webhook-notifications)
- [JSONL Analysis](#jsonl-analysis)
- [Debug Commands](#debug-commands)
- [Configuration](#configuration)
- [Directory Structure](#directory-structure)
- [Legacy Migration](#legacy-migration)
- [Config File Example](#config-file-example)
- [Environment Variables](#environment-variables)
- [Display Features](#display-features)
- [Unified Block System](#unified-block-system)
- [Current Billing Block Identification](#current-billing-block-identification)
- [Manual Override](#manual-override)
- [Compact Interface](#compact-interface)
- [Optional Session Details](#optional-session-details)
- [Project Aggregation Mode](#project-aggregation-mode-default)
- [Smart Token Limit Management](#smart-token-limit-management)
- [Model Display Names and Token Multipliers](#model-display-names-and-token-multipliers)
- [Time Format Options](#time-format-options)
- [Project Name Customization](#project-name-customization)
- [Cost Tracking & Pricing](#cost-tracking--pricing-1)
- [Webhook Notifications](#webhook-notifications-1)
- [File Locations](#file-locations)
- [XDG Base Directory Specification](#xdg-base-directory-specification)
- [Configuration Files](#configuration-files)
- [Legacy File Migration](#legacy-file-migration)
- [Environment Variable Override](#environment-variable-override)
- [Coming Soon](#coming-soon)
- [What's New](#whats-new)
- [v0.1.6 - Intelligent Cost Hierarchy](#v016---intelligent-cost-hierarchy)
- [v0.1.5 - Debug Flag Enhancement](#v015---debug-flag-enhancement)
- [v0.1.4 - Theme System Implementation](#v014---theme-system-implementation)
- [v0.1.3 - Code Quality Improvements](#v013---code-quality-improvements)
- [v0.1.2 - Pricing & Cost Tracking](#v012---pricing--cost-tracking)
- [older...](#older)
- [Development](#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
### 🔥 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
### 🎯 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
### 🌐 Configuration & Customization
- **XDG directory compliance**: Config, cache, and data files stored in standard locations
- **Automatic migration**: Legacy config files automatically moved to XDG locations
- **Timezone support**: Full timezone handling with configurable display formats
- **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 5 carefully crafted themes for different preferences
- **Light and dark themes**: Options for both dark terminal and light terminal users
- **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
### 🛠️ 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](https://docs.astral.sh/uv/) (fastest):
```bash
uv tool install par-cc-usage
```
Using pip:
```bash
pip install par-cc-usage
```
After installation, you can run the tool directly:
```bash
pccu monitor
```
### Option 2: Development Installation
Clone the repository and install in development mode:
```bash
# 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:
```bash
# 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.12 or higher
- Claude Code must be installed and have generated usage data
- [uv](https://docs.astral.sh/uv/) (recommended) or pip for installation
## Usage
### Monitor Token Usage
Monitor token usage in real-time with comprehensive options:
```bash
# Basic monitoring (default 5-second interval)
pccu monitor
# Compact mode for minimal display
pccu monitor --compact
# Enhanced monitoring with session details
pccu monitor --show-sessions
# 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
# 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 accessibility --show-pricing # High contrast theme with pricing
pccu monitor --theme minimal --compact # Minimal theme with compact display
```
#### 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 when `--show-sessions` is used
- **Activity tables**: Project or session aggregation views with optional cost columns
### List Usage Data
Generate usage reports:
```bash
# 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
```
### Configuration Management
```bash
# Initialize configuration file
pccu init
# Set token limit
pccu set-limit 500000
# Use custom config file
pccu init --config my-config.yaml
```
### Cache Management
```bash
# Clear file monitoring cache
pccu clear-cache
# Clear cache with custom config
pccu clear-cache --config my-config.yaml
```
### Theme Management
```bash
# 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
```bash
# 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:
```bash
# Via the main CLI (recommended)
pccu analyze ~/.claude/projects/-Users-username-project/session-id.jsonl
# Or run standalone
uv run python -m par_cc_usage.jsonl_analyzer ~/.claude/projects/-Users-username-project/session-id.jsonl
# Analyze first N lines (useful for large files)
pccu analyze path/to/file.jsonl --max-lines 10
# Customize string truncation length for better readability
pccu analyze path/to/file.jsonl --max-length 50
# Output as JSON for programmatic processing
pccu analyze path/to/file.jsonl --json
# Example: Analyze current project's most recent session
pccu analyze ~/.claude/projects/-Users-probello-Repos-par-cc-usage/*.jsonl --max-lines 20
```
#### JSONL Analyzer Features:
- **Field discovery**: Automatically identifies all fields present in the JSONL data
- **Type information**: Shows data types for each field (string, number, object, array)
- **Smart truncation**: Long strings and arrays are truncated for readability
- **Streaming processing**: Handles large files efficiently without loading everything into memory
- **Usage analysis**: Helps identify token usage patterns and message structures
### Debug Commands
Comprehensive troubleshooting tools for billing block calculations and session timing:
```bash
# Block Analysis
pccu debug-blocks # Show all active billing blocks
pccu debug-blocks --show-inactive # Include completed/inactive blocks
# Unified Block Calculation
pccu debug-unified # Step-by-step unified block selection trace
pccu debug-unified -e 18 # Validate against expected hour (24-hour format)
pccu debug-unified --expected-hour 14 # Alternative syntax for validation
# Activity Pattern Analysis
pccu debug-activity # Recent activity patterns (last 6 hours)
pccu debug-activity --hours 12 # Extended activity analysis (12 hours)
pccu debug-activity -e 18 --hours 8 # Validate expected start time with custom window
# Advanced Debugging Scenarios
pccu debug-blocks --show-inactive | grep "2025-07-08" # Filter by specific date
pccu debug-unified --config debug.yaml -e 13 # Use debug configuration with validation
```
#### Debug Output Features
- **Block timing verification**: Confirms correct 5-hour block boundaries
- **Strategy explanation**: Shows why specific blocks were selected
- **Token calculation validation**: Verifies deduplication and aggregation
- **Activity timeline**: Chronological view of session activity
- **Configuration validation**: Confirms settings are applied correctly
- **Expected time validation**: Validates unified block calculations against expected results (24-hour format)
## Configuration
The tool supports configuration via YAML files and environment variables. Configuration files are stored in XDG Base Directory compliant locations:
### Directory Structure
- **Config**: `~/.config/par_cc_usage/config.yaml` (respects `XDG_CONFIG_HOME`)
- **Cache**: `~/.cache/par_cc_usage/` (respects `XDG_CACHE_HOME`)
- **Data**: `~/.local/share/par_cc_usage/` (respects `XDG_DATA_HOME`)
### Legacy Migration
If you have an existing `./config.yaml` file in your working directory, it will be automatically migrated to the XDG config location (`~/.config/par_cc_usage/config.yaml`) when you first run the tool.
**Migration behavior:**
- Checks for legacy config files in current directory and home directory
- Automatically copies to XDG location if XDG config doesn't exist
- Preserves all existing settings during migration
- No manual intervention required
### Config File Example
The configuration file is located at `~/.config/par_cc_usage/config.yaml`:
```yaml
projects_dir: ~/.claude/projects
polling_interval: 5
timezone: America/Los_Angeles
token_limit: 500000
cache_dir: ~/.cache/par_cc_usage # XDG cache directory (automatically set)
disable_cache: false # Set to true to disable file monitoring cache
recent_activity_window_hours: 5 # Hours to consider as 'recent' activity for smart strategy (matches billing cycle)
display:
show_progress_bars: true
show_active_sessions: false # Default: hidden for compact display
update_in_place: true
refresh_interval: 1
time_format: 24h # Time format: '12h' for 12-hour, '24h' for 24-hour
display_mode: normal # Display mode: 'normal' or 'compact'
show_pricing: false # Enable cost calculations and display (default: false)
theme: default # Theme: 'default', 'dark', 'light', 'accessibility', or 'minimal'
project_name_prefixes: # Strip prefixes from project names for cleaner display
- "-Users-"
- "-home-"
aggregate_by_project: true # Aggregate token usage by project instead of individual sessions (default)
notifications:
discord_webhook_url: https://discord.com/api/webhooks/your-webhook-url
slack_webhook_url: https://hooks.slack.com/services/your-webhook-url
notify_on_block_completion: true # Send notification when 5-hour block completes
cooldown_minutes: 5 # Minimum minutes between notifications
```
### Environment Variables
- `PAR_CC_USAGE_PROJECTS_DIR`: Override projects directory
- `PAR_CC_USAGE_POLLING_INTERVAL`: Set polling interval
- `PAR_CC_USAGE_TIMEZONE`: Set timezone
- `PAR_CC_USAGE_TOKEN_LIMIT`: Set token limit
- `PAR_CC_USAGE_CACHE_DIR`: Override cache directory (defaults to XDG cache directory)
- `PAR_CC_USAGE_DISABLE_CACHE`: Disable file monitoring cache ('true', '1', 'yes', 'on' for true)
- `PAR_CC_USAGE_RECENT_ACTIVITY_WINDOW_HOURS`: Hours to consider as 'recent' activity for smart strategy (default: 5)
- `PAR_CC_USAGE_SHOW_PROGRESS_BARS`: Show progress bars
- `PAR_CC_USAGE_SHOW_ACTIVE_SESSIONS`: Show active sessions
- `PAR_CC_USAGE_UPDATE_IN_PLACE`: Update display in place
- `PAR_CC_USAGE_REFRESH_INTERVAL`: Display refresh interval
- `PAR_CC_USAGE_TIME_FORMAT`: Time format ('12h' or '24h')
- `PAR_CC_USAGE_THEME`: Theme name ('default', 'dark', 'light', 'accessibility', or 'minimal')
- `PAR_CC_USAGE_PROJECT_NAME_PREFIXES`: Comma-separated list of prefixes to strip from project names
- `PAR_CC_USAGE_AGGREGATE_BY_PROJECT`: Aggregate token usage by project instead of sessions ('true', '1', 'yes', 'on' for true)
- `PAR_CC_USAGE_DISCORD_WEBHOOK_URL`: Discord webhook URL for notifications
- `PAR_CC_USAGE_SLACK_WEBHOOK_URL`: Slack webhook URL for notifications
- `PAR_CC_USAGE_NOTIFY_ON_BLOCK_COMPLETION`: Send block completion notifications ('true', '1', 'yes', 'on' for true)
- `PAR_CC_USAGE_COOLDOWN_MINUTES`: Minimum minutes between notifications
## Display Features
### Unified Block System
When multiple Claude Code sessions are active simultaneously, they all share a single 5-hour billing block. The system intelligently determines which block timing to display based on your work patterns.
**Important**: Token counts and session displays are filtered to show only sessions with activity that overlaps with the unified block time window. This ensures the displayed totals accurately reflect what will be billed for the current 5-hour period. Sessions are included if they have any activity within the billing window, regardless of when they started.
#### Current Billing Block Identification
The system uses a **simple approach** to identify the current billing block:
**Algorithm:**
1. **Identifies active blocks** across all projects and sessions
2. **Returns the most recent active block** chronologically
**Block Activity Criteria:**
A block is considered "active" if both conditions are met:
- **Recent activity**: Time since last activity < 5 hours
- **Within block window**: Current time < block's theoretical end time (start + 5 hours)
**Key Benefits:**
- **Simple and reliable**: No complex filtering or edge case logic
- **Simple logic**: Uses straightforward rules to identify the current billing block
- **Predictable behavior**: Always selects the most recent block that has recent activity
**Example Scenario:**
- Session A: Started at 2:00 PM, last activity at 3:18 PM ✓ (active - within 5 hours)
- Session B: Started at 3:00 PM, last activity at 5:12 PM ✓ (active - within 5 hours)
- **Result**: Current billing block starts at 3:00 PM (most recent active block)
#### Manual Override
For testing or debugging, you can override the unified block start time:
```bash
# Override unified block to start at 2:00 PM (14:00 in 24-hour format)
pccu monitor --block-start 14
# Override with timezone consideration (hour is interpreted in your configured timezone)
pccu monitor --block-start 18 --show-sessions
```
**Important**: The `--block-start` hour (0-23) is interpreted in your configured timezone and automatically converted to UTC for internal processing.
### Compact Interface
The monitor now supports compact mode for minimal, focused display:
**Normal Mode (Default)**: Full display with all information:
- **Header**: Active projects and sessions count
- **Block Progress**: 5-hour block progress with time remaining
- **Token Usage**: Per-model token counts with burn rate metrics and progress bars
- **Tool Usage**: Optional tool usage statistics (if enabled)
- **Sessions**: Optional session/project details (if enabled)
**Compact Mode**: Minimal display with essential information only:
- **Header**: Active projects and sessions count
- **Token Usage**: Per-model token counts with burn rate metrics (no progress bars or interruption stats)
- **Burn Rate**: Displays tokens consumed per minute (e.g., "1.2K/m")
- **Estimated Total**: Projects total usage for the full 5-hour block based on current burn rate
- **ETA**: Shows estimated time until token limit is reached with actual clock time (e.g., "2.3h (10:45 PM)" or "45m (08:30 AM)")
- **Total Usage**: Simple text display instead of progress bar
- **Hidden Elements**: No block progress bar, tool usage information, or session details (even with `--show-sessions`)
**Using Compact Mode**:
```bash
# Start directly in compact mode
pccu monitor --compact
# Compact mode with other options (sessions still hidden in compact mode)
pccu monitor --compact --show-sessions --interval 2
# Use config file for persistent compact mode
pccu monitor # Uses config setting: display.display_mode: compact
# Environment variable approach
PAR_CC_USAGE_DISPLAY_MODE=compact pccu monitor
```
**Configuration Options**:
- **CLI**: Use `--compact` flag to start in compact mode
- **Config**: Set `display.display_mode: compact` in config file
- **Environment**: Set `PAR_CC_USAGE_DISPLAY_MODE=compact`
### Optional Session Details
Use `--show-sessions` or set `show_active_sessions: true` in config to view:
- Individual session information
- Project and session IDs
- Model types (Opus, Sonnet)
- Token usage per session
- Sessions sorted by newest activity first
**Session Filtering**: The sessions table displays only sessions with activity that overlaps with the current 5-hour billing window. This ensures accurate billing representation - sessions are shown if they have any activity within the unified block time window, regardless of when they started.
### Project Aggregation Mode (Default)
Project aggregation is enabled by default, showing token usage aggregated by project instead of individual sessions:
- **Project View**: Shows token usage aggregated by project instead of individual sessions
- **Simplified Table**: Removes session ID column for cleaner display
- **Same Filtering**: Uses the same unified block time window filtering as session mode
- **Model Tracking**: Shows all models used across all sessions within each project
- **Activity Sorting**: Projects sorted by their most recent activity time
**To disable project aggregation and show individual sessions:**
```yaml
display:
aggregate_by_project: false # Show individual sessions instead of projects
```
**Environment Variable:**
```bash
export PAR_CC_USAGE_AGGREGATE_BY_PROJECT=false
```
### Smart Token Limit Management
- **Auto-adjustment**: When current usage exceeds the configured limit, the limit is automatically increased and saved to the config file
- **Visual indicators**: Progress bars turn red when exceeding the original limit
- **Real-time updates**: Limits update immediately during monitoring
### Token Usage Calculation
PAR CC Usage calculates token consumption using a comprehensive approach that accounts for all token types and applies cost-based multipliers:
#### Token Types Included
- **Input tokens**: User prompts and context
- **Output tokens**: AI responses and generated content
- **Cache creation tokens**: Tokens used to create context caches
- **Cache read tokens**: Tokens read from existing context caches
**Total Calculation**: All token types are summed together for accurate billing representation.
#### Model-Based Token Multipliers
To reflect the actual cost differences between Claude models, tokens are adjusted using multipliers:
- **Opus models** (`claude-opus-*`): **5x multiplier** - reflects significantly higher cost
- **Sonnet models** (`claude-sonnet-*`): **1x multiplier** - baseline cost
- **Other/Unknown models**: **1x multiplier** - baseline cost
**Multiplier Application**: The multiplier is applied to the total token count (input + output + cache tokens) for each message, then aggregated by model within each billing block.
#### Block-Level Aggregation
- **Per-session blocks**: Each 5-hour session maintains separate token counts
- **Per-model tracking**: Token counts are tracked separately for each model within a block
- **Unified billing**: When multiple sessions are active, the system aggregates tokens from all sessions that overlap with the current billing period
#### Deduplication
- **Message + Request ID**: Prevents double-counting when JSONL files are re-processed
- **Processed hash tracking**: Maintains a cache of seen message combinations
- **Cross-session deduplication**: Works across all active sessions and projects
#### Display Calculations
- **Unified Block Total**: Shows tokens from all sessions overlapping the current 5-hour billing window
- **Per-Model Breakdown**: Displays individual model contributions with multipliers applied
- **Burn Rate**: Calculated as tokens per minute based on activity within the current block
- **Projections**: Estimates total block usage based on current burn rate
### Model Display Names
Model identifiers are simplified for better readability:
- `claude-opus-*` → **Opus**
- `claude-sonnet-*` → **Sonnet**
- Unknown/other models → **Unknown**
**Note**: Claude Code primarily uses Opus and Sonnet models. Any other model names (including Haiku) are normalized to "Unknown".
### Time Format Options
Configure time display format through `display.time_format` setting:
- **24h format** (default): Shows time as `14:30` and `2024-07-08 14:30:45 PDT`
- **12h format**: Shows time as `2:30 PM` and `2024-07-08 2:30:45 PM PDT`
The time format applies to:
- Real-time monitor display (header and block progress)
- List command output (time ranges)
- Block time ranges in all display modes
### Project Name Customization
Configure project name display through `display.project_name_prefixes` setting:
- **Strip common prefixes**: Remove repetitive path prefixes from project names
- **Preserve project structure**: Maintains the actual project name including dashes
- **Configurable prefixes**: Customize which prefixes to strip
**Examples:**
- Claude directory: `-Users-probello-Repos-my-awesome-project`
- With prefix `"-Users-probello-Repos-"`: Shows as `my-awesome-project`
- Without prefix stripping: Shows as `-Users-probello-Repos-my-awesome-project`
**Configuration:**
```yaml
display:
project_name_prefixes:
- "-Users-probello-Repos-" # Strip your repos path
- "-home-user-" # Strip alternative home paths
```
**Environment Variable:**
```bash
export PAR_CC_USAGE_PROJECT_NAME_PREFIXES="-Users-probello-Repos-,-home-user-"
```
### Cost Tracking & Pricing
PAR CC Usage includes comprehensive cost tracking capabilities using LiteLLM's pricing data for accurate cost calculations across all supported Claude models.
#### Enabling Cost Display
**Via Command Line:**
```bash
# Enable pricing for monitor mode
pccu monitor --show-pricing
# Enable pricing for session view
pccu monitor --show-sessions --show-pricing
# Enable pricing for list output
pccu list --show-pricing
```
**Via Configuration File:**
```yaml
display:
show_pricing: true # Enable cost calculations and display
```
**Via Environment Variable:**
```bash
export PAR_CC_USAGE_SHOW_PRICING=true
```
#### Features
- **Real-time cost tracking**: Live cost calculations displayed alongside token usage
- **Per-model accuracy**: Precise cost calculations for each Claude model (Opus, Sonnet, Haiku)
- **Activity table integration**: Optional cost columns in both project and session aggregation views
- **Total cost display**: Overall cost shown in the main token usage summary
- **Burn rate cost estimation**: Intelligent 5-hour block cost projection based on current spending rate
- **LiteLLM integration**: Uses LiteLLM's comprehensive pricing database for accuracy
- **Efficient caching**: Built-in pricing cache for optimal performance
#### Cost Display Locations
When `show_pricing` is enabled, cost information appears in:
1. **Main Usage Summary**: Total cost displayed next to token counts (e.g., "84.1M $34.85")
2. **Burn Rate Line**: Estimated total cost for 5-hour block based on current spending rate (e.g., "531K/m Est: 159.3M (90%) Est: $65.51 ETA: 2h 28m")
3. **Activity Tables**:
- Project aggregation mode: Cost column showing project-level costs
- Session aggregation mode: Cost column showing session-level costs
4. **List Command Output**: Cost information in table, JSON, and CSV formats with cost source tracking
#### Pricing Data
PAR CC Usage uses LiteLLM's comprehensive pricing database for accurate, up-to-date model costs with intelligent fallback handling:
**Core Pricing Features:**
- **Intelligent cost hierarchy**: Three-tier cost calculation system for maximum accuracy
1. **Native cost data (Priority 1)**: Uses cost data from Claude JSONL files when available
2. **LiteLLM calculation (Priority 2)**: Falls back to real-time pricing calculations
3. **Cost source transparency**: All outputs include cost calculation source for debugging
- **Real-time pricing data**: Uses LiteLLM's pricing database for current model costs
- **Comprehensive model support**: Covers all Claude model variants with accurate per-token pricing
- **Token type handling**: Proper pricing for input, output, cache creation, and cache read tokens
- **Automatic model mapping**: Maps Claude Code model names to LiteLLM pricing keys
- **Future-proof design**: Automatically uses native Claude cost data when available
**Intelligent Fallback System:**
- **Unknown model handling**: Models marked as "Unknown" automatically display $0.00 cost
- **Pattern-based fallbacks**: When exact model names aren't found, uses intelligent pattern matching:
- Models containing "opus" → Falls back to Claude Opus pricing
- Models containing "sonnet" → Falls back to Claude Sonnet pricing
- Models containing "haiku" → Falls back to Claude Haiku pricing
- **Fuzzy matching**: Partial name matching for model variants and prefixes
- **Generic Claude fallbacks**: Unrecognized Claude models fall back to Sonnet pricing as a safe default
- **Graceful error handling**: Missing pricing data doesn't break functionality
**Cost Calculation Hierarchy:**
PAR CC Usage implements an intelligent three-tier cost calculation system for maximum accuracy:
```bash
# Example list output showing cost source transparency
pccu list --show-pricing --format json
[
{
"project": "my-app",
"session": "abc123...",
"model": "opus",
"tokens": 150000,
"active": true,
"cost": 12.50,
"cost_source": "block_native" # Native cost from Claude
},
{
"project": "my-app",
"session": "def456...",
"model": "sonnet",
"tokens": 75000,
"active": true,
"cost": 3.25,
"cost_source": "litellm_calculated" # Calculated with LiteLLM
}
]
```
**Cost Source Types:**
- `"block_native"`: Cost from TokenBlock native data (highest priority)
- `"usage_native"`: Cost from TokenUsage native data (medium priority)
- `"litellm_calculated"`: Cost calculated using LiteLLM pricing (fallback)
**Cost Validation:**
- Native cost data is validated for reasonableness ($0.01-$1000.00)
- Invalid native costs automatically fall back to LiteLLM calculation
- Suspiciously high costs (>$1000) are logged and ignored
**Examples of Fallback Behavior:**
- `"Unknown"` → $0.00 cost (no charges applied)
- `"claude-opus-custom"` → Uses Claude Opus pricing via pattern matching
- `"anthropic/claude-sonnet-experimental"` → Uses Claude Sonnet pricing via fuzzy matching
- `"custom-claude-model"` → Uses Claude Sonnet pricing as generic fallback
### Webhook Notifications
PAR CC Usage can send webhook notifications to Discord and/or Slack when 5-hour billing blocks complete, helping you stay aware of your usage patterns and costs.
#### Discord Setup
1. **Create Discord Webhook**:
- Go to your Discord server settings
- Navigate to Integrations > Webhooks
- Create a new webhook and copy the URL
2. **Configure Discord Webhook**:
```yaml
notifications:
discord_webhook_url: https://discord.com/api/webhooks/your-webhook-url
notify_on_block_completion: true
cooldown_minutes: 5
```
Or via environment variable:
```bash
export PAR_CC_USAGE_DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/your-webhook-url"
```
#### Slack Setup
1. **Create Slack Webhook**:
- Go to your Slack workspace settings
- Navigate to Apps > Incoming Webhooks
- Create a new webhook and copy the URL
2. **Configure Slack Webhook**:
```yaml
notifications:
slack_webhook_url: https://hooks.slack.com/services/your-webhook-url
notify_on_block_completion: true
cooldown_minutes: 5
```
Or via environment variable:
```bash
export PAR_CC_USAGE_SLACK_WEBHOOK_URL="https://hooks.slack.com/services/your-webhook-url"
```
#### Multiple Webhooks
You can configure both Discord and Slack webhooks simultaneously:
```yaml
notifications:
discord_webhook_url: https://discord.com/api/webhooks/your-discord-webhook
slack_webhook_url: https://hooks.slack.com/services/your-slack-webhook
notify_on_block_completion: true
cooldown_minutes: 5
```
#### Test Configuration
```bash
# Test all configured webhooks
pccu test-webhook
```
#### Notification Features
- **Block Completion Alerts**: Notifications sent when a 5-hour block completes
- **Activity Filtering**: Only sends notifications for blocks that had activity (token usage > 0)
- **One-Time Sending**: Each block completion notification is sent only once
- **Cooldown Protection**: Configurable minimum time between notifications (default: 5 minutes)
- **Rich Information**: Includes token usage, duration, limit status, and time ranges
- **Smart Coloring**: Visual indicators based on token limit usage (green/orange/red)
#### Notification Content
Each notification includes:
- **Block Duration**: How long the block lasted
- **Token Usage**: Active and total token counts
- **Limit Status**: Percentage of configured limit used
- **Time Range**: Start and end times in your configured timezone
- **Visual Indicators**: Color-coded based on usage levels
#### Configuration Options
- `discord_webhook_url`: Discord webhook URL (optional - for Discord notifications)
- `slack_webhook_url`: Slack webhook URL (optional - for Slack notifications)
- `notify_on_block_completion`: Enable/disable block completion notifications (default: true)
- `cooldown_minutes`: Minimum minutes between notifications (default: 5)
### Theme System
PAR CC Usage includes a comprehensive theme system that allows you to customize the visual appearance of the CLI interface to match your preferences, terminal setup, and accessibility needs.
#### Available Themes
**Default Theme**: Original bright color scheme with vibrant colors
- **Use case**: General usage with high contrast
- **Colors**: Bright colors (cyan, yellow, green, red, magenta)
- **Best for**: Dark terminals, users who prefer bright colors
**Dark Theme**: Optimized for dark terminal backgrounds
- **Use case**: Dark mode terminals with refined colors
- **Colors**: Softer bright colors with better dark background contrast
- **Best for**: Dark terminals, reduced eye strain
**Light Theme**: Solarized Light inspired color palette
- **Use case**: Light terminal backgrounds
- **Colors**: Solarized Light palette (darker text, warm backgrounds)
- **Best for**: Light terminals, bright environments
**Accessibility Theme**: High contrast theme meeting WCAG AAA standards
- **Use case**: Visual accessibility and screen readers
- **Colors**: High contrast colors (black text on white background)
- **Best for**: Accessibility needs, high contrast requirements
**Minimal Theme**: Grayscale theme with minimal color usage
- **Use case**: Distraction-free, professional environments
- **Colors**: Grayscale palette (white, grays, black)
- **Best for**: Minimal aesthetics, focus on content over colors
#### Theme Configuration
**Set Default Theme (saves to config file):**
```bash
# Set light theme as default
pccu theme set light
# Set accessibility theme as default
pccu theme set accessibility
# Set with custom config file
pccu theme set dark --config my-config.yaml
```
**Temporary Theme Override (session only):**
```bash
# Override theme for single command
pccu monitor --theme light
pccu list --theme accessibility
pccu list-sessions --theme minimal
# Theme persists for the entire command execution
pccu monitor --theme light --show-sessions --show-pricing
```
**Configuration File Setting:**
```yaml
display:
theme: light # Options: 'default', 'dark', 'light', 'accessibility', 'minimal'
```
**Environment Variable:**
```bash
export PAR_CC_USAGE_THEME=accessibility
```
#### Theme Management Commands
```bash
# List all available themes with descriptions
pccu theme list
# Get current theme setting
pccu theme current
# Set default theme (saves to config)
pccu theme set <theme-name>
```
#### Theme Features
- **Semantic Color System**: Uses meaningful color names (success, warning, error, info) for consistency
- **Rich Integration**: Full integration with Rich library for optimal terminal rendering
- **Responsive Design**: Themes work across all display modes (normal, compact, sessions)
- **Consistent Application**: Colors are applied uniformly across all UI elements
- **Configuration Flexibility**: Multiple ways to set themes (CLI, config file, environment)
#### Theme Scope
Themes apply to all visual elements:
- **Progress bars**: Token usage and block progress indicators
- **Tables**: Project and session data tables
- **Status indicators**: Active/inactive sessions, success/error states
- **Burn rate displays**: Token consumption metrics
- **Headers and borders**: UI structure elements
- **Cost information**: Pricing and cost calculation displays (when enabled)
#### Best Practices
- **Light terminals**: Use `light` or `accessibility` themes
- **Dark terminals**: Use `default` or `dark` themes
- **Accessibility needs**: Use `accessibility` theme for high contrast
- **Professional environments**: Use `minimal` theme for clean appearance
- **Testing themes**: Use `--theme` flag to test before setting as default
## File Locations
### XDG Base Directory Specification
PAR CC Usage follows the XDG Base Directory Specification for proper file organization:
| Directory | Default Location | Environment Variable | Purpose |
|-----------|------------------|---------------------|----------|
| Config | `~/.config/par_cc_usage/` | `XDG_CONFIG_HOME` | Configuration files |
| Cache | `~/.cache/par_cc_usage/` | `XDG_CACHE_HOME` | File monitoring cache |
| Data | `~/.local/share/par_cc_usage/` | `XDG_DATA_HOME` | Application data |
### Configuration Files
- **Main config**: `~/.config/par_cc_usage/config.yaml`
- **Cache file**: `~/.cache/par_cc_usage/file_states.json`
### Legacy File Migration
The tool automatically migrates configuration files from legacy locations:
- `./config.yaml` (current working directory)
- `~/.par_cc_usage/config.yaml` (home directory)
Migration happens automatically on first run if:
1. Legacy config file exists
2. XDG config file doesn't exist
3. File is copied to `~/.config/par_cc_usage/config.yaml`
### Environment Variable Override
You can override XDG directories using standard environment variables:
```bash
# Override config directory
export XDG_CONFIG_HOME="/custom/config/path"
# Override cache directory
export XDG_CACHE_HOME="/custom/cache/path"
# Override data directory
export XDG_DATA_HOME="/custom/data/path"
```
## Coming Soon
We're actively working on exciting new features to enhance your Claude Code monitoring experience:
### 💰 Cost Tracking for Non-Subscribers
- **Pay-per-use cost calculation**: Accurate cost estimates for users without Claude Pro subscriptions
- **Real-time cost monitoring**: Live cost tracking alongside token usage
- **Cost projections**: Estimated spending for the current billing block
- **Historical cost analysis**: Track spending patterns over time
- **Budget alerts**: Configurable notifications when approaching cost thresholds
**Want to contribute or request a feature?** Check out our [GitHub repository](https://github.com/paulrobello/par_cc_usage) or open an issue with your suggestions!
## What's New
### v0.1.6 - Intelligent Cost Hierarchy
**Advanced Cost Calculation System**: Implemented a sophisticated three-tier cost calculation hierarchy for the `pccu list` command, providing maximum accuracy and future-proofing for native Claude cost data:
#### 💰 Intelligent Cost Features
- **Three-Tier Cost Hierarchy**: Priority-based cost calculation system:
1. **Native Block Cost** (Priority 1): Uses `cost_usd` from TokenBlock when available
2. **Native Usage Cost** (Priority 2): Uses `cost_usd` from TokenUsage when block cost unavailable
3. **LiteLLM Calculation** (Priority 3): Falls back to real-time pricing calculations
- **Cost Source Transparency**: All exports include `cost_source` field showing calculation method:
- `"block_native"`: Cost from TokenBlock native data (future-ready)
- `"usage_native"`: Cost from TokenUsage native data (future-ready)
- `"litellm_calculated"`: Cost calculated using LiteLLM pricing (current default)
- **Cost Validation**: Native cost data validated for reasonableness ($0.01-$1000.00)
- **Future-Proof Design**: Automatically uses native Claude cost data when available
#### 📊 Enhanced List Command
- **Full Output Format Support**: Pricing works with table, JSON, and CSV formats
- **Async Cost Calculations**: Non-blocking cost calculations maintain performance
- **Cost Source Tracking**: Complete transparency in cost calculation methods
- **Export Integration**: JSON and CSV exports include cost and cost_source fields
#### 📈 Usage Examples
```bash
# Display usage with costs in table format
pccu list --show-pricing
# Export with cost source transparency
pccu list --show-pricing --format json
# CSV export with cost data
pccu list --show-pricing --format csv --output costs.csv
```
#### 🔧 Technical Improvements
- **566 Tests Passing**: Comprehensive test coverage including 12 new cost hierarchy tests
- **Cost Hierarchy Validation**: Full validation of native cost data before use
- **Performance Optimization**: Efficient async cost calculations with LiteLLM caching
- **Documentation Enhancement**: Added comprehensive architecture diagrams and cost flow charts
### v0.1.5 - Debug Flag Enhancement
**Improved Monitor Experience**: Successfully implemented a debug flag system that eliminates display jumping in monitor mode while providing optional diagnostic output:
#### 🐛 Debug Features
- **Clean Monitor Display**: Processing messages are now suppressed by default, preventing display jumping during active monitoring
- **Optional Debug Output**: Use `--debug` flag to enable detailed processing messages when troubleshooting
- **Smart Logging Configuration**: Automatic logging level adjustment based on debug flag state
- **Comprehensive Test Coverage**: 554+ tests including specific debug functionality validation
#### 📝 Usage Examples
- **Clean monitoring**: `pccu monitor` (no processing messages, stable display)
- **Debug monitoring**: `pccu monitor --debug` (shows processing messages for troubleshooting)
- **Debug with other options**: `pccu monitor --debug --show-sessions --show-pricing`
#### 🔧 Technical Improvements
- **Logger Integration**: Converted console output to proper logging infrastructure
- **MonitorOptions Enhancement**: Added debug field to options dataclass with full type safety
- **Documentation Updates**: Updated both CLAUDE.md and README.md with debug flag usage examples
### v0.1.4 - Theme System Implementation
**Complete Theme System**: Successfully implemented a comprehensive theme system with full Rich library integration and accessibility support:
#### 🎨 Theme Features
- **5 Built-in Themes**: Default, Dark, Light, Accessibility, and Minimal themes
- **Solarized Light Integration**: Professional light theme based on Solarized Light color palette
- **WCAG AAA Compliance**: High contrast accessibility theme meeting accessibility standards
- **Semantic Color System**: Color abstraction with meaningful names (success, warning, error, info)
- **Rich Library Integration**: Full integration with Rich console for optimal terminal rendering
#### 🔧 Configuration Options
- **Multiple Configuration Methods**: CLI flags, config file, environment variables
- **Session-based Overrides**: `--theme` flag for temporary theme changes without saving
- **Persistent Configuration**: Theme settings saved to XDG-compliant config files
- **Theme Management Commands**: Built-in CLI commands for theme listing, setting, and current status
#### 🌈 Theme Varieties
- **Default Theme**: Original bright colors for general dark terminal usage
- **Dark Theme**: Refined colors optimized for dark terminals with reduced eye strain
- **Light Theme**: Solarized Light inspired palette perfect for light terminals
- **Accessibility Theme**: High contrast black/white theme for visual accessibility needs
- **Minimal Theme**: Grayscale palette for distraction-free, professional environments
#### 🎯 Usage Examples
- **Monitor with themes**: `pccu monitor --theme light --show-sessions`
- **List with themes**: `pccu list --theme accessibility --show-pricing`
- **Theme management**: `pccu theme set dark`, `pccu theme list`, `pccu theme current`
- **Configuration**: `display.theme: light` in config file or `PAR_CC_USAGE_THEME=minimal`
### v0.1.3 - Code Quality Improvements
**Major Code Quality Overhaul**: Successfully completed a comprehensive code quality improvement initiative focused on reducing cyclomatic complexity and improving maintainability across all core modules:
#### 🔧 Complexity Reduction
- **9 functions refactored**: Reduced cyclomatic complexity from 11-36 down to ≤10 for all functions
- **40+ helper functions extracted**: Decomposed complex operations into focused, reusable components
- **Improved maintainability**: Each function now has a single, clear responsibility
#### 📊 Key Improvements
- **Display System**: Split complex table population and burn rate calculation functions
- **Session Management**: Decomposed session listing, filtering, and analysis operations
- **Debug Commands**: Extracted analysis and display logic into modular components
- **Cost Tracking**: Separated cost calculation from display formatting
#### 🎯 Benefits
- **Better Code Readability**: Functions are easier to understand and debug
- **Increased Testability**: Helper functions can be tested independently
- **Enhanced Reusability**: Common logic extracted into reusable components
- **Reduced Maintenance Burden**: Changes to specific functionality are now isolated
#### 📈 Quality Metrics
- **512+ test cases**: Comprehensive test coverage maintained
- **All functions ≤10 complexity**: Enforced by automated linting
- **Full type safety**: Complete type annotations with validation
- **Zero linting errors**: Clean, consistent code style
### v0.1.2 - Pricing & Cost Tracking
**Cost Tracking Integration**: Added comprehensive cost tracking and pricing functionality with LiteLLM integration for accurate cost calculations across all Claude models.
### v0.1.1 - Enhanced Analytics
**Advanced Analytics**: Enhanced burn rate calculations, block management improvements, and refined display system with better user experience.
### older...
Earlier versions focused on foundational architecture, file monitoring, and basic token tracking capabilities.
## Development
```bash
# Format and lint
make checkall
# Run development mode
make dev
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "par-cc-usage",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "Paul Robello <probello@gmail.com>",
"keywords": "anthropic, claude, claude-code, cli, monitoring, real-time, terminal, token-usage, usage-tracking",
"author": null,
"author_email": "Paul Robello <probello@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/58/5d/b774a53cc54ee68e2b687cc49514503058957c3f3b8ab084ff4da92ec198/par_cc_usage-0.1.6.tar.gz",
"platform": null,
"description": "# PAR CC Usage\n\nClaude Code usage tracking tool with real-time monitoring and analysis.\n\n[](https://pypi.org/project/par-cc-usage/)\n[](https://pypi.org/project/par-cc-usage/) \n\n\n\n\n\n[](https://buymeacoffee.com/probello3)\n\n\n*Real-time monitoring interface showing token usage, burn rate analytics, tool usage tracking, and project activity*\n\n## Table of Contents\n\n- [Features](#features)\n - [\ud83d\udcca Real-Time Monitoring](#-real-time-monitoring)\n - [\ud83d\udd25 Advanced Burn Rate Analytics](#-advanced-burn-rate-analytics)\n - [\u2699\ufe0f Intelligent Block Management](#\ufe0f-intelligent-block-management)\n - [\ud83c\udfaf Smart Features](#-smart-features)\n - [\ud83d\udcb0 Cost Tracking & Pricing](#-cost-tracking--pricing)\n - [\ud83d\udcc1 File System Support](#-file-system-support)\n - [\ud83c\udf10 Configuration & Customization](#-configuration--customization)\n - [\ud83c\udfa8 Theme System](#-theme-system)\n - [\ud83d\udd14 Notification System](#-notification-system)\n - [\ud83d\udee0\ufe0f Developer Tools](#\ufe0f-developer-tools)\n- [Installation](#installation)\n- [Usage](#usage)\n - [Monitor Token Usage](#monitor-token-usage)\n - [List Usage Data](#list-usage-data)\n - [Configuration Management](#configuration-management)\n - [Cache Management](#cache-management)\n - [Webhook Notifications](#webhook-notifications)\n - [JSONL Analysis](#jsonl-analysis)\n - [Debug Commands](#debug-commands)\n- [Configuration](#configuration)\n - [Directory Structure](#directory-structure)\n - [Legacy Migration](#legacy-migration)\n - [Config File Example](#config-file-example)\n - [Environment Variables](#environment-variables)\n- [Display Features](#display-features)\n - [Unified Block System](#unified-block-system)\n - [Current Billing Block Identification](#current-billing-block-identification)\n - [Manual Override](#manual-override)\n - [Compact Interface](#compact-interface)\n - [Optional Session Details](#optional-session-details)\n - [Project Aggregation Mode](#project-aggregation-mode-default)\n - [Smart Token Limit Management](#smart-token-limit-management)\n - [Model Display Names and Token Multipliers](#model-display-names-and-token-multipliers)\n - [Time Format Options](#time-format-options)\n - [Project Name Customization](#project-name-customization)\n - [Cost Tracking & Pricing](#cost-tracking--pricing-1)\n - [Webhook Notifications](#webhook-notifications-1)\n- [File Locations](#file-locations)\n - [XDG Base Directory Specification](#xdg-base-directory-specification)\n - [Configuration Files](#configuration-files)\n - [Legacy File Migration](#legacy-file-migration)\n - [Environment Variable Override](#environment-variable-override)\n- [Coming Soon](#coming-soon)\n- [What's New](#whats-new)\n - [v0.1.6 - Intelligent Cost Hierarchy](#v016---intelligent-cost-hierarchy)\n - [v0.1.5 - Debug Flag Enhancement](#v015---debug-flag-enhancement)\n - [v0.1.4 - Theme System Implementation](#v014---theme-system-implementation)\n - [v0.1.3 - Code Quality Improvements](#v013---code-quality-improvements)\n - [v0.1.2 - Pricing & Cost Tracking](#v012---pricing--cost-tracking)\n - [older...](#older)\n- [Development](#development)\n\n## Features\n\n### \ud83d\udcca Real-Time Monitoring\n- **Live token tracking**: Monitor usage across all Claude Code projects in real-time\n- **5-hour billing blocks**: Unified block system that accurately reflects Claude's billing structure\n- **Multi-session support**: When multiple sessions are active, they share billing blocks intelligently\n- **Visual progress indicators**: Real-time progress bars for current billing period\n\n### \ud83d\udd25 Advanced Burn Rate Analytics\n- **Per-minute tracking**: Granular burn rate display (tokens/minute) for precise monitoring\n- **Estimated completion**: Projects total usage for full 5-hour block based on current rate\n- **ETA with clock time**: Shows both duration and actual time when limit will be reached\n- **Smart color coding**: Visual indicators based on usage levels (green/orange/red)\n\n### \u2699\ufe0f Intelligent Block Management\n- **Smart strategy**: Intelligent algorithm that automatically selects optimal billing blocks\n- **Manual override**: CLI option to set custom block start times for testing or corrections\n- **Automatic detection**: Smart detection of session boundaries and billing periods\n- **Gap handling**: Proper handling of inactivity periods longer than 5 hours\n\n### \ud83c\udfaf Smart Features\n- **Auto-adjusting limits**: Automatically increases token limits when exceeded and saves to config\n- **Deduplication**: Prevents double-counting using message and request IDs\n- **Model name simplification**: Clean display names (Opus, Sonnet) for better readability\n- **Session sorting**: Newest-first ordering for active sessions\n- **Per-model token tracking**: Accurate token attribution with proper multipliers (Opus 5x, others 1x)\n- **Compact display mode**: Minimal interface option for reduced screen space usage\n\n### \ud83d\udcb0 Cost Tracking & Pricing\n- **Real-time cost calculations**: Live cost tracking using LiteLLM pricing data\n- **Per-model cost breakdown**: Accurate cost attribution for each Claude model\n- **Monitor pricing integration**: Optional cost columns in project and session views with `--show-pricing`\n- **List command pricing**: Full cost analysis support in table, JSON, and CSV outputs with `--show-pricing` and intelligent cost hierarchy\n- **Burn rate cost estimation**: Real-time 5-hour block cost projection based on current spending rate\n- **Configurable pricing display**: Enable/disable cost tracking via configuration or command-line\n- **Export with costs**: JSON and CSV exports include cost data and cost source transparency when pricing is enabled\n- **Integrated pricing cache**: Efficient pricing lookups with built-in caching\n- **Intelligent fallbacks**: When exact model names aren't found, uses pattern matching to find closest pricing\n- **Unknown model handling**: Models marked as \"Unknown\" automatically display $0.00 cost\n- **Robust error handling**: Missing pricing data doesn't break functionality or display\n\n### \ud83d\udcc1 File System Support\n- **Multi-directory monitoring**: Supports both legacy (`~/.claude/projects`) and new paths\n- **Efficient caching**: File position tracking to avoid re-processing entire files\n- **Cache management**: Optional cache disabling for full file reprocessing\n- **JSONL analysis**: Deep analysis of Claude Code data structures\n- **XDG Base Directory compliance**: Uses standard Unix/Linux directory conventions\n- **Legacy migration**: Automatically migrates existing config files to XDG locations\n\n### \ud83c\udf10 Configuration & Customization\n- **XDG directory compliance**: Config, cache, and data files stored in standard locations\n- **Automatic migration**: Legacy config files automatically moved to XDG locations\n- **Timezone support**: Full timezone handling with configurable display formats\n- **Time formats**: 12-hour or 24-hour time display options\n- **Project name cleanup**: Strip common path prefixes for cleaner display\n- **Flexible output**: Table, JSON, and CSV export formats\n\n### \ud83c\udfa8 Theme System\n- **Multiple built-in themes**: Choose from 5 carefully crafted themes for different preferences\n- **Light and dark themes**: Options for both dark terminal and light terminal users\n- **Accessibility support**: High contrast theme meeting WCAG AAA standards\n- **Session-based overrides**: Temporarily change themes for individual command runs\n- **Rich color integration**: Semantic color system with consistent visual language\n- **CLI theme management**: Built-in commands for theme configuration and preview\n\n### \ud83d\udd14 Notification System\n- **Discord integration**: Webhook notifications for billing block completion\n- **Smart filtering**: Only notifies for blocks with actual activity\n- **Cooldown protection**: Configurable minimum time between notifications\n- **Rich information**: Detailed usage statistics in notifications\n\n### \ud83d\udee0\ufe0f Developer Tools\n- **Debug commands**: Comprehensive debugging tools for block calculation and timing\n- **Activity analysis**: Historical activity pattern analysis\n- **JSONL analyzer**: Built-in `jsonl_analyzer.py` tool for examining Claude Code data files\n- **Webhook testing**: Built-in Discord and Slack webhook testing\n\n## Installation\n\n### Option 1: Install from PyPI (Recommended)\n\nUsing [uv](https://docs.astral.sh/uv/) (fastest):\n```bash\nuv tool install par-cc-usage\n```\n\nUsing pip:\n```bash\npip install par-cc-usage\n```\n\nAfter installation, you can run the tool directly:\n```bash\npccu monitor\n```\n\n### Option 2: Development Installation\n\nClone the repository and install in development mode:\n\n```bash\n# Clone the repository\ngit clone https://github.com/paulrobello/par_cc_usage.git\ncd par_cc_usage\n\n# Install with uv (recommended)\nuv sync\n\n# Or install with pip\npip install -e .\n```\n\nRun the tool in development mode:\n```bash\n# Using uv\nuv run pccu monitor\n\n# Or using make (if available)\nmake run\n\n# Or directly with Python\npython -m par_cc_usage.main monitor\n```\n\n### Prerequisites\n\n- Python 3.12 or higher\n- Claude Code must be installed and have generated usage data\n- [uv](https://docs.astral.sh/uv/) (recommended) or pip for installation\n\n## Usage\n\n### Monitor Token Usage\n\nMonitor token usage in real-time with comprehensive options:\n\n```bash\n# Basic monitoring (default 5-second interval)\npccu monitor\n\n# Compact mode for minimal display\npccu monitor --compact\n\n# Enhanced monitoring with session details\npccu monitor --show-sessions\n\n# High-frequency monitoring with custom settings\npccu monitor --interval 2 --token-limit 1000000 --show-sessions\n\n# Monitor with custom configuration\npccu monitor --config production-config.yaml\n\n# Testing and debugging scenarios\npccu monitor --no-cache --block-start 18 # Fresh scan + custom block timing\npccu monitor --block-start 14 --show-sessions # Override block start time\npccu monitor --debug # Enable debug output to see processing messages\n\n# Production monitoring examples\npccu monitor --interval 10 --token-limit 500000 # Conservative monitoring\npccu monitor --show-sessions --config team-config.yaml # Team dashboard\npccu monitor --compact --interval 3 # Minimal display with frequent updates\n\n# Cost tracking and pricing\npccu monitor --show-pricing # Enable cost calculations and display\npccu monitor --show-sessions --show-pricing # Session view with cost breakdown\npccu monitor --show-pricing --config pricing-config.yaml # Cost monitoring with config\n\n# Theme customization\npccu monitor --theme light # Use light theme for this session\npccu monitor --theme dark --show-sessions # Dark theme with session details\npccu monitor --theme accessibility --show-pricing # High contrast theme with pricing\npccu monitor --theme minimal --compact # Minimal theme with compact display\n```\n\n#### Monitor Display Features\n- **Real-time updates**: Live token consumption tracking\n- **Burn rate analytics**: Tokens/minute with ETA to limit (e.g., \"1.2K/m ETA: 2.3h (10:45 PM)\")\n- **Cost tracking**: Real-time cost calculations using LiteLLM pricing (when `--show-pricing` is enabled)\n- **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\")\n- **Block progress**: Visual 5-hour billing block progress with time remaining\n- **Model breakdown**: Per-model token usage (Opus, Sonnet) with optional cost breakdown\n- **Session details**: Individual session tracking when `--show-sessions` is used\n- **Activity tables**: Project or session aggregation views with optional cost columns\n\n### List Usage Data\n\nGenerate usage reports:\n\n```bash\n# List all usage data (table format)\npccu list\n\n# Output as JSON\npccu list --format json\n\n# Output as CSV\npccu list --format csv\n\n# Sort by different fields\npccu list --sort-by tokens\npccu list --sort-by session\npccu list --sort-by project\npccu list --sort-by time\npccu list --sort-by model\n\n# Include cost information in output (table format)\npccu list --show-pricing\n\n# Export usage data with costs as JSON\npccu list --show-pricing --format json\n\n# Export usage data with costs as CSV\npccu list --show-pricing --format csv --output usage-with-costs.csv\n\n# Combine sorting and pricing\npccu list --sort-by tokens --show-pricing --format table\n\n# Save detailed report with costs to file\npccu list --show-pricing --output usage-report.json --format json\n\n# Theme customization for list output\npccu list --theme light --show-pricing # Light theme with pricing\npccu list --theme accessibility --format table # High contrast theme\npccu list --theme minimal --sort-by tokens # Minimal theme with token sorting\n```\n\n### Configuration Management\n\n```bash\n# Initialize configuration file\npccu init\n\n# Set token limit\npccu set-limit 500000\n\n# Use custom config file\npccu init --config my-config.yaml\n```\n\n### Cache Management\n\n```bash\n# Clear file monitoring cache\npccu clear-cache\n\n# Clear cache with custom config\npccu clear-cache --config my-config.yaml\n```\n\n### Theme Management\n\n```bash\n# List all available themes\npccu theme list\n\n# Set default theme (saves to config)\npccu theme set light\n\n# Set theme with custom config file\npccu theme set dark --config my-config.yaml\n\n# Check current theme\npccu theme current\n\n# Use temporary theme overrides (doesn't save to config)\npccu monitor --theme light # Light theme for this session only\npccu list --theme accessibility # High contrast theme for this command\npccu list-sessions --theme minimal # Minimal theme for session list\n```\n\n### Webhook Notifications\n\n```bash\n# Test webhook configuration (Discord and/or Slack)\npccu test-webhook\n\n# Test with custom config file\npccu test-webhook --config my-config.yaml\n```\n\n### JSONL Analysis\n\nThe `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.\n\nThis tool is integrated into the main `pccu` CLI but can also be run standalone:\n\n```bash\n# Via the main CLI (recommended)\npccu analyze ~/.claude/projects/-Users-username-project/session-id.jsonl\n\n# Or run standalone\nuv run python -m par_cc_usage.jsonl_analyzer ~/.claude/projects/-Users-username-project/session-id.jsonl\n\n# Analyze first N lines (useful for large files)\npccu analyze path/to/file.jsonl --max-lines 10\n\n# Customize string truncation length for better readability\npccu analyze path/to/file.jsonl --max-length 50\n\n# Output as JSON for programmatic processing\npccu analyze path/to/file.jsonl --json\n\n# Example: Analyze current project's most recent session\npccu analyze ~/.claude/projects/-Users-probello-Repos-par-cc-usage/*.jsonl --max-lines 20\n```\n\n#### JSONL Analyzer Features:\n- **Field discovery**: Automatically identifies all fields present in the JSONL data\n- **Type information**: Shows data types for each field (string, number, object, array)\n- **Smart truncation**: Long strings and arrays are truncated for readability\n- **Streaming processing**: Handles large files efficiently without loading everything into memory\n- **Usage analysis**: Helps identify token usage patterns and message structures\n\n### Debug Commands\n\nComprehensive troubleshooting tools for billing block calculations and session timing:\n\n```bash\n# Block Analysis\npccu debug-blocks # Show all active billing blocks\npccu debug-blocks --show-inactive # Include completed/inactive blocks\n\n# Unified Block Calculation\npccu debug-unified # Step-by-step unified block selection trace\npccu debug-unified -e 18 # Validate against expected hour (24-hour format)\npccu debug-unified --expected-hour 14 # Alternative syntax for validation\n\n# Activity Pattern Analysis\npccu debug-activity # Recent activity patterns (last 6 hours)\npccu debug-activity --hours 12 # Extended activity analysis (12 hours)\npccu debug-activity -e 18 --hours 8 # Validate expected start time with custom window\n\n# Advanced Debugging Scenarios\npccu debug-blocks --show-inactive | grep \"2025-07-08\" # Filter by specific date\npccu debug-unified --config debug.yaml -e 13 # Use debug configuration with validation\n```\n\n#### Debug Output Features\n- **Block timing verification**: Confirms correct 5-hour block boundaries\n- **Strategy explanation**: Shows why specific blocks were selected\n- **Token calculation validation**: Verifies deduplication and aggregation\n- **Activity timeline**: Chronological view of session activity\n- **Configuration validation**: Confirms settings are applied correctly\n- **Expected time validation**: Validates unified block calculations against expected results (24-hour format)\n\n## Configuration\n\nThe tool supports configuration via YAML files and environment variables. Configuration files are stored in XDG Base Directory compliant locations:\n\n### Directory Structure\n\n- **Config**: `~/.config/par_cc_usage/config.yaml` (respects `XDG_CONFIG_HOME`)\n- **Cache**: `~/.cache/par_cc_usage/` (respects `XDG_CACHE_HOME`)\n- **Data**: `~/.local/share/par_cc_usage/` (respects `XDG_DATA_HOME`)\n\n### Legacy Migration\n\nIf you have an existing `./config.yaml` file in your working directory, it will be automatically migrated to the XDG config location (`~/.config/par_cc_usage/config.yaml`) when you first run the tool.\n\n**Migration behavior:**\n- Checks for legacy config files in current directory and home directory\n- Automatically copies to XDG location if XDG config doesn't exist\n- Preserves all existing settings during migration\n- No manual intervention required\n\n### Config File Example\n\nThe configuration file is located at `~/.config/par_cc_usage/config.yaml`:\n\n```yaml\nprojects_dir: ~/.claude/projects\npolling_interval: 5\ntimezone: America/Los_Angeles\ntoken_limit: 500000\ncache_dir: ~/.cache/par_cc_usage # XDG cache directory (automatically set)\ndisable_cache: false # Set to true to disable file monitoring cache\nrecent_activity_window_hours: 5 # Hours to consider as 'recent' activity for smart strategy (matches billing cycle)\ndisplay:\n show_progress_bars: true\n show_active_sessions: false # Default: hidden for compact display\n update_in_place: true\n refresh_interval: 1\n time_format: 24h # Time format: '12h' for 12-hour, '24h' for 24-hour\n display_mode: normal # Display mode: 'normal' or 'compact'\n show_pricing: false # Enable cost calculations and display (default: false)\n theme: default # Theme: 'default', 'dark', 'light', 'accessibility', or 'minimal'\n project_name_prefixes: # Strip prefixes from project names for cleaner display\n - \"-Users-\"\n - \"-home-\"\n aggregate_by_project: true # Aggregate token usage by project instead of individual sessions (default)\nnotifications:\n discord_webhook_url: https://discord.com/api/webhooks/your-webhook-url\n slack_webhook_url: https://hooks.slack.com/services/your-webhook-url\n notify_on_block_completion: true # Send notification when 5-hour block completes\n cooldown_minutes: 5 # Minimum minutes between notifications\n```\n\n### Environment Variables\n\n- `PAR_CC_USAGE_PROJECTS_DIR`: Override projects directory\n- `PAR_CC_USAGE_POLLING_INTERVAL`: Set polling interval\n- `PAR_CC_USAGE_TIMEZONE`: Set timezone\n- `PAR_CC_USAGE_TOKEN_LIMIT`: Set token limit\n- `PAR_CC_USAGE_CACHE_DIR`: Override cache directory (defaults to XDG cache directory)\n- `PAR_CC_USAGE_DISABLE_CACHE`: Disable file monitoring cache ('true', '1', 'yes', 'on' for true)\n- `PAR_CC_USAGE_RECENT_ACTIVITY_WINDOW_HOURS`: Hours to consider as 'recent' activity for smart strategy (default: 5)\n- `PAR_CC_USAGE_SHOW_PROGRESS_BARS`: Show progress bars\n- `PAR_CC_USAGE_SHOW_ACTIVE_SESSIONS`: Show active sessions\n- `PAR_CC_USAGE_UPDATE_IN_PLACE`: Update display in place\n- `PAR_CC_USAGE_REFRESH_INTERVAL`: Display refresh interval\n- `PAR_CC_USAGE_TIME_FORMAT`: Time format ('12h' or '24h')\n- `PAR_CC_USAGE_THEME`: Theme name ('default', 'dark', 'light', 'accessibility', or 'minimal')\n- `PAR_CC_USAGE_PROJECT_NAME_PREFIXES`: Comma-separated list of prefixes to strip from project names\n- `PAR_CC_USAGE_AGGREGATE_BY_PROJECT`: Aggregate token usage by project instead of sessions ('true', '1', 'yes', 'on' for true)\n- `PAR_CC_USAGE_DISCORD_WEBHOOK_URL`: Discord webhook URL for notifications\n- `PAR_CC_USAGE_SLACK_WEBHOOK_URL`: Slack webhook URL for notifications\n- `PAR_CC_USAGE_NOTIFY_ON_BLOCK_COMPLETION`: Send block completion notifications ('true', '1', 'yes', 'on' for true)\n- `PAR_CC_USAGE_COOLDOWN_MINUTES`: Minimum minutes between notifications\n\n## Display Features\n\n### Unified Block System\nWhen multiple Claude Code sessions are active simultaneously, they all share a single 5-hour billing block. The system intelligently determines which block timing to display based on your work patterns.\n\n**Important**: Token counts and session displays are filtered to show only sessions with activity that overlaps with the unified block time window. This ensures the displayed totals accurately reflect what will be billed for the current 5-hour period. Sessions are included if they have any activity within the billing window, regardless of when they started.\n\n#### Current Billing Block Identification\nThe system uses a **simple approach** to identify the current billing block:\n\n**Algorithm:**\n1. **Identifies active blocks** across all projects and sessions\n2. **Returns the most recent active block** chronologically\n\n**Block Activity Criteria:**\nA block is considered \"active\" if both conditions are met:\n- **Recent activity**: Time since last activity < 5 hours\n- **Within block window**: Current time < block's theoretical end time (start + 5 hours)\n\n**Key Benefits:**\n- **Simple and reliable**: No complex filtering or edge case logic\n- **Simple logic**: Uses straightforward rules to identify the current billing block\n- **Predictable behavior**: Always selects the most recent block that has recent activity\n\n**Example Scenario:**\n- Session A: Started at 2:00 PM, last activity at 3:18 PM \u2713 (active - within 5 hours)\n- Session B: Started at 3:00 PM, last activity at 5:12 PM \u2713 (active - within 5 hours) \n- **Result**: Current billing block starts at 3:00 PM (most recent active block)\n\n#### Manual Override\nFor testing or debugging, you can override the unified block start time:\n\n```bash\n# Override unified block to start at 2:00 PM (14:00 in 24-hour format)\npccu monitor --block-start 14\n\n# Override with timezone consideration (hour is interpreted in your configured timezone)\npccu monitor --block-start 18 --show-sessions\n```\n\n**Important**: The `--block-start` hour (0-23) is interpreted in your configured timezone and automatically converted to UTC for internal processing.\n\n### Compact Interface\nThe monitor now supports compact mode for minimal, focused display:\n\n**Normal Mode (Default)**: Full display with all information:\n- **Header**: Active projects and sessions count\n- **Block Progress**: 5-hour block progress with time remaining\n- **Token Usage**: Per-model token counts with burn rate metrics and progress bars\n- **Tool Usage**: Optional tool usage statistics (if enabled)\n- **Sessions**: Optional session/project details (if enabled)\n\n**Compact Mode**: Minimal display with essential information only:\n- **Header**: Active projects and sessions count\n- **Token Usage**: Per-model token counts with burn rate metrics (no progress bars or interruption stats)\n - **Burn Rate**: Displays tokens consumed per minute (e.g., \"1.2K/m\")\n - **Estimated Total**: Projects total usage for the full 5-hour block based on current burn rate\n - **ETA**: Shows estimated time until token limit is reached with actual clock time (e.g., \"2.3h (10:45 PM)\" or \"45m (08:30 AM)\")\n - **Total Usage**: Simple text display instead of progress bar\n- **Hidden Elements**: No block progress bar, tool usage information, or session details (even with `--show-sessions`)\n\n**Using Compact Mode**:\n\n```bash\n# Start directly in compact mode\npccu monitor --compact\n\n# Compact mode with other options (sessions still hidden in compact mode)\npccu monitor --compact --show-sessions --interval 2\n\n# Use config file for persistent compact mode\npccu monitor # Uses config setting: display.display_mode: compact\n\n# Environment variable approach\nPAR_CC_USAGE_DISPLAY_MODE=compact pccu monitor\n```\n\n**Configuration Options**:\n- **CLI**: Use `--compact` flag to start in compact mode\n- **Config**: Set `display.display_mode: compact` in config file\n- **Environment**: Set `PAR_CC_USAGE_DISPLAY_MODE=compact`\n\n### Optional Session Details\nUse `--show-sessions` or set `show_active_sessions: true` in config to view:\n- Individual session information\n- Project and session IDs\n- Model types (Opus, Sonnet)\n- Token usage per session\n- Sessions sorted by newest activity first\n\n**Session Filtering**: The sessions table displays only sessions with activity that overlaps with the current 5-hour billing window. This ensures accurate billing representation - sessions are shown if they have any activity within the unified block time window, regardless of when they started.\n\n### Project Aggregation Mode (Default)\nProject aggregation is enabled by default, showing token usage aggregated by project instead of individual sessions:\n- **Project View**: Shows token usage aggregated by project instead of individual sessions\n- **Simplified Table**: Removes session ID column for cleaner display\n- **Same Filtering**: Uses the same unified block time window filtering as session mode\n- **Model Tracking**: Shows all models used across all sessions within each project\n- **Activity Sorting**: Projects sorted by their most recent activity time\n\n**To disable project aggregation and show individual sessions:**\n```yaml\ndisplay:\n aggregate_by_project: false # Show individual sessions instead of projects\n```\n\n**Environment Variable:**\n```bash\nexport PAR_CC_USAGE_AGGREGATE_BY_PROJECT=false\n```\n\n### Smart Token Limit Management\n- **Auto-adjustment**: When current usage exceeds the configured limit, the limit is automatically increased and saved to the config file\n- **Visual indicators**: Progress bars turn red when exceeding the original limit\n- **Real-time updates**: Limits update immediately during monitoring\n\n### Token Usage Calculation\n\nPAR CC Usage calculates token consumption using a comprehensive approach that accounts for all token types and applies cost-based multipliers:\n\n#### Token Types Included\n- **Input tokens**: User prompts and context\n- **Output tokens**: AI responses and generated content\n- **Cache creation tokens**: Tokens used to create context caches\n- **Cache read tokens**: Tokens read from existing context caches\n\n**Total Calculation**: All token types are summed together for accurate billing representation.\n\n#### Model-Based Token Multipliers\nTo reflect the actual cost differences between Claude models, tokens are adjusted using multipliers:\n\n- **Opus models** (`claude-opus-*`): **5x multiplier** - reflects significantly higher cost\n- **Sonnet models** (`claude-sonnet-*`): **1x multiplier** - baseline cost\n- **Other/Unknown models**: **1x multiplier** - baseline cost\n\n**Multiplier Application**: The multiplier is applied to the total token count (input + output + cache tokens) for each message, then aggregated by model within each billing block.\n\n#### Block-Level Aggregation\n- **Per-session blocks**: Each 5-hour session maintains separate token counts\n- **Per-model tracking**: Token counts are tracked separately for each model within a block\n- **Unified billing**: When multiple sessions are active, the system aggregates tokens from all sessions that overlap with the current billing period\n\n#### Deduplication\n- **Message + Request ID**: Prevents double-counting when JSONL files are re-processed\n- **Processed hash tracking**: Maintains a cache of seen message combinations\n- **Cross-session deduplication**: Works across all active sessions and projects\n\n#### Display Calculations\n- **Unified Block Total**: Shows tokens from all sessions overlapping the current 5-hour billing window\n- **Per-Model Breakdown**: Displays individual model contributions with multipliers applied\n- **Burn Rate**: Calculated as tokens per minute based on activity within the current block\n- **Projections**: Estimates total block usage based on current burn rate\n\n### Model Display Names\nModel identifiers are simplified for better readability:\n- `claude-opus-*` \u2192 **Opus**\n- `claude-sonnet-*` \u2192 **Sonnet** \n- Unknown/other models \u2192 **Unknown**\n\n**Note**: Claude Code primarily uses Opus and Sonnet models. Any other model names (including Haiku) are normalized to \"Unknown\".\n\n### Time Format Options\nConfigure time display format through `display.time_format` setting:\n- **24h format** (default): Shows time as `14:30` and `2024-07-08 14:30:45 PDT`\n- **12h format**: Shows time as `2:30 PM` and `2024-07-08 2:30:45 PM PDT`\n\nThe time format applies to:\n- Real-time monitor display (header and block progress)\n- List command output (time ranges)\n- Block time ranges in all display modes\n\n### Project Name Customization\nConfigure project name display through `display.project_name_prefixes` setting:\n- **Strip common prefixes**: Remove repetitive path prefixes from project names\n- **Preserve project structure**: Maintains the actual project name including dashes\n- **Configurable prefixes**: Customize which prefixes to strip\n\n**Examples:**\n- Claude directory: `-Users-probello-Repos-my-awesome-project`\n- With prefix `\"-Users-probello-Repos-\"`: Shows as `my-awesome-project`\n- Without prefix stripping: Shows as `-Users-probello-Repos-my-awesome-project`\n\n**Configuration:**\n```yaml\ndisplay:\n project_name_prefixes:\n - \"-Users-probello-Repos-\" # Strip your repos path\n - \"-home-user-\" # Strip alternative home paths\n```\n\n**Environment Variable:**\n```bash\nexport PAR_CC_USAGE_PROJECT_NAME_PREFIXES=\"-Users-probello-Repos-,-home-user-\"\n```\n\n### Cost Tracking & Pricing\n\nPAR CC Usage includes comprehensive cost tracking capabilities using LiteLLM's pricing data for accurate cost calculations across all supported Claude models.\n\n#### Enabling Cost Display\n\n**Via Command Line:**\n```bash\n# Enable pricing for monitor mode\npccu monitor --show-pricing\n\n# Enable pricing for session view\npccu monitor --show-sessions --show-pricing\n\n# Enable pricing for list output\npccu list --show-pricing\n```\n\n**Via Configuration File:**\n```yaml\ndisplay:\n show_pricing: true # Enable cost calculations and display\n```\n\n**Via Environment Variable:**\n```bash\nexport PAR_CC_USAGE_SHOW_PRICING=true\n```\n\n#### Features\n\n- **Real-time cost tracking**: Live cost calculations displayed alongside token usage\n- **Per-model accuracy**: Precise cost calculations for each Claude model (Opus, Sonnet, Haiku)\n- **Activity table integration**: Optional cost columns in both project and session aggregation views\n- **Total cost display**: Overall cost shown in the main token usage summary\n- **Burn rate cost estimation**: Intelligent 5-hour block cost projection based on current spending rate\n- **LiteLLM integration**: Uses LiteLLM's comprehensive pricing database for accuracy\n- **Efficient caching**: Built-in pricing cache for optimal performance\n\n#### Cost Display Locations\n\nWhen `show_pricing` is enabled, cost information appears in:\n\n1. **Main Usage Summary**: Total cost displayed next to token counts (e.g., \"84.1M $34.85\")\n2. **Burn Rate Line**: Estimated total cost for 5-hour block based on current spending rate (e.g., \"531K/m Est: 159.3M (90%) Est: $65.51 ETA: 2h 28m\")\n3. **Activity Tables**: \n - Project aggregation mode: Cost column showing project-level costs\n - Session aggregation mode: Cost column showing session-level costs\n4. **List Command Output**: Cost information in table, JSON, and CSV formats with cost source tracking\n\n#### Pricing Data\n\nPAR CC Usage uses LiteLLM's comprehensive pricing database for accurate, up-to-date model costs with intelligent fallback handling:\n\n**Core Pricing Features:**\n- **Intelligent cost hierarchy**: Three-tier cost calculation system for maximum accuracy\n 1. **Native cost data (Priority 1)**: Uses cost data from Claude JSONL files when available\n 2. **LiteLLM calculation (Priority 2)**: Falls back to real-time pricing calculations\n 3. **Cost source transparency**: All outputs include cost calculation source for debugging\n- **Real-time pricing data**: Uses LiteLLM's pricing database for current model costs\n- **Comprehensive model support**: Covers all Claude model variants with accurate per-token pricing\n- **Token type handling**: Proper pricing for input, output, cache creation, and cache read tokens\n- **Automatic model mapping**: Maps Claude Code model names to LiteLLM pricing keys\n- **Future-proof design**: Automatically uses native Claude cost data when available\n\n**Intelligent Fallback System:**\n- **Unknown model handling**: Models marked as \"Unknown\" automatically display $0.00 cost\n- **Pattern-based fallbacks**: When exact model names aren't found, uses intelligent pattern matching:\n - Models containing \"opus\" \u2192 Falls back to Claude Opus pricing\n - Models containing \"sonnet\" \u2192 Falls back to Claude Sonnet pricing \n - Models containing \"haiku\" \u2192 Falls back to Claude Haiku pricing\n- **Fuzzy matching**: Partial name matching for model variants and prefixes\n- **Generic Claude fallbacks**: Unrecognized Claude models fall back to Sonnet pricing as a safe default\n- **Graceful error handling**: Missing pricing data doesn't break functionality\n\n**Cost Calculation Hierarchy:**\n\nPAR CC Usage implements an intelligent three-tier cost calculation system for maximum accuracy:\n\n```bash\n# Example list output showing cost source transparency\npccu list --show-pricing --format json\n[\n {\n \"project\": \"my-app\",\n \"session\": \"abc123...\",\n \"model\": \"opus\",\n \"tokens\": 150000,\n \"active\": true,\n \"cost\": 12.50,\n \"cost_source\": \"block_native\" # Native cost from Claude\n },\n {\n \"project\": \"my-app\", \n \"session\": \"def456...\",\n \"model\": \"sonnet\",\n \"tokens\": 75000,\n \"active\": true,\n \"cost\": 3.25,\n \"cost_source\": \"litellm_calculated\" # Calculated with LiteLLM\n }\n]\n```\n\n**Cost Source Types:**\n- `\"block_native\"`: Cost from TokenBlock native data (highest priority)\n- `\"usage_native\"`: Cost from TokenUsage native data (medium priority) \n- `\"litellm_calculated\"`: Cost calculated using LiteLLM pricing (fallback)\n\n**Cost Validation:**\n- Native cost data is validated for reasonableness ($0.01-$1000.00)\n- Invalid native costs automatically fall back to LiteLLM calculation\n- Suspiciously high costs (>$1000) are logged and ignored\n\n**Examples of Fallback Behavior:**\n- `\"Unknown\"` \u2192 $0.00 cost (no charges applied)\n- `\"claude-opus-custom\"` \u2192 Uses Claude Opus pricing via pattern matching\n- `\"anthropic/claude-sonnet-experimental\"` \u2192 Uses Claude Sonnet pricing via fuzzy matching\n- `\"custom-claude-model\"` \u2192 Uses Claude Sonnet pricing as generic fallback\n\n### Webhook Notifications\n\nPAR CC Usage can send webhook notifications to Discord and/or Slack when 5-hour billing blocks complete, helping you stay aware of your usage patterns and costs.\n\n#### Discord Setup\n\n1. **Create Discord Webhook**: \n - Go to your Discord server settings\n - Navigate to Integrations > Webhooks\n - Create a new webhook and copy the URL\n\n2. **Configure Discord Webhook**:\n ```yaml\n notifications:\n discord_webhook_url: https://discord.com/api/webhooks/your-webhook-url\n notify_on_block_completion: true\n cooldown_minutes: 5\n ```\n\n Or via environment variable:\n ```bash\n export PAR_CC_USAGE_DISCORD_WEBHOOK_URL=\"https://discord.com/api/webhooks/your-webhook-url\"\n ```\n\n#### Slack Setup\n\n1. **Create Slack Webhook**:\n - Go to your Slack workspace settings\n - Navigate to Apps > Incoming Webhooks\n - Create a new webhook and copy the URL\n\n2. **Configure Slack Webhook**:\n ```yaml\n notifications:\n slack_webhook_url: https://hooks.slack.com/services/your-webhook-url\n notify_on_block_completion: true\n cooldown_minutes: 5\n ```\n\n Or via environment variable:\n ```bash\n export PAR_CC_USAGE_SLACK_WEBHOOK_URL=\"https://hooks.slack.com/services/your-webhook-url\"\n ```\n\n#### Multiple Webhooks\n\nYou can configure both Discord and Slack webhooks simultaneously:\n\n```yaml\nnotifications:\n discord_webhook_url: https://discord.com/api/webhooks/your-discord-webhook\n slack_webhook_url: https://hooks.slack.com/services/your-slack-webhook\n notify_on_block_completion: true\n cooldown_minutes: 5\n```\n\n#### Test Configuration\n\n```bash\n# Test all configured webhooks\npccu test-webhook\n```\n\n#### Notification Features\n\n- **Block Completion Alerts**: Notifications sent when a 5-hour block completes\n- **Activity Filtering**: Only sends notifications for blocks that had activity (token usage > 0)\n- **One-Time Sending**: Each block completion notification is sent only once\n- **Cooldown Protection**: Configurable minimum time between notifications (default: 5 minutes)\n- **Rich Information**: Includes token usage, duration, limit status, and time ranges\n- **Smart Coloring**: Visual indicators based on token limit usage (green/orange/red)\n\n#### Notification Content\n\nEach notification includes:\n- **Block Duration**: How long the block lasted\n- **Token Usage**: Active and total token counts\n- **Limit Status**: Percentage of configured limit used\n- **Time Range**: Start and end times in your configured timezone\n- **Visual Indicators**: Color-coded based on usage levels\n\n#### Configuration Options\n\n- `discord_webhook_url`: Discord webhook URL (optional - for Discord notifications)\n- `slack_webhook_url`: Slack webhook URL (optional - for Slack notifications)\n- `notify_on_block_completion`: Enable/disable block completion notifications (default: true)\n- `cooldown_minutes`: Minimum minutes between notifications (default: 5)\n\n### Theme System\n\nPAR CC Usage includes a comprehensive theme system that allows you to customize the visual appearance of the CLI interface to match your preferences, terminal setup, and accessibility needs.\n\n#### Available Themes\n\n**Default Theme**: Original bright color scheme with vibrant colors\n- **Use case**: General usage with high contrast\n- **Colors**: Bright colors (cyan, yellow, green, red, magenta)\n- **Best for**: Dark terminals, users who prefer bright colors\n\n**Dark Theme**: Optimized for dark terminal backgrounds\n- **Use case**: Dark mode terminals with refined colors\n- **Colors**: Softer bright colors with better dark background contrast\n- **Best for**: Dark terminals, reduced eye strain\n\n**Light Theme**: Solarized Light inspired color palette\n- **Use case**: Light terminal backgrounds\n- **Colors**: Solarized Light palette (darker text, warm backgrounds)\n- **Best for**: Light terminals, bright environments\n\n**Accessibility Theme**: High contrast theme meeting WCAG AAA standards\n- **Use case**: Visual accessibility and screen readers\n- **Colors**: High contrast colors (black text on white background)\n- **Best for**: Accessibility needs, high contrast requirements\n\n**Minimal Theme**: Grayscale theme with minimal color usage\n- **Use case**: Distraction-free, professional environments\n- **Colors**: Grayscale palette (white, grays, black)\n- **Best for**: Minimal aesthetics, focus on content over colors\n\n#### Theme Configuration\n\n**Set Default Theme (saves to config file):**\n```bash\n# Set light theme as default\npccu theme set light\n\n# Set accessibility theme as default\npccu theme set accessibility\n\n# Set with custom config file\npccu theme set dark --config my-config.yaml\n```\n\n**Temporary Theme Override (session only):**\n```bash\n# Override theme for single command\npccu monitor --theme light\npccu list --theme accessibility\npccu list-sessions --theme minimal\n\n# Theme persists for the entire command execution\npccu monitor --theme light --show-sessions --show-pricing\n```\n\n**Configuration File Setting:**\n```yaml\ndisplay:\n theme: light # Options: 'default', 'dark', 'light', 'accessibility', 'minimal'\n```\n\n**Environment Variable:**\n```bash\nexport PAR_CC_USAGE_THEME=accessibility\n```\n\n#### Theme Management Commands\n\n```bash\n# List all available themes with descriptions\npccu theme list\n\n# Get current theme setting\npccu theme current\n\n# Set default theme (saves to config)\npccu theme set <theme-name>\n```\n\n#### Theme Features\n\n- **Semantic Color System**: Uses meaningful color names (success, warning, error, info) for consistency\n- **Rich Integration**: Full integration with Rich library for optimal terminal rendering\n- **Responsive Design**: Themes work across all display modes (normal, compact, sessions)\n- **Consistent Application**: Colors are applied uniformly across all UI elements\n- **Configuration Flexibility**: Multiple ways to set themes (CLI, config file, environment)\n\n#### Theme Scope\n\nThemes apply to all visual elements:\n- **Progress bars**: Token usage and block progress indicators\n- **Tables**: Project and session data tables\n- **Status indicators**: Active/inactive sessions, success/error states\n- **Burn rate displays**: Token consumption metrics\n- **Headers and borders**: UI structure elements\n- **Cost information**: Pricing and cost calculation displays (when enabled)\n\n#### Best Practices\n\n- **Light terminals**: Use `light` or `accessibility` themes\n- **Dark terminals**: Use `default` or `dark` themes\n- **Accessibility needs**: Use `accessibility` theme for high contrast\n- **Professional environments**: Use `minimal` theme for clean appearance\n- **Testing themes**: Use `--theme` flag to test before setting as default\n\n## File Locations\n\n### XDG Base Directory Specification\n\nPAR CC Usage follows the XDG Base Directory Specification for proper file organization:\n\n| Directory | Default Location | Environment Variable | Purpose |\n|-----------|------------------|---------------------|----------|\n| Config | `~/.config/par_cc_usage/` | `XDG_CONFIG_HOME` | Configuration files |\n| Cache | `~/.cache/par_cc_usage/` | `XDG_CACHE_HOME` | File monitoring cache |\n| Data | `~/.local/share/par_cc_usage/` | `XDG_DATA_HOME` | Application data |\n\n### Configuration Files\n\n- **Main config**: `~/.config/par_cc_usage/config.yaml`\n- **Cache file**: `~/.cache/par_cc_usage/file_states.json`\n\n### Legacy File Migration\n\nThe tool automatically migrates configuration files from legacy locations:\n\n- `./config.yaml` (current working directory)\n- `~/.par_cc_usage/config.yaml` (home directory)\n\nMigration happens automatically on first run if:\n1. Legacy config file exists\n2. XDG config file doesn't exist\n3. File is copied to `~/.config/par_cc_usage/config.yaml`\n\n### Environment Variable Override\n\nYou can override XDG directories using standard environment variables:\n\n```bash\n# Override config directory\nexport XDG_CONFIG_HOME=\"/custom/config/path\"\n\n# Override cache directory \nexport XDG_CACHE_HOME=\"/custom/cache/path\"\n\n# Override data directory\nexport XDG_DATA_HOME=\"/custom/data/path\"\n```\n\n## Coming Soon\n\nWe're actively working on exciting new features to enhance your Claude Code monitoring experience:\n\n### \ud83d\udcb0 Cost Tracking for Non-Subscribers\n- **Pay-per-use cost calculation**: Accurate cost estimates for users without Claude Pro subscriptions\n- **Real-time cost monitoring**: Live cost tracking alongside token usage\n- **Cost projections**: Estimated spending for the current billing block\n- **Historical cost analysis**: Track spending patterns over time\n- **Budget alerts**: Configurable notifications when approaching cost thresholds\n\n**Want to contribute or request a feature?** Check out our [GitHub repository](https://github.com/paulrobello/par_cc_usage) or open an issue with your suggestions!\n\n## What's New\n\n### v0.1.6 - Intelligent Cost Hierarchy\n\n**Advanced Cost Calculation System**: Implemented a sophisticated three-tier cost calculation hierarchy for the `pccu list` command, providing maximum accuracy and future-proofing for native Claude cost data:\n\n#### \ud83d\udcb0 Intelligent Cost Features\n- **Three-Tier Cost Hierarchy**: Priority-based cost calculation system:\n 1. **Native Block Cost** (Priority 1): Uses `cost_usd` from TokenBlock when available\n 2. **Native Usage Cost** (Priority 2): Uses `cost_usd` from TokenUsage when block cost unavailable\n 3. **LiteLLM Calculation** (Priority 3): Falls back to real-time pricing calculations\n- **Cost Source Transparency**: All exports include `cost_source` field showing calculation method:\n - `\"block_native\"`: Cost from TokenBlock native data (future-ready)\n - `\"usage_native\"`: Cost from TokenUsage native data (future-ready)\n - `\"litellm_calculated\"`: Cost calculated using LiteLLM pricing (current default)\n- **Cost Validation**: Native cost data validated for reasonableness ($0.01-$1000.00)\n- **Future-Proof Design**: Automatically uses native Claude cost data when available\n\n#### \ud83d\udcca Enhanced List Command\n- **Full Output Format Support**: Pricing works with table, JSON, and CSV formats\n- **Async Cost Calculations**: Non-blocking cost calculations maintain performance\n- **Cost Source Tracking**: Complete transparency in cost calculation methods\n- **Export Integration**: JSON and CSV exports include cost and cost_source fields\n\n#### \ud83d\udcc8 Usage Examples\n```bash\n# Display usage with costs in table format\npccu list --show-pricing\n\n# Export with cost source transparency\npccu list --show-pricing --format json\n\n# CSV export with cost data\npccu list --show-pricing --format csv --output costs.csv\n```\n\n#### \ud83d\udd27 Technical Improvements\n- **566 Tests Passing**: Comprehensive test coverage including 12 new cost hierarchy tests\n- **Cost Hierarchy Validation**: Full validation of native cost data before use\n- **Performance Optimization**: Efficient async cost calculations with LiteLLM caching\n- **Documentation Enhancement**: Added comprehensive architecture diagrams and cost flow charts\n\n### v0.1.5 - Debug Flag Enhancement\n\n**Improved Monitor Experience**: Successfully implemented a debug flag system that eliminates display jumping in monitor mode while providing optional diagnostic output:\n\n#### \ud83d\udc1b Debug Features\n- **Clean Monitor Display**: Processing messages are now suppressed by default, preventing display jumping during active monitoring\n- **Optional Debug Output**: Use `--debug` flag to enable detailed processing messages when troubleshooting\n- **Smart Logging Configuration**: Automatic logging level adjustment based on debug flag state\n- **Comprehensive Test Coverage**: 554+ tests including specific debug functionality validation\n\n#### \ud83d\udcdd Usage Examples \n- **Clean monitoring**: `pccu monitor` (no processing messages, stable display)\n- **Debug monitoring**: `pccu monitor --debug` (shows processing messages for troubleshooting)\n- **Debug with other options**: `pccu monitor --debug --show-sessions --show-pricing`\n\n#### \ud83d\udd27 Technical Improvements\n- **Logger Integration**: Converted console output to proper logging infrastructure\n- **MonitorOptions Enhancement**: Added debug field to options dataclass with full type safety\n- **Documentation Updates**: Updated both CLAUDE.md and README.md with debug flag usage examples\n\n### v0.1.4 - Theme System Implementation\n\n**Complete Theme System**: Successfully implemented a comprehensive theme system with full Rich library integration and accessibility support:\n\n#### \ud83c\udfa8 Theme Features\n- **5 Built-in Themes**: Default, Dark, Light, Accessibility, and Minimal themes\n- **Solarized Light Integration**: Professional light theme based on Solarized Light color palette\n- **WCAG AAA Compliance**: High contrast accessibility theme meeting accessibility standards\n- **Semantic Color System**: Color abstraction with meaningful names (success, warning, error, info)\n- **Rich Library Integration**: Full integration with Rich console for optimal terminal rendering\n\n#### \ud83d\udd27 Configuration Options\n- **Multiple Configuration Methods**: CLI flags, config file, environment variables\n- **Session-based Overrides**: `--theme` flag for temporary theme changes without saving\n- **Persistent Configuration**: Theme settings saved to XDG-compliant config files\n- **Theme Management Commands**: Built-in CLI commands for theme listing, setting, and current status\n\n#### \ud83c\udf08 Theme Varieties\n- **Default Theme**: Original bright colors for general dark terminal usage\n- **Dark Theme**: Refined colors optimized for dark terminals with reduced eye strain\n- **Light Theme**: Solarized Light inspired palette perfect for light terminals\n- **Accessibility Theme**: High contrast black/white theme for visual accessibility needs\n- **Minimal Theme**: Grayscale palette for distraction-free, professional environments\n\n#### \ud83c\udfaf Usage Examples\n- **Monitor with themes**: `pccu monitor --theme light --show-sessions`\n- **List with themes**: `pccu list --theme accessibility --show-pricing`\n- **Theme management**: `pccu theme set dark`, `pccu theme list`, `pccu theme current`\n- **Configuration**: `display.theme: light` in config file or `PAR_CC_USAGE_THEME=minimal`\n\n### v0.1.3 - Code Quality Improvements\n\n**Major Code Quality Overhaul**: Successfully completed a comprehensive code quality improvement initiative focused on reducing cyclomatic complexity and improving maintainability across all core modules:\n\n#### \ud83d\udd27 Complexity Reduction\n- **9 functions refactored**: Reduced cyclomatic complexity from 11-36 down to \u226410 for all functions\n- **40+ helper functions extracted**: Decomposed complex operations into focused, reusable components\n- **Improved maintainability**: Each function now has a single, clear responsibility\n\n#### \ud83d\udcca Key Improvements\n- **Display System**: Split complex table population and burn rate calculation functions\n- **Session Management**: Decomposed session listing, filtering, and analysis operations\n- **Debug Commands**: Extracted analysis and display logic into modular components\n- **Cost Tracking**: Separated cost calculation from display formatting\n\n#### \ud83c\udfaf Benefits\n- **Better Code Readability**: Functions are easier to understand and debug\n- **Increased Testability**: Helper functions can be tested independently\n- **Enhanced Reusability**: Common logic extracted into reusable components\n- **Reduced Maintenance Burden**: Changes to specific functionality are now isolated\n\n#### \ud83d\udcc8 Quality Metrics\n- **512+ test cases**: Comprehensive test coverage maintained\n- **All functions \u226410 complexity**: Enforced by automated linting\n- **Full type safety**: Complete type annotations with validation\n- **Zero linting errors**: Clean, consistent code style\n\n### v0.1.2 - Pricing & Cost Tracking\n\n**Cost Tracking Integration**: Added comprehensive cost tracking and pricing functionality with LiteLLM integration for accurate cost calculations across all Claude models.\n\n### v0.1.1 - Enhanced Analytics\n\n**Advanced Analytics**: Enhanced burn rate calculations, block management improvements, and refined display system with better user experience.\n\n### older...\n\nEarlier versions focused on foundational architecture, file monitoring, and basic token tracking capabilities.\n\n## Development\n\n```bash\n# Format and lint\nmake checkall\n\n# Run development mode\nmake dev\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Paul Robello\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Claude Code usage tracking tool with real-time monitoring and analysis",
"version": "0.1.6",
"project_urls": {
"Documentation": "https://github.com/paulrobello/par_cc_usage/blob/main/README.md",
"Homepage": "https://github.com/paulrobello/par_cc_usage",
"Issues": "https://github.com/paulrobello/par_cc_usage/issues",
"Source": "https://github.com/paulrobello/par_cc_usage"
},
"split_keywords": [
"anthropic",
" claude",
" claude-code",
" cli",
" monitoring",
" real-time",
" terminal",
" token-usage",
" usage-tracking"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cfd7e65bcf90e518f95b8e6fe4943b7a793ba858c255a008cb9fa760693bbaa7",
"md5": "f97f77faf7abc852620fad1bc3f047e5",
"sha256": "4500873e5c8dd8f3afd39c74ff7c971cfa2312d553ea41ac55991f8bd2f370fe"
},
"downloads": -1,
"filename": "par_cc_usage-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f97f77faf7abc852620fad1bc3f047e5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 92311,
"upload_time": "2025-07-13T06:01:15",
"upload_time_iso_8601": "2025-07-13T06:01:15.251990Z",
"url": "https://files.pythonhosted.org/packages/cf/d7/e65bcf90e518f95b8e6fe4943b7a793ba858c255a008cb9fa760693bbaa7/par_cc_usage-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "585db774a53cc54ee68e2b687cc49514503058957c3f3b8ab084ff4da92ec198",
"md5": "9ee1f7e6d74ec262c77de3a75d9c4a43",
"sha256": "1ec877b1565dd561b1a105120eeee40094e54e181afd30106aae7eac03f8409e"
},
"downloads": -1,
"filename": "par_cc_usage-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "9ee1f7e6d74ec262c77de3a75d9c4a43",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 98629,
"upload_time": "2025-07-13T06:01:16",
"upload_time_iso_8601": "2025-07-13T06:01:16.860048Z",
"url": "https://files.pythonhosted.org/packages/58/5d/b774a53cc54ee68e2b687cc49514503058957c3f3b8ab084ff4da92ec198/par_cc_usage-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 06:01:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "paulrobello",
"github_project": "par_cc_usage",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "par-cc-usage"
}
