git:20251226.b8022e7 to v1.0.0

# 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