Session Analytics¶

Automatically track comprehensive session statistics from your Claude Code sessions.

Overview¶

The Session Analytics feature uses two hooks: - SessionStart - Captures development environment context when a session begins - SessionEnd - Logs comprehensive session statistics when a session ends

All data is saved to ~/.claude/session-logs/sessions.csv for easy analysis.

Setting Ticket Numbers¶

Use the #ticket: command at the start of your message to associate sessions with specific tickets or issues:

#ticket: JIRA-1234

You can add multiple tickets in a single command:

#ticket: JIRA-1234 GH-567

Or add tickets incrementally throughout the session:

#ticket: JIRA-1234
# ... work on first ticket ...
#ticket: JIRA-5678
# ... work on second ticket ...

All tickets will be logged as a space-separated list: JIRA-1234 JIRA-5678

Setting Session Topics¶

Use the #topic: command at the start of your message to describe what you're working on:

#topic: feat: Refactoring authentication module
#topic: fix: Resolving login bug
#topic: refactor: Optimizing database queries

The topic supports conventional commit message prefixes (feat:, fix:, refactor:, docs:, test:, etc.) for consistency.

You can update the topic at any time during the session:

#topic: feat: Refactoring authentication module
# ... work on refactoring ...
#topic: feat: Added OAuth support to authentication module

Pro tip: Set the topic early in your session for better tracking and reporting.

Combining Commands¶

You can set both ticket and topic in a single message:

#ticket: JIRA-1234 #topic: feat: Adding dark mode support

What Gets Tracked¶

CSV Columns (29 fields)¶

Cost Calculation¶

Costs are calculated automatically based on the AI model used in the session. Pricing data is stored in config/pricing.json and includes rates for:

• Claude Sonnet 4.5 (default)
• Claude Opus 4.5
• Claude Haiku 4
• Claude 3.5 Sonnet variants

The cost calculation uses the detected model from the session transcript and applies the corresponding pricing:

• Input tokens: Model-specific rate per million tokens
• Output tokens: Model-specific rate per million tokens
• Cache write: Model-specific rate per million tokens
• Cache read: Model-specific rate per million tokens

Example pricing (Sonnet 4.5 - January 2025): - Input: $3.00/million, Output: $15.00/million, Cache read: $0.30/million, Cache write: $3.75/million

To update pricing or add new models, edit config/pricing.json. See Configuration for details.

Session End Reasons¶

The end_reason field indicates how the session ended:

• clear - User ran /clear command
• logout - User logged out
• prompt_input_exit - User exited during a prompt
• other - Other exit scenarios

Viewing Data¶

Command Line¶

# View entire CSV
cat ~/.claude/session-logs/sessions.csv

# View with column formatting
column -t -s, ~/.claude/session-logs/sessions.csv | less -S

# Show specific columns (timestamp, project, cost)
cut -d, -f1,5,21 ~/.claude/session-logs/sessions.csv

# Filter by project
grep "my-project" ~/.claude/session-logs/sessions.csv

# Calculate total cost
awk -F, 'NR>1 {sum+=$21} END {print "Total: $"sum}' ~/.claude/session-logs/sessions.csv

# Cost by project
awk -F, 'NR>1 {cost[$5]+=$21} END {for(p in cost) print p": $"cost[p]}' ~/.claude/session-logs/sessions.csv

Import into Spreadsheet¶

• Excel: File → Open → Select sessions.csv
• Google Sheets: File → Import → Upload file
• Numbers: File → Open → Select sessions.csv

Python Analysis¶

import pandas as pd

# Load CSV
df = pd.read_csv('~/.claude/session-logs/sessions.csv')

# Calculate total cost
print(f"Total cost: ${df['total_cost'].sum():.2f}")

# Average session duration
print(f"Avg duration: {df['duration_seconds'].mean() / 60:.1f} minutes")

# Most used tools
print(df['tools_used'].value_counts().head())

# Cost by project
print(df.groupby('project')['total_cost'].sum())

Google Sheets Integration¶

For automatic cloud backup and team collaboration, see the Google Sheets Setup Guide.

Back to home