gptme-wrapped git:20251226.b8022e7C

Immutable. This exact content never changes and is served at /api/v1/blob/254bd80aaaf95781.

# gptme Wrapped - Conversation Analytics

**Description:** Analyze your gptme conversation history for insights like token usage, costs, model preferences, and usage patterns - inspired by Spotify Wrapped.

## Overview

"gptme Wrapped" provides year-end (or any period) analytics for your gptme usage, similar to Spotify's annual Wrapped feature. It analyzes conversation logs stored locally to provide insights about:

- **Token usage**: Input/output tokens, cache hits
- **Cost tracking**: Spending by model, day, conversation
- **Model preferences**: Most used models, provider breakdown
- **Usage patterns**: Peak hours, conversation lengths, topics
- **Context efficiency**: Average context sizes, compression ratios

## Storage Structure

gptme stores conversations in `~/.local/share/gptme/logs/` with this structure:

```tree
~/.local/share/gptme/logs/
├── 2025-12-25-running-red-cat/
│   ├── conversation.jsonl    # Messages with metadata
│   ├── config.toml           # Conversation config (model, tools)
│   ├── branches/             # Conversation branches
│   └── workspace -> /path    # Symlink to workspace
└── ...
```

### Message Format (conversation.jsonl)

Each line is a JSON object representing a message:

```json
{
  "role": "assistant",
  "content": "...",
  "timestamp": "2025-12-25T22:47:40.922775",
  "metadata": {
    "model": "anthropic/claude-sonnet-4-20250514",
    "input_tokens": 33970,
    "output_tokens": 50,
    "cache_read_tokens": 30000,
    "cache_creation_tokens": 0,
    "cost": 0.0123
  }
}
```

**Key metadata fields:**
- `model`: The model used for generation
- `input_tokens`: Tokens sent to the model
- `output_tokens`: Tokens generated by the model
- `cache_read_tokens`: Tokens read from prompt cache (saves cost)
- `cache_creation_tokens`: Tokens written to prompt cache
- `cost`: Cost in USD (when available)

**Note:** Token metadata is only populated for assistant messages when the LLM API returns usage data. Historical conversations before this feature may not have metadata.

### Config Format (config.toml)

```toml
[chat]
name = "Conversation Name"
model = "anthropic/claude-sonnet-4-20250514"
tools = ["shell", "ipython", "save", "patch", ...]
workspace = "~/Programming/project"
```

## Best Practices

1. **Wait for data accumulation**: Metadata tracking is recent; 2026 will have fuller data.
2. **Filter by year**: Use timestamp filtering to focus on specific periods.
3. **Handle missing metadata**: Older conversations may not have token/cost data.
4. **Consider local models**: Token counts exist but costs are $0 for local models.
5. **Cache efficiency varies**: Depends on conversation patterns and model support.

## Plugin Integration

See `plugins/wrapped/` for the analytics plugin that provides:
- `wrapped_stats(year)`: Get comprehensive year stats
- `wrapped_report(year)`: Generate formatted ASCII report
- `wrapped_export(year, format)`: Export to HTML/JSON

## Related Skills

- **Cost Tracking**: Understanding gptme's cost tracking system
- **Context Management**: Managing token usage efficiently
- **Model Selection**: Choosing the right model for tasks