gptme/gptme-contrib/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:

~/.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:

{
  "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)

[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