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

# Metrics and Privacy

> Understand what data Crush collects and how to opt out

## What Metrics Are Collected?

Crush collects **pseudonymous usage metadata** to help maintainers understand how the tool is used and prioritize development efforts. This data is tied to a device-specific hash, not your personal identity.

### What IS Collected

Crush collects usage events such as:

* **Application lifecycle**: When Crush starts and exits, session duration
* **Feature usage**: Sessions created, sessions deleted, sessions switched
* **Prompt activity**: When prompts are sent and received (timing and counts only)
* **Token usage**: Number of tokens consumed (for understanding usage patterns)
* **System information**: OS, architecture, terminal type, Crush version
* **Error events**: Error types and messages (to identify bugs)

### What is NOT Collected

Crush **never** collects:

* **Prompt content**: Your actual prompts or questions
* **LLM responses**: Any text generated by the AI
* **Code content**: Source code from your projects
* **File names or paths**: Specific files you're working with
* **API keys**: Your provider credentials
* **Personal information**: Email, username, or identifying details
* **Project details**: Repository names, URLs, or business logic

<Info>
  Metrics are strictly usage metadata. Your code, prompts, and AI conversations remain completely private.
</Info>

## How Metrics Work

### Device Identifier

Crush generates a pseudonymous device identifier using:

1. **Machine ID** (preferred): A stable, hashed identifier based on your machine
2. **MAC address hash** (fallback): A hashed network adapter address
3. **Unknown** (fallback): If neither can be determined

This identifier:

* Cannot be traced back to you personally
* Helps understand usage across multiple sessions
* Is stored locally and never transmitted with personal information

### Data Transmission

Metrics are sent to Charm's PostHog instance:

* **Endpoint**: `https://data.charm.land`
* **Protocol**: HTTPS (encrypted)
* **Frequency**: Events are sent as they occur and batched when possible
* **Timeout**: Short timeout to avoid impacting performance

## Viewing Collected Metrics

You can see exactly what Crush collects by reviewing the source code:

