### Claudelytics Quick Command Examples

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Examples of how to use Claudelytics commands after setup for various tasks like checking today's cost, specific dates, and interactive sessions.

```bash
ctoday          # Today's cost
csum            # Total cost summary
cdate 20241201  # Specific date cost
cwt             # Today's full report
cint            # Interactive session browser
ctui            # Enhanced TUI interface
catui           # Advanced TUI with professional features
cwatch          # Real-time monitoring
cdaily          # Quick daily summary
```

--------------------------------

### Install Claudelytics using Quick Install Script

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Use the provided script to download and install Claudelytics. The script supports custom installation directories, specific version installs, and viewing help options.

```bash
curl -fsSL https://raw.githubusercontent.com/nwiizo/claudelytics/main/scripts/install.sh | bash
```

```bash
curl -fsSL https://raw.githubusercontent.com/nwiizo/claudelytics/main/scripts/install.sh | bash -s -- --dir ~/.local/bin
```

```bash
curl -fsSL https://raw.githubusercontent.com/nwiizo/claudelytics/main/scripts/install.sh | bash -s -- --version v0.4.3
```

```bash
curl -fsSL https://raw.githubusercontent.com/nwiizo/claudelytics/main/scripts/install.sh | bash -s -- --help
```

--------------------------------

### Basic Claudelytics Commands

Source: https://github.com/nwiizo/claudelytics/blob/main/INSTALL.md

Common commands to get started with claudelytics after installation, such as viewing daily usage, launching the TUI, and checking costs.

```bash
# View daily usage
claudelytics daily

# Launch interactive TUI
claudelytics tui

# View session analytics
claudelytics session

# Show today's cost
claudelytics cost --today
```

--------------------------------

### Build and Install Claudelytics from Source

Source: https://github.com/nwiizo/claudelytics/blob/main/INSTALL.md

Clones the repository, builds the project in release mode, and installs the binary using Cargo.

```bash
# Clone the repository
git clone https://github.com/nwiizo/claudelytics.git
cd claudelytics

# Build in release mode
cargo build --release

# Install to cargo's bin directory
cargo install --path .
```

--------------------------------

### Claudelytics Configuration File Example

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Shows an example of the Claudelytics configuration file in YAML format, specifying paths, output formats, and watch intervals.

```yaml
claude_path: /custom/path/to/.claude
default_output_format: Table  # or Json
default_command: Daily        # Daily, Session, or Interactive
watch_interval_seconds: 5
export_directory: ~/Reports
date_format: "%Y-%m-%d"
```

--------------------------------

### Install Rust Toolchain

Source: https://github.com/nwiizo/claudelytics/blob/main/INSTALL.md

Installs the Rust toolchain using the official installation script. Ensures Rust is available for building from source.

```bash
# Install Rust if you haven't already
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
```

--------------------------------

### Start Live Dashboard

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Initiates the live dashboard with default settings for real-time usage monitoring. The refresh interval can be customized.

```bash
claudelytics live
```

```bash
claudelytics live --refresh 10
```

```bash
claudelytics live --token-limit 1000000
```

```bash
claudelytics live --cost-limit 50
```

```bash
claudelytics live --refresh 10 --token-limit 1000000 --cost-limit 50
```

```bash
claudelytics blocks --live
```

--------------------------------

### Install Claudelytics from Crates.io

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Install the Claudelytics CLI tool directly from crates.io using Cargo. This is the recommended installation method.

```bash
cargo install claudelytics
```

--------------------------------

### Install Claudelytics using Homebrew

Source: https://github.com/nwiizo/claudelytics/blob/main/INSTALL.md

Recommended for macOS and Linux users. Adds the tap, installs the package, and verifies the installation.

```bash
# Add the claudelytics tap
brew tap nwiizo/claudelytics

# Install claudelytics
brew install claudelytics

# Verify installation
claudelytics --version
```

--------------------------------

### Install Claudelytics using Quick Install Script

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Installs Claudelytics using a curl script. The script can install the latest version to a default location, a specific version, or a custom directory.

```bash
# Latest version to /usr/local/bin (or ~/.local/bin for non-root)
curl -fsSL https://raw.githubusercontent.com/nwiizo/claudelytics/main/scripts/install.sh | bash

# Specific version
curl -fsSL https://raw.githubusercontent.com/nwiizo/claudelytics/main/scripts/install.sh | bash -s -- --version v0.4.3

# Custom directory
curl -fsSL https://raw.githubusercontent.com/nwiizo/claudelytics/main/scripts/install.sh | bash -s -- --dir ~/.local/bin
```

--------------------------------

### Quick Install Script for Claudelytics

Source: https://github.com/nwiizo/claudelytics/blob/main/INSTALL.md

Installs the latest version of claudelytics without Homebrew. Can specify a custom installation directory.

```bash
# Install latest version
curl -fsSL https://raw.githubusercontent.com/nwiizo/claudelytics/main/scripts/install.sh | bash
```

```bash
# Or with custom install directory
CLAUDELYTICS_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/nwiizo/claudelytics/main/scripts/install.sh | bash
```

--------------------------------

### Install Claudelytics via Homebrew

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Installs Claudelytics on macOS or Linux using Homebrew. First, tap the custom repository, then install the package. Verify the installation by checking the version.

