# Gptme Wrapped

> Analyze your gptme conversation history for insights like token usage, costs, model preferences, and usage patterns — inspired by Spotify Wrapped.

- Skill: `gptme/gptme-wrapped` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gptme/gptme-wrapped`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gptme/gptme-wrapped/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: gptme (https://skillmd.com/u/gptme)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/gptme/gptme-wrapped

---


# 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