> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/charmbracelet/crush/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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

<ParamField path="--data-dir" type="string" default="~/.crush">
  Custom Crush data directory. Specify which Crush database to analyze.
</ParamField>

Other [global flags](/cli/crush#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

<CodeGroup>
  ```bash View stats theme={null}
  # Generate and view statistics
  crush stats
  ```

  ```bash Custom data directory theme={null}
  # View stats from a specific project
  crush stats --data-dir /path/to/project/.crush
  ```

  ```bash Debug mode theme={null}
  # Generate stats with debug logging
  crush stats --debug
  ```
</CodeGroup>

## 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:

```bash theme={null}
$ 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:

```bash theme={null}
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**:

```bash theme={null}
# 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**:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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`](/cli/logs) - View Crush logs
* [Configuration](/configuration/overview) - Understanding configuration
* [Metrics](/guides/metrics) - Understanding metrics and privacy