```bash
brew tap nwiizo/claudelytics
brew install claudelytics
claudelytics --version
```

--------------------------------

### Claudelytics Watch Mode Example

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Demonstrates the output of 'claudelytics watch' for real-time monitoring of Claude usage, showing the monitoring status and last updated time.

```bash
$ claudelytics watch
🔍 Starting watch mode...
👀 Monitoring: /Users/user/.claude
Press Ctrl+C to stop

🕐 Last updated: 2024-12-01 14:30:15
────────────────────────────────────────────────────────────────────────────────
[Daily usage table updates in real-time]
────────────────────────────────────────────────────────────────────────────────
```

--------------------------------

### Install Claudelytics with Homebrew

Source: https://github.com/nwiizo/claudelytics/blob/main/homebrew-claudelytics/README.md

Installs the Claudelytics CLI tool using Homebrew after the tap has been added.

```bash
brew install claudelytics
```

--------------------------------

### Claudelytics Quick Start Commands

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Execute these commands for quick analysis and interaction with Claudelytics. Includes commands for daily cost, interactive session browsing, TUI interfaces, and real-time monitoring.

```bash
claudelytics cost --today
```

```bash
claudelytics interactive
```

```bash
claudelytics tui
```

```bash
claudelytics advanced-tui
```

```bash
claudelytics --today
```

```bash
claudelytics watch
```

```bash
claudelytics export -o reports
```

```bash
claudelytics conversation --list
```

```bash
claudelytics conversation --session abc123
```

--------------------------------

### Claudelytics Daily Report Example

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Demonstrates the output format of the default 'claudelytics daily' command, showing total cost, token usage, and recent activity.

```bash
$ claudelytics daily
📊 Claude Code Usage Analytics
🕐 Generated at 2024-12-01 14:30:15

────────────────────────────────────────────────────────────
│  💰 Total Cost: $4.90  │  📅 Days: 3  │  🎯 Total Tokens: 35,500
│  📥 Input: 10,000  │  📤 Output: 20,000  │  🔄 Cache: 5,500
────────────────────────────────────────────────────────────

🚀 Recent Activity
► 2024-12-01 │ 18,000 tokens │ $2.45
  2024-11-30 │ 10,500 tokens │ $1.50
  2024-11-29 │ 7,000 tokens │ $0.95

📋 Daily Usage Details
📅 2024-12-01
  💰 Cost: $2.45 │ 🎯 Tokens: 18,000 │ 📊 Ratio: 2.0:1
  📥 In: 5,000 │ 📤 Out: 10,000 │ 🔄 Cache: 3,000

📋 2024-11-30
  💰 Cost: $1.50 │ 🎯 Tokens: 10,500 │ 📊 Ratio: 2.0:1
  📥 In: 3,000 │ 📤 Out: 6,000 │ 🔄 Cache: 1,500
```

--------------------------------

### Claudelytics Cost Summary Example

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Shows the output for 'claudelytics cost --today', providing a summary of today's usage cost and token count.

```bash
$ claudelytics cost --today
💰 Today's Usage Cost
Date: 2024-12-01
Cost: $2.45
Tokens: 12,450
```

--------------------------------

### Install Claudelytics via Cargo

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Installs the latest version of Claudelytics from crates.io using Cargo. Verify the installation by checking the version.

```bash
cargo install claudelytics
claudelytics --version
```

--------------------------------

### Configuration Options in YAML

Source: https://github.com/nwiizo/claudelytics/blob/main/docs/conversation-viewer-spec.md

Example configuration file (`config.yaml`) showing new options for conversation handling, analysis, and caching. These settings control default formats, display preferences, and performance features.

```yaml
# config.yaml additions
conversation:
  default_format: enhanced  # enhanced, compact, markdown
  show_thinking: true
  show_tools: true
  syntax_highlighting: true
  max_preview_lines: 10
  export_format: markdown  # markdown, html, json
  
analysis:
  enable_topic_modeling: true
  enable_sentiment: true
  topic_count: 10
  
cache:
  enable_conversation_cache: true
  max_cache_size_mb: 100
  cache_ttl_hours: 24
```

--------------------------------

### Claudelytics CLI JSON Output Example

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Use the --json flag with Claudelytics commands to get output in JSON format, which can be piped to tools like jq for further processing.

```bash
claudelytics --json daily | jq '...'
```

--------------------------------

### Get Cache Statistics for a Specific Session

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Retrieve detailed per-session cache statistics, including turn count, cold start percentage, hit percentage, and token usage.

```bash
# Per-session cache stats for a specific session ID
claudelytics cache-stats --session-id <uuid>
```

```json
# JSON output for cache-stats
claudelytics --json cache-stats --session-id <uuid>
# {
#   "turn_count": 12,
#   "cold_pct": 0.083,
#   "hit_pct": 0.750,
#   "churn_tokens_per_turn": 450,
#   "total_tokens": 85000,
#   "cache_read_tokens": 63750
# }
```

--------------------------------

### Install Claudelytics Binary Manually

Source: https://github.com/nwiizo/claudelytics/blob/main/INSTALL.md

Moves the extracted binary to a directory in your PATH or a user-specific bin directory, and makes it executable on Unix systems.

