gptme-wrapped - SKILL.md Agent Skill

name: gptme-wrapped description: Analyze your gptme conversation history for insights like token usage, costs, model preferences, and usage patterns — inspired by Spotify Wrapped. license: MIT compatibility: "Requires gptme>=0.27.0" metadata: author: bob version: "1.0.0" tags: [analytics, conversations, tokens, costs, usage-patterns] requires_tools: [] requires_skills: []

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

Wait for data accumulation: Metadata tracking is recent; 2026 will have fuller data.
Filter by year: Use timestamp filtering to focus on specific periods.
Handle missing metadata: Older conversations may not have token/cost data.
Consider local models: Token counts exist but costs are $0 for local models.
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