* **Event definitions**: [`internal/event/all.go`](https://github.com/charmbracelet/crush/blob/main/internal/event/all.go)
* **Event implementation**: [`internal/event/event.go`](https://github.com/charmbracelet/crush/blob/main/internal/event/event.go)
* **Agent events**: [`internal/llm/agent/event.go`](https://github.com/charmbracelet/crush/blob/main/internal/agent/event.go)

Crush is open source, so you can verify exactly what data is sent.

## How to Opt Out

You can disable metrics collection using any of these methods:

### Environment Variable: CRUSH\_DISABLE\_METRICS

Set the `CRUSH_DISABLE_METRICS` environment variable:

```bash theme={null}
# Unix/Linux/macOS
export CRUSH_DISABLE_METRICS=1

# Windows (PowerShell)
$env:CRUSH_DISABLE_METRICS=1

# Windows (Command Prompt)
set CRUSH_DISABLE_METRICS=1
```

To make this permanent:

```bash theme={null}
# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
echo 'export CRUSH_DISABLE_METRICS=1' >> ~/.bashrc
source ~/.bashrc
```

### Environment Variable: DO\_NOT\_TRACK

Crush respects the [DO\_NOT\_TRACK](https://consoledonottrack.com/) convention:

```bash theme={null}
# Unix/Linux/macOS
export DO_NOT_TRACK=1

# Windows (PowerShell)
$env:DO_NOT_TRACK=1
```

This is a standard convention respected by many CLI tools.

### Configuration File

Add the `disable_metrics` option to your `crush.json`:

```json theme={null}
{
  "options": {
    "disable_metrics": true
  }
}
```

This disables metrics for all sessions in this project.

**Configuration file locations:**

* Project-level: `.crush.json` or `crush.json` in your project root
* User-level: `~/.config/crush/crush.json` (Unix) or `%LOCALAPPDATA%\crush\crush.json` (Windows)

### Verification

To verify metrics are disabled:

1. Enable debug logging: `crush --debug`
2. Check the logs: `crush logs`
3. Look for absence of "PostHog" or "metrics" entries

You can also check the `shouldEnableMetrics` function in [`internal/cmd/root.go`](https://github.com/charmbracelet/crush/blob/main/internal/cmd/root.go) to see the exact logic.

## Privacy Considerations

### Local-First

Crush is designed with privacy in mind:

* All your data (sessions, messages, files) stays on your local machine
* The SQLite database (`./.crush/crush.db`) never leaves your device
* Logs (`./.crush/logs/crush.log`) are stored locally
* Metrics are the **only** data sent to external servers

### Provider Privacy

Your prompts and responses are sent to your configured LLM provider (OpenAI, Anthropic, etc.) according to their privacy policies. Crush itself does not intercept or store this data beyond your local session database.

**Review your provider's privacy policy:**

* [OpenAI Privacy Policy](https://openai.com/policies/privacy-policy)
* [Anthropic Privacy Policy](https://www.anthropic.com/privacy)
* [Google AI Privacy](https://ai.google/responsibility/privacy-terms/)

### Network Requests

Crush makes network requests to:

1. **LLM providers**: Your configured providers (OpenAI, Anthropic, etc.)
2. **Metrics endpoint**: `https://data.charm.land` (if metrics are enabled)
3. **Provider updates**: Checks for updated provider/model lists from [Catwalk](https://github.com/charmbracelet/catwalk)

You can disable provider auto-updates:

```json theme={null}
{
  "options": {
    "disable_provider_auto_update": true
  }
}
```

Or via environment variable:

```bash theme={null}
export CRUSH_DISABLE_PROVIDER_AUTO_UPDATE=1
```

## Why Metrics Matter

Metrics help the Crush maintainers:

* **Understand usage patterns**: Which features are most used?
* **Identify bugs**: What errors occur most frequently?
* **Prioritize development**: Where should we focus our efforts?
* **Measure impact**: How many people benefit from new features?
* **Support decisions**: Which platforms and configurations to prioritize?

All of this can be done with pseudonymous usage metadata—we don't need to see your code or prompts.

## Open Source Transparency

Crush is fully open source, which means:

* You can audit the metrics code yourself
* You can verify no sensitive data is collected
* You can contribute improvements to privacy and metrics
* You can fork and modify the metrics behavior if needed

**Key files to review:**

* Metrics initialization: [`internal/event/event.go`](https://github.com/charmbracelet/crush/blob/main/internal/event/event.go)
* Event definitions: [`internal/event/all.go`](https://github.com/charmbracelet/crush/blob/main/internal/event/all.go)
* Opt-out logic: [`internal/cmd/root.go`](https://github.com/charmbracelet/crush/blob/main/internal/cmd/root.go#L231-L242)
* Device identifier: [`internal/event/identifier.go`](https://github.com/charmbracelet/crush/blob/main/internal/event/identifier.go)

## Frequently Asked Questions

### Does Crush send my code to Charm servers?

No. Your code stays on your machine and is only sent to your configured LLM provider (OpenAI, Anthropic, etc.). Charm does not receive your code.

### Can I use Crush completely offline?

Yes, with caveats:

1. You'll need a local LLM provider (like Ollama or LM Studio)
2. Disable metrics (`CRUSH_DISABLE_METRICS=1`)
3. Disable provider auto-updates (`CRUSH_DISABLE_PROVIDER_AUTO_UPDATE=1`)

After initial setup, Crush can operate without internet access.

### What happens if metrics fail to send?

Nothing. Metrics are sent on a best-effort basis. If the network is unavailable or the endpoint is down, Crush continues working normally without any errors or delays.

### Can I see what metrics were sent?

Yes, enable debug logging:

```bash theme={null}
crush --debug
```

Then check the logs for PostHog events:

```bash theme={null}
crush logs | grep -i posthog
```

You'll see the exact events and properties being sent.

### Does opting out affect functionality?

No. Disabling metrics has zero impact on Crush functionality. All features work exactly the same whether metrics are enabled or disabled.

### How long is metrics data retained?

Metrics are stored in Charm's PostHog instance according to their data retention policy. Contact Charm for specific retention details.

## Summary

* **Metrics are pseudonymous usage metadata only**
* **Your code and prompts are never collected**
* **You can opt out easily** via environment variables or configuration
* **Metrics help improve Crush** for everyone
* **Crush is open source** so you can verify privacy claims

<Tip>
  If you're comfortable with it, leaving metrics enabled helps the Crush team build a better tool for everyone. But the choice is completely yours.
</Tip>