```bash
# Move to a directory in your PATH
sudo mv claudelytics /usr/local/bin/
```

```bash
# Or to user directory
mkdir -p ~/.local/bin
mv claudelytics ~/.local/bin/
```

```bash
# Make executable (Unix systems)
chmod +x /usr/local/bin/claudelytics
```

--------------------------------

### Verify Claudelytics Installation

Source: https://github.com/nwiizo/claudelytics/blob/main/INSTALL.md

Commands to check if claudelytics is installed correctly and accessible in the system's PATH.

```bash
# Check version
claudelytics --version

# Show help
claudelytics --help

# Run a basic command
claudelytics config --show
```

--------------------------------

### Claudelytics Data Structure Example

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Visualizes the directory structure used by Claudelytics to store project and session data, including the location of chat log files.

```bash
~/.claude/
└── projects/
    ├── project-name-1/
    │   ├── session-abc123/
    │   │   └── chat_2024_01_01.jsonl
    │   └── session-def456/
    │       └── chat_2024_01_02.jsonl
    └── project-name-2/
        └── nested/
            └── path/
                └── session-ghi789/
                    └── chat_2024_01_03.jsonl
```

--------------------------------

### TUI: Conversation Viewer Layout Example

Source: https://github.com/nwiizo/claudelytics/blob/main/docs/conversation-viewer-spec.md

Illustrates the visual layout of the conversation viewer in the TUI, showing session metadata, message structure, tool usage, and navigation controls.

```text
┌─────────────────────────────────────────────────────────────┐
│ Session: project-name/2024-01-15 | Messages: 42 | Cost: $1.23│
├─────────────────────────────────────────────────────────────┤
│ [User] 2024-01-15 10:30:15                                  │
│ How can I implement a binary search tree in Rust?           │
├─────────────────────────────────────────────────────────────┤
│ [Assistant] 2024-01-15 10:30:18                            │
│ I'll help you implement a binary search tree in Rust...     │
│                                                              │
│ ```rust                                                      │
│ struct Node<T> {
│     value: T,
│     left: Option<Box<Node<T>>>,
│     right: Option<Box<Node<T>>>,
│ }
│ ```                                                         │
├─────────────────────────────────────────────────────────────┤
│ [Tool Use] search_files                                     │
│ Pattern: "binary.*tree" | Files found: 3                   │
├─────────────────────────────────────────────────────────────┤
│ [j/k] Navigate | [/] Search | [t] Toggle view | [e] Export │
└─────────────────────────────────────────────────────────────┘
```

--------------------------------

### Claudelytics YAML Configuration File Structure

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Example structure of the `config.yaml` file used by Claudelytics to manage persistent settings.

```yaml
# ~/.config/claudelytics/config.yaml
claude_path: /custom/path/to/.claude
default_output_format: Table   # Enhanced | Table | Json
default_command: Daily         # Daily | Session | Interactive | Tui | AdvancedTui
export_directory: ~/reports
date_format: "%Y-%m-%d"
```

--------------------------------

### Claudelytics Interactive Mode Example

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Illustrates the interactive mode interface for selecting Claude sessions, displaying session names, token counts, and associated costs.

```bash
📊 Claude Session Selector (ESC/q: quit, Enter: select)
🔍 Query: 
────────────────────────────────────────────────────────────
► project-1/feature-implementation
  📝 In: 1,245 | 📤 Out: 2,103 | 💰 $0.42

  project-2/bug-fixes
  📝 In: 891 | 📤 Out: 1,567 | 💰 $0.31

  project-3/documentation
  📝 In: 567 | 📤 Out: 1,234 | 💰 $0.23
```

--------------------------------

### Publish Homebrew Tap

Source: https://github.com/nwiizo/claudelytics/blob/main/release-checklist.md

Push the Homebrew tap repository to GitHub. This makes the claudelytics formula available for installation via `brew install claudelytics`.

```bash
# 1. Push homebrew-claudelytics repository
# 2. Users can then install with:
brew tap nwiizo/claudelytics
brew install claudelytics
```

--------------------------------

### Claudelytics CLI Budget Status Example

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Monitor budget status using the --json budget-status command, specifying a budget limit. This is useful for triggering alerts when costs approach a threshold.

```bash
claudelytics --json budget-status --budget N
```

--------------------------------

### Get SHA256 Checksums for Homebrew Formula

Source: https://github.com/nwiizo/claudelytics/blob/main/release-checklist.md

Download release artifacts and calculate their SHA256 checksums. These are required for updating the Homebrew formula.

```bash
# 1. Download and get SHA256 checksums for each platform
curl -fsSL https://github.com/nwiizo/claudelytics/releases/download/v0.1.0/claudelytics-x86_64-apple-darwin.tar.gz | shasum -a 256
curl -fsSL https://github.com/nwiizo/claudelytics/releases/download/v0.1.0/claudelytics-aarch64-apple-darwin.tar.gz | shasum -a 256
curl -fsSL https://github.com/nwiizo/claudelytics/releases/download/v0.1.0/claudelytics-x86_64-unknown-linux-gnu.tar.gz | shasum -a 256
curl -fsSL https://github.com/nwiizo/claudelytics/releases/download/v0.1.0/claudelytics-aarch64-unknown-linux-gnu.tar.gz | shasum -a 256

# 2. Update Formula/claudelytics.rb with:
#    - New version number
#    - New SHA256 checksums for each platform
```

--------------------------------

### Test Homebrew Formula Locally

Source: https://github.com/nwiizo/claudelytics/blob/main/release-checklist.md

Install and test the claudelytics formula locally using Homebrew. This ensures the formula works correctly before publishing.

```bash
# Test the formula locally
brew install --build-from-source ./Formula/claudelytics.rb

# Test that it works
claudelytics --version
claudelytics --help

# Clean up
brew uninstall claudelytics
```

--------------------------------

### Analyze Cache Behavior

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Analyze per-session cache performance, including TTL buckets, hit rates, cold starts, and churn rates. Use flags to sort, filter, and specify output.

```bash
# Top 10 sessions by cache write cost (default)
claudelytics cache
```

```bash
# Top 20 sessions sorted by hit rate descending
claudelytics cache --top 20 --sort hit-rate --desc
```

```bash
# Filter to a specific project
claudelytics --today cache --project myproject
```

```bash
# Only show sessions with ≥90% hit rate
claudelytics cache --min-hit 90
```

```bash
# Show sessions with ≥50% churn rate
claudelytics cache --min-churn 50
```

```bash
# JSON output
claudelytics --json cache
```

--------------------------------

### Launch Interactive TUI

Source: https://github.com/nwiizo/claudelytics/blob/main/homebrew-claudelytics/README.md

Starts the Claudelytics tool in an interactive Text User Interface (TUI) mode.

```bash
claudelytics tui
```

--------------------------------

### Add Homebrew Tap

Source: https://github.com/nwiizo/claudelytics/blob/main/homebrew-claudelytics/README.md

Adds the necessary tap to your Homebrew installation to access the Claudelytics formula.

```bash
brew tap nwiizo/claudelytics
```

--------------------------------

### Get Cost Summary

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Provides a quick cost lookup without generating a full report. Can show total cumulative cost, today's cost, or cost for a specific date.

```bash
claudelytics cost
```

```bash
claudelytics cost --today
```

```bash
claudelytics cost --date 20241201
```

--------------------------------

### Generate Weekly Report

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Generates a weekly usage report. Supports custom start days for the week and different output formats like JSON or classic tables.

```bash
claudelytics weekly
```

```bash
claudelytics weekly --start-of-week sunday
```

```bash
claudelytics --json weekly
```

```bash
claudelytics weekly --classic
```

--------------------------------

### TUI: Search and Filter Interface Example

Source: https://github.com/nwiizo/claudelytics/blob/main/docs/conversation-viewer-spec.md

Visual representation of the search and filter interface within the TUI, including input fields for keywords, role, date, project, and checkboxes for advanced options.

```text
┌─ Search & Filter ───────────────────────────────────────────┐
│ Search: [keyword________________]                           │
│ Role: [All ▼] | Date: [Last 7 days ▼] | Project: [All ▼]  │
│ □ Show thinking blocks  □ Show tool usage  □ Compact view  │
└─────────────────────────────────────────────────────────────┘
```

--------------------------------

### JSONL Data Format Example

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Each line in a Claudelytics JSONL file represents a usage record with details like timestamp, request ID, cost, and message information including token usage.

```json
{
  "timestamp": "2024-12-01T12:34:56Z",
  "requestId": "req_abc123",
  "costUSD": 0.0245,
  "message": {
    "id": "msg_xyz789",
    "model": "claude-opus-4-20250514",
    "usage": {
      "input_tokens": 1000,
      "output_tokens": 2000,
      "cache_creation_input_tokens": 500,
      "cache_read_input_tokens": 300,
      "speed": "standard"
    }
  }
}
```

--------------------------------

### Run Development Build

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Execute the project in development mode to see help for the 'daily' command. Ensure the project is built first.

```bash
cargo run -- daily --help
```

--------------------------------

### Run Release Build

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Execute the project in release mode to generate JSON output for the 'session' command. This is optimized for performance.

```bash
cargo run --release -- session --json
```

--------------------------------

### Show Help Information

Source: https://github.com/nwiizo/claudelytics/blob/main/homebrew-claudelytics/README.md

Displays the help message and available options for the claudelytics CLI.

```bash
claudelytics --help
```

--------------------------------

### Uninstall Claudelytics with Homebrew

Source: https://github.com/nwiizo/claudelytics/blob/main/homebrew-claudelytics/README.md

Removes the claudelytics tool and its associated tap from your Homebrew installation.

```bash
brew uninstall claudelytics
brew untap nwiizo/claudelytics
```

--------------------------------

### Troubleshoot 'Permission denied' Error

Source: https://github.com/nwiizo/claudelytics/blob/main/INSTALL.md

Steps to resolve permission errors, focusing on ensuring the binary has execute permissions and checking directory permissions.

```bash
# Make sure the binary is executable:
chmod +x /path/to/claudelytics
```

```bash
# Check directory permissions:
ls -la /path/to/claudelytics
```

--------------------------------

### Create Homebrew Tap Repository

Source: https://github.com/nwiizo/claudelytics/blob/main/release-checklist.md

