crush stats

View comprehensive usage statistics and analytics

The crush stats command generates and displays detailed usage statistics including token usage, costs, activity patterns, and tool usage analytics.

Usage

crush stats [flags]

Description

Generate and display comprehensive usage statistics in a beautiful HTML dashboard. The stats include:

• Total statistics: Sessions, tokens, costs, messages
• Daily usage: Token consumption and costs over time
• Model usage: Which models you use most
• Hourly patterns: When you’re most active
• Day of week: Activity by day
• Recent activity: Last 30 days of usage
• Tool usage: Which tools are called most frequently
• Heatmap: Hour-by-day activity visualization
• Response times: Average AI response times

Global Flags

--data-dir · string · default: "~/.crush"

Custom Crush data directory. Specify which Crush database to analyze.

Other global flags are also available: --debug

Output

The command generates an HTML file with interactive charts and visualizations:

Stats generated: ~/.crush/stats/index.html

The file is automatically opened in your default browser. If the browser fails to open, the path is displayed for manual opening.

Examples

View stats

# Generate and view statistics
crush stats

Statistics Breakdown

Total Stats

Overall usage metrics:

• Total Sessions: Number of Crush sessions
• Total Messages: Messages exchanged with AI
• Total Tokens: Combined prompt and completion tokens
  • Prompt Tokens: Tokens sent to the AI
  • Completion Tokens: Tokens generated by the AI
• Total Cost: Estimated cost in USD
• Average Tokens per Session: Mean token usage per session
• Average Messages per Session: Mean message count per session

Usage by Day

Daily breakdown showing:

• Date
• Prompt tokens
• Completion tokens
• Total tokens
• Cost
• Session count

Usage by Model

Model usage statistics:

• Model name (e.g., claude-sonnet-4-20250514)
• Provider (e.g., anthropic)
• Message count

Helps identify your most-used models.

Usage by Hour

Activity distribution across 24 hours:

• Hour (0-23)
• Session count

Shows when you’re most productive with Crush.

Usage by Day of Week

Weekly activity patterns:

• Day name (Sunday through Saturday)
• Session count
• Prompt tokens
• Completion tokens

Identify your most productive days.

Recent Activity

Last 30 days of activity:

• Date
• Session count
• Total tokens
• Cost

Track recent trends in your usage.

Tool Usage

Frequency of tool calls:

• Tool name (e.g., bash, edit, read)
• Call count

See which tools the AI uses most in your sessions.

Hour-Day Heatmap

Visualize activity across hours and days:

• X-axis: Hours (0-23)
• Y-axis: Days of week
• Color intensity: Session count

Identify your peak productivity patterns.

Average Response Time

Mean response time from the AI in milliseconds.

Generated HTML

The statistics page includes:

• Interactive charts: Built with JavaScript charting library
• Responsive design: Works on desktop and mobile
• Embedded styling: Self-contained HTML file
• Branding: Crush logo and styling
• Metadata: Generation date, project name, username

File Structure

~/.crush/stats/
└── index.html    # Self-contained HTML dashboard

The HTML file is completely self-contained with embedded:

• CSS styling
• JavaScript code
• SVG graphics
• Statistics data (JSON)

Example Output

When you run the command:

$ crush stats
Stats generated: /home/user/.crush/stats/index.html

The browser opens showing:

╔══════════════════════════════════════╗
║        Crush Usage Statistics        ║
║                                      ║
║  Project: ~/dev/my-project          ║
║  User: alice                        ║
║  Generated: 2025-03-11              ║
╚══════════════════════════════════════╝

Total Statistics
├── Sessions: 42
├── Messages: 384
├── Tokens: 1,234,567
│   ├── Prompt: 823,456
│   └── Completion: 411,111
└── Cost: $4.56

[Interactive Charts Below]
- Daily Usage Chart
- Model Usage Pie Chart
- Hourly Activity Bar Chart
- Day of Week Distribution
- Recent Activity Timeline
- Tool Usage Bar Chart
- Hour-Day Heatmap

Error Messages

No Data Available

no data available: no sessions found in database

Cause: No Crush sessions have been recorded yet.

Solution: Use Crush to create some sessions first:

crush
# or
crush run "test prompt"

Failed to Initialize Config

failed to initialize config: <error>

Cause: Configuration file is invalid or data directory doesn’t exist.

Solution:

# Check if config exists
cat ~/.crush/crush.json

# If missing, run crush to create it
crush

Failed to Connect to Database

failed to connect to database: <error>

Cause: Database file is missing or corrupted.

Solution:

# Check if database exists
ls -lh ~/.crush/crush.db

# If corrupted, backup and recreate
mv ~/.crush/crush.db ~/.crush/crush.db.backup
crush  # This will recreate the database

Browser Doesn’t Open

Could not open browser: <error>
Please open the file manually.

Cause: System browser couldn’t be launched.

Solution: Open the displayed file path manually:

# macOS
open ~/.crush/stats/index.html

# Linux
xdg-open ~/.crush/stats/index.html

# Or specify a browser
firefox ~/.crush/stats/index.html

Data Source

Statistics are gathered from the SQLite database at:

~/.crush/crush.db

The database contains:

• Sessions table: Session metadata
• Messages table: All messages with token counts
• Tool calls: Records of tool invocations
• Timestamps: For time-based analysis

Privacy & Analytics

The stats command:

• Runs locally: No data is sent to external servers
• Reads from local DB: Only accesses your local Crush database
• Generates local HTML: Output is saved to your filesystem
• No telemetry: Statistics generation doesn’t trigger any metrics

Use Cases

Cost Tracking

Monitor your AI API spending:

# Generate stats monthly
crush stats
# Review total cost in the dashboard

Usage Optimization

Identify patterns to optimize your workflow:

• Which models you use most
• Peak productivity hours
• Most-used tools
• Average session length

Team Reporting

Share usage insights:

# Generate stats
crush stats

# Share the HTML file
cp ~/.crush/stats/index.html ~/reports/crush-stats-march.html

Billing & Budgeting

Track costs for:

• Personal budget management
• Project cost allocation
• Client billing
• Team cost analysis

Telemetry

Running crush stats triggers an analytics event:

event.StatsViewed()

This can be disabled with:

• CRUSH_DISABLE_METRICS=true environment variable
• DO_NOT_TRACK=true environment variable
• "disable_metrics": true in crush.json

See Also

• crush logs - View Crush logs
• Configuration - Understanding configuration
• Metrics - Understanding metrics and privacy