Set up a new Homebrew tap repository for claudelytics. This involves creating a repository, copying the formula, and adding a README.

```bash
# 1. Create new repository: homebrew-claudelytics
# 2. Copy Formula/claudelytics.rb to the root
# 3. Add README.md for the tap
```

--------------------------------

### Live Dashboard Options

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Launches a real-time token burn rate dashboard with customizable refresh rates, token limits, and cost limits. The alternative 'blocks' command can also be used in live mode.

```bash
claudelytics live
```

```bash
claudelytics live --refresh 10
```

```bash
claudelytics live --token-limit 1000000
```

```bash
claudelytics live --cost-limit 50
```

```bash
claudelytics blocks --live
```

--------------------------------

### Build and Run Claudelytics with Docker

Source: https://github.com/nwiizo/claudelytics/blob/main/INSTALL.md

Builds a Docker image for claudelytics and runs it, mounting the local Claude data directory to the container.

```bash
# Build the image
docker build -t claudelytics .

# Run with your Claude data mounted
docker run --rm -v ~/.claude:/root/.claude claudelytics daily
```

--------------------------------

### Enable Responsive Tables with CLI Flags

Source: https://github.com/nwiizo/claudelytics/blob/main/docs/responsive-tables.md

Add the `--responsive` flag to any command that displays tables to enable this feature. This flag can be combined with other command-line options.

```bash
claudelytics --responsive daily
```

```bash
claudelytics --responsive session
```

```bash
claudelytics --responsive billing-blocks
```

```bash
claudelytics --responsive --today daily
```

```bash
claudelytics --responsive --since 20240101 session
```

--------------------------------

### Watch Mode

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Continuously re-renders reports whenever Claude data changes. Starts watch mode and monitors the specified directory, exiting with Ctrl+C.

```bash
claudelytics watch
```

--------------------------------

### Troubleshoot 'Command not found' Error

Source: https://github.com/nwiizo/claudelytics/blob/main/INSTALL.md

Steps to resolve 'command not found' errors, including checking the PATH and ensuring the binary is executable.

```bash
# Check if the binary is in your PATH:
echo $PATH
which claudelytics
```

```bash
# Add the installation directory to your PATH:
export PATH="/path/to/claudelytics:$PATH"
```

```bash
# Make sure the binary is executable:
chmod +x /path/to/claudelytics
```

--------------------------------

### Claudelytics Build and Development Commands

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Lists essential Cargo commands for building, testing, and formatting the Claudelytics project from source.

```bash
# Clone repository
git clone https://github.com/nwiizo/claudelytics.git
cd claudelytics

# Build debug version
cargo build

# Build release version
cargo build --release

# Run tests
cargo test

# Format code
cargo fmt

# Check formatting
cargo fmt --check
```

--------------------------------

### Format Code

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Format the project's code according to standard Rust conventions. This should be run before committing changes.

```bash
cargo fmt
```

--------------------------------

### Tag and Push Release

Source: https://github.com/nwiizo/claudelytics/blob/main/release-checklist.md

Tag the release with a version number and push it to the origin. GitHub Actions will automatically build binaries and create a release.

```bash
# 1. Tag the release
git tag v0.1.0
git push origin v0.1.0

# 2. GitHub Actions will automatically:
#    - Build binaries for all platforms
#    - Create GitHub release
#    - Upload release artifacts
```

--------------------------------

### Manage Pricing Cache

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Commands to manage the 7-day offline pricing cache. Use '--show' to view status, '--clear' to remove it, and '--update' to force a rebuild.

```bash
# Show cache status, age, validity, and cached model list
claudelytics pricing-cache --show
```

```bash
# Clear the cache (falls back to built-in pricing)
claudelytics pricing-cache --clear
```

```bash
# Force update / rebuild the cache
claudelytics pricing-cache --update
```

--------------------------------

### List Registered Models

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Display all registered language models, including their families and aliases.

```bash
claudelytics --list-models
```

--------------------------------

### Run Tests

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Execute the project's test suite to ensure code integrity. This is a standard step in the contribution workflow.

```bash
cargo test
```

--------------------------------

### Run Claudelytics using Docker

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Builds a Docker image for Claudelytics and runs a container. Mounts the local Claude configuration directory to the container for data access.

```bash
docker build -t claudelytics .
docker run --rm -v ~/.claude:/root/.claude claudelytics daily
```

--------------------------------

### Date Filtering for Usage Data

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Filters usage data by date ranges. Supports specifying a start date ('--since'), an end date ('--until'), or both. The '--today' flag shows only current day's data.

```bash
claudelytics daily --since 20240101
```

```bash
claudelytics daily --until 20240131
```

```bash
claudelytics daily --since 20240101 --until 20240131
```

```bash
claudelytics --today
```

```bash
claudelytics daily --today
```

```bash
claudelytics session --today
```

--------------------------------

### Show Realtime Analytics

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Display a snapshot of realtime analytics, including burn rate and budget projections. Set daily, monthly, or yearly limits and alert thresholds.

```bash
# Show all real-time analytics
claudelytics realtime
```

```bash
# With budget limits for projections and alerts
claudelytics realtime --daily-limit 5.0 --monthly-limit 100.0
```

```bash
# With yearly limit and custom alert threshold (80% of budget)
claudelytics realtime --yearly-limit 1000 --alert-threshold 0.8
```

```bash
# JSON output for monitoring pipelines
claudelytics realtime --json
```

--------------------------------

### CLI: Show Advanced Conversation Details

Source: https://github.com/nwiizo/claudelytics/blob/main/docs/conversation-viewer-spec.md

View conversations with additional details like thinking blocks or tool usage, or in a compact format.

```bash
claudelytics conversation <session-id> --show-thinking  # Show thinking blocks
```

```bash
claudelytics conversation <session-id> --show-tools     # Show tool usage
```

```bash
claudelytics conversation <session-id> --compact        # Compact view
```

--------------------------------

### View Command Aliases

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Shorthand aliases for the 'view' command to quickly access different functionalities.

```bash
claudelytics view abc123
```

```bash
claudelytics view --project myproject --list
```

```bash
claudelytics view --recent --export markdown -o recent.md
```

--------------------------------

### CLI: Enhance Session Command

Source: https://github.com/nwiizo/claudelytics/blob/main/docs/conversation-viewer-spec.md

Add conversation preview and summary options to the 'session' command.

```bash
claudelytics session --preview
```

```bash
claudelytics session --summary
```

--------------------------------

### Run Rust Project Checks

Source: https://github.com/nwiizo/claudelytics/blob/main/CLAUDE.md

Execute standard Rust project checks including formatting, linting with warnings enabled, and running tests.

```bash
cargo fmt && cargo clippy -- -D warnings && cargo test
```

--------------------------------

### Live Dashboard

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Provides a continuously refreshing real-time burn rate dashboard. Supports custom refresh intervals and limits, and can be accessed via the 'blocks --live' command.

```bash
claudelytics live
```

```bash
claudelytics live --refresh 10 --token-limit 1000000 --cost-limit 50
```

```bash
claudelytics blocks --live
```

--------------------------------

### Claudelytics Configuration Commands

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Provides bash commands for managing Claudelytics configuration, including showing current settings, setting custom paths, and resetting to defaults.

```bash
# View current configuration
claudelytics config --show

# Set custom Claude path
claudelytics config --set-path /path/to/.claude

# Reset to defaults
claudelytics config --reset
```

--------------------------------

### CLI: Analyze Content Patterns

Source: https://github.com/nwiizo/claudelytics/blob/main/docs/conversation-viewer-spec.md

Utilize the 'analyze-content' command for various content analysis tasks.

```bash
claudelytics analyze-content --topic-modeling
```

```bash
claudelytics analyze-content --sentiment
```

```bash
claudelytics analyze-content --tool-usage
```

```bash
claudelytics analyze-content --message-length
```

--------------------------------

### Fish Aliases for Claudelytics

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Sets up convenient Fish shell aliases for common Claudelytics commands, simplifying daily usage and quick checks.

```fish
# Claudelytics aliases
alias ctoday='claudelytics cost --today'
alias csum='claudelytics cost'
alias cwt='claudelytics --today'
alias cwatch='claudelytics watch'
alias cint='claudelytics interactive'
alias ctui='claudelytics tui'
alias catui='claudelytics advanced-tui'
```

--------------------------------

### Pricing Cache Management

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Manages the pricing cache. Commands allow viewing the cache status and clearing it.

```bash
claudelytics pricing-cache
```

```bash
claudelytics pricing-cache --clear
```

--------------------------------

### Show Daily Usage Report

Source: https://github.com/nwiizo/claudelytics/blob/main/homebrew-claudelytics/README.md

Generates and displays a daily usage report using the claudelytics CLI.

```bash
claudelytics daily
```

--------------------------------

### Perform Post-Implementation Duplication Check

Source: https://github.com/nwiizo/claudelytics/blob/main/CLAUDE.md

Use the similarity-rs tool to check for code duplication within the src directory, focusing on segments with at least 50 tokens.

```bash
similarity-rs ./src --min-tokens 50
```

--------------------------------

### Generate Usage Projections

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Forecast future token consumption and costs based on historical data. Specify the projection duration and set token or cost limits.

```bash
# 30-day projection (default)
claudelytics projections
```

```bash
# 90-day projection with token and cost limits
claudelytics projections --days 90 --token-limit 5000000 --cost-limit 500
```

```json
# JSON output
claudelytics projections --json
# {
#   "daily_average": 1.23,
#   "weekly_average": 8.61,
#   "monthly_average": 37.5,
#   "trend": "Increasing",
#   "growth_rate": 12.5,
#   "estimated_monthly_cost": 42.0,
#   "days_until_limit": 18,
#   "projections": [...] 
# }
```

--------------------------------

### Daily Report Table - Normal Mode

Source: https://github.com/nwiizo/claudelytics/blob/main/docs/responsive-tables.md

Shows a standard set of columns with full headers, including Date, Cost (USD), Total Tokens, Input, Output, and O/I Ratio, for terminals between 80-120 columns wide.

```text
Date       Cost (USD)  Total Tokens  Input    Output   O/I Ratio
---------- ----------- ------------- -------- -------- ---------
2024-01-07 $0.1234     1,234         500      734      1.5:1
2024-01-06 $0.5678     5,678         2,000    3,678    1.8:1
Total      $0.6912     6,912         2,500    4,412    1.8:1
```

--------------------------------

### Generate Daily Usage Report

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Generates a daily usage report, showing token usage and costs aggregated by calendar date. Supports various output formats, filters, and sorting options.

```bash
# Compact table (default)
claudelytics daily

# Verbose enhanced output with burn rates
claudelytics -v daily

# Classic ASCII table
claudelytics daily --classic

# JSON output — pipe-friendly for scripting
claudelytics --json daily | jq '.totals.total_cost'

# Date range filter
claudelytics daily --since 20240101 --until 20240131

# Today only
claudelytics --today daily

# Last 7 / 30 days shortcuts
claudelytics --last-7d daily
claudelytics --last-30d daily

# Sort by cost descending
claudelytics daily --sort-by cost --sort-order desc

# Filter to Opus model usage only
claudelytics --model-filter opus daily

# Cost calculation modes
claudelytics --cost-mode auto daily      # use costUSD if present, else recalculate
claudelytics --cost-mode calculate daily # always recalculate from token counts
claudelytics --cost-mode display daily   # show costUSD field verbatim
```

--------------------------------

### Configure Claudelytics Settings

Source: https://github.com/nwiizo/claudelytics/blob/main/INSTALL.md

Commands to manage claudelytics configuration, including showing current settings, setting a custom Claude directory, and resetting to defaults.

```bash
# Show current configuration
claudelytics config --show

# Set custom Claude directory path
claudelytics config --set-path /path/to/claude

# Reset configuration to defaults
claudelytics config --reset
```

--------------------------------

### CLI: View Conversations by Project

Source: https://github.com/nwiizo/claudelytics/blob/main/docs/conversation-viewer-spec.md

Filter and view conversations associated with a specific project name.

```bash
claudelytics conversation --project <project-name>
```

--------------------------------

### Claudelytics Basic Usage Commands

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Perform core analytics tasks with these basic Claudelytics commands. Includes daily and session reports, and the interactive session selector.

```bash
claudelytics daily
```

```bash
claudelytics session
```

```bash
claudelytics interactive
```

--------------------------------

### Inspect Sessions

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Commands to inspect session details, including metadata, token breakdown, and activity timeline. Use '--recent' for the last 7 days and '--detailed' for full information.

```bash
# Inspect top 10 sessions (default)
claudelytics inspect
```

```bash
# Inspect a specific session by ID
claudelytics inspect abc123def456
```

```bash
# Inspect all sessions from a project
claudelytics inspect --project myproject
```

```bash
# Recent sessions (last 7 days) with full detail
claudelytics inspect --recent --detailed
```

```bash
# Include conversation file list and activity timeline
claudelytics inspect --recent --conversations --timeline
```

```bash
# JSON output for automation
claudelytics inspect --project myproject --json
```

--------------------------------

### Generate Monthly Usage Report

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Generates a monthly usage report for long-term trend analysis, aggregating token usage and costs by calendar month. Supports various output formats and date filtering.

```bash
# Enhanced monthly view
claudelytics monthly

# Classic table
claudelytics monthly --classic

# JSON output
claudelytics --json monthly

# From a specific month onwards
claudelytics --since 20240101 monthly
```

--------------------------------

### Bash Aliases for Claudelytics

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Sets up convenient Bash aliases for common Claudelytics commands, simplifying daily usage and quick checks.

```bash
# Claudelytics aliases
alias ctoday='claudelytics cost --today'
alias csum='claudelytics cost'
alias cwt='claudelytics --today'
alias cwatch='claudelytics watch'
alias cint='claudelytics interactive'
alias ctui='claudelytics tui'
alias catui='claudelytics advanced-tui'
```

```bash
# Function to check cost for specific date
cdate() {
    if [ $# -eq 0 ]; then
        echo "Usage: cdate YYYYMMDD"
        return 1
    fi
    claudelytics cost --date "$1"
}
```

```bash
# Quick daily summary
cdaily() {
    echo "📊 Claude Usage Summary"
    claudelytics cost --today
    echo ""
    claudelytics --today
}
```

--------------------------------

### Configuration Management

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Manages Claudelytics configuration. Allows showing the current configuration and setting a custom path for configuration files.

```bash
claudelytics config --show
```

```bash
claudelytics config --set-path /path/to/claude
```

--------------------------------

### Display Billing Blocks

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Organizes and displays usage by Claude's 5-hour billing windows. Supports enhanced display, summary statistics, today's blocks, JSON output, and responsive/classic table layouts.

```bash
claudelytics billing-blocks
```

```bash
claudelytics billing-blocks --summary
```

```bash
claudelytics --today billing-blocks
```

```bash
claudelytics billing-blocks --json
```

```bash
claudelytics --responsive billing-blocks
```

```bash
claudelytics billing-blocks --classic
```

--------------------------------

### Development Build and Run Claudelytics

Source: https://github.com/nwiizo/claudelytics/blob/main/INSTALL.md

Builds the project in debug mode for faster compilation, runs the application with arguments, and executes tests.

```bash
# Build in debug mode (faster compilation)
cargo build

# Run directly
cargo run -- --help

# Run tests
cargo test
```

--------------------------------

### Sort Monthly Usage

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Sorts the monthly usage report by total tokens in ascending order. Requires the 'monthly' command with sort options.

```bash
claudelytics monthly --sort-by tokens --sort-order asc
```

--------------------------------

### Daily Report Table - Ultra Compact Mode

Source: https://github.com/nwiizo/claudelytics/blob/main/docs/responsive-tables.md

Displays essential columns like Date, Cost, and Tokens, with abbreviated headers, suitable for terminals less than 60 columns wide.

```text
Date       Cost    Tokens
---------- ------- -------
2024-01-07 $0.1234   1.2K
2024-01-06 $0.5678   5.6K
Total      $0.6912   6.8K
```

--------------------------------

### Run Specific Commands

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Execute specific Claudelytics commands for daily cost analysis, interactive mode, TUI, advanced TUI, or watch mode. Ensure the project is built.

```bash
cargo run -- cost --today
```

```bash
cargo run -- interactive
```

```bash
cargo run -- tui
```

```bash
cargo run -- advanced-tui
```

```bash
cargo run -- watch
```

--------------------------------

### Analyze Session Blocks

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Analyzes usage in configurable time windows, defaulting to 8-hour blocks. Supports active blocks only, custom lengths, recent data, and limit warnings.

```bash
claudelytics blocks
```

```bash
claudelytics blocks --active
```

```bash
claudelytics blocks --length 4 --recent
```

```bash
claudelytics blocks --token-limit 1000000 --cost-limit 50
```

--------------------------------

### Export Data to CSV

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Exports daily, session, or summary data to CSV format. Use the '-o' flag to specify the output file name.

```bash
claudelytics export --daily --sessions --summary
```

--------------------------------

### Billing Blocks Analysis

Source: https://github.com/nwiizo/claudelytics/blob/main/README.md

Analyzes 5-hour billing blocks. Supports standard output and JSON output.

```bash
claudelytics billing-blocks
```

```bash
claudelytics billing-blocks --json
```

--------------------------------

### Generate Session Usage Report

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Generates a per-session usage report, breaking down token usage and costs by individual Claude Code sessions. Supports various output formats, filters, and sorting.

```bash
# Enhanced per-session view
claudelytics session

# Classic table
claudelytics session --classic

# JSON output
claudelytics --json session

# Today's sessions sorted by efficiency (tokens per dollar)
claudelytics --today session --sort-by efficiency --sort-order desc

# Sessions for a specific project (model filter + date range)
claudelytics --model-filter sonnet --since 20240601 session

# Responsive layout (auto-adjusts columns for narrow terminals)
claudelytics --responsive session
```

--------------------------------

### Perform Session Analytics

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Analyze session patterns including time-of-day, day-of-week, duration, frequency, and cost efficiency. Use flags to focus on specific analytical dimensions.

```bash
# Show all analytics
claudelytics analytics
```

```bash
# Time of day analysis only (peak hour, business vs after-hours split)
claudelytics analytics --time-of-day
```

```bash
# Day of week analysis (most/least active, weekend ratio)
claudelytics analytics --day-of-week
```

```bash
# Session duration distribution (< 5 min, 5–30, 30–60, 1–3h, > 3h)
claudelytics analytics --duration
```

```bash
# Frequency analysis (sessions/day, longest streak, current streak)
claudelytics analytics --frequency
```

```bash
# Cost efficiency (most expensive, most efficient, sessions above threshold)
claudelytics analytics --efficiency --threshold 2.0
```

--------------------------------

### Check Claudelytics Directory Path

Source: https://github.com/nwiizo/claudelytics/blob/main/INSTALL.md

View the current Claude directory path configured in Claudelytics.

```bash
claudelytics config --show
```

--------------------------------

### Export Usage Data to CSV

Source: https://context7.com/nwiizo/claudelytics/llms.txt

Export usage data into CSV files for external analysis. Specify report types and output paths.

```bash
# Export all three report types to default location
claudelytics export
# Creates: ./claudelytics_export.daily.csv
#          ./claudelytics_export.sessions.csv
#          ./claudelytics_export.summary.csv
```

```bash
# Export specific types to a custom base path
claudelytics export --daily --sessions -o ~/reports/dec2024
# Creates: ~/reports/dec2024.daily.csv
#          ~/reports/dec2024.sessions.csv
```

```bash
# Export summary only
claudelytics export --summary -o ~/reports/summary
```

```bash
# Filter by date range before exporting
claudelytics --since 20241101 --until 20241130 export --daily -o ~/reports/nov
```

--------------------------------

### CLI: Export Conversation

Source: https://github.com/nwiizo/claudelytics/blob/main/docs/conversation-viewer-spec.md

Export a specific conversation in markdown, html, or json format.

```bash
claudelytics conversation <session-id> --export markdown
```

```bash
claudelytics conversation <session-id> --export html
```

```bash
claudelytics conversation <session-id> --export json
```

--------------------------------

### Set Correct Claude Directory Path

Source: https://github.com/nwiizo/claudelytics/blob/main/INSTALL.md

Configure Claudelytics with the correct path to your Claude data directory if it's not found.

```bash
claudelytics config --set-path /correct/path/to/claude
```