Claude Dev Insights

Developer analytics and productivity insights for Claude Code. Automatically track sessions with detailed metrics and optional Google Sheets sync using 3 intelligent hooks.

---

Features

📊 Session Analytics (SessionStart + SessionEnd + UserPromptSubmit)

• 29 data points per session - Duration, messages, tokens, costs, tool usage
• Local CSV storage - ~/.claude/session-logs/sessions.csv
• Google Sheets sync - Optional cloud backup for team sharing
• Environment profiling - CMS detection, dependency tracking, git status
• Ticket tracking - Auto-detect and log issue/ticket numbers
• Session summaries - Describe what you're working on

---

Quick Install

Via Claude Toolbox Marketplace:

# Inside Claude Code CLI
/plugin marketplace add kanopi/claude-toolbox
/plugin install claude-dev-insights@claude-toolbox

Direct Install:

# Inside Claude Code CLI
/plugin install https://github.com/kanopi/claude-dev-insights

That's it! Hooks activate automatically when the plugin is enabled.

---

Quick Start: Session Tracking

Track your work with structured commands at the start of your message:

Track Tickets

Use #ticket: to log issue/ticket numbers:

#ticket: JIRA-1234
#ticket: JIRA-1234 GH-567   # Multiple tickets
#ticket: ABC-999            # Add more later

Describe Your Work

Use #topic: to describe what you're working on:

#topic: feat: Adding user authentication
#topic: fix: Resolving checkout bug
#topic: refactor: Optimizing database queries

Combine Both

Set ticket and topic together:

#ticket: JIRA-1234 #topic: feat: Adding dark mode to dashboard

All data is logged to CSV for easy reporting:

grep JIRA-1234 ~/.claude/session-logs/sessions.csv

---

What Gets Tracked

Session CSV Columns (29 fields)

Column	Description	Example
timestamp	Session end timestamp	2025-11-12 08:45:23
session_id	Unique session identifier	abc123def456
user	Git user name or system username	John Doe
ticket_number	Optional ticket/issue number	JIRA-1234
project	Project directory name	my-project
summary	One-line session description	Feature: User Auth
cms_type	Detected CMS (drupal/wordpress/unknown)	drupal
environment_type	Environment (ddev/local)	ddev
dependencies_count	Number of composer dependencies	47
uncommitted_changes	Number of uncommitted files at start	3
source	Session source (new/resume)	new
end_reason	How session ended (clear/crash/etc)	clear
duration_seconds	Session duration in seconds	1847
user_messages	Number of user messages	45
assistant_messages	Number of assistant messages	62
input_tokens	Tokens sent to API	18943
output_tokens	Tokens generated by API	12561
cache_read_tokens	Tokens read from cache	2841023
cache_write_tokens	Tokens written to cache	198234
total_tokens	Sum of all token types	3070761
total_cost	Session cost in USD	2.1847
tool_calls	Number of tool invocations	38
api_time_seconds	Total API time in seconds	47
avg_call_time_ms	Average API call time in ms	1237
tools_used	Top 5 tools with counts	Bash:12; Read:10; Edit:8
git_branch	Active git branch	main
claude_version	Claude Code version	2.0.36
model	AI model used	claude-sonnet-4-5-20250929
permission_mode	Permission mode setting	default

---

Google Sheets Integration

Why Use Google Sheets?

• ☁️ Cloud backup - Your data is safe in the cloud
• 👥 Team sharing - Share insights with your team
• 📊 Easy visualization - Built-in charts and pivot tables
• 📱 Access anywhere - View on any device
• 🔄 Real-time sync - Data updates automatically

Quick Setup

1. Install Python dependencies:

   pip3 install gspread oauth2client

2. Run interactive setup:

   python3 ~/.claude/plugins/cache/claude-dev-insights/hooks/session-end/sync-to-google-sheets.py --setup

3. Test connection:

   python3 ~/.claude/plugins/cache/claude-dev-insights/hooks/session-end/sync-to-google-sheets.py --test

Full setup guide: docs/google-sheets/setup.md

---

Usage Examples

View Your Analytics

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

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

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

# Generate full report
python3 ~/.claude/plugins/cache/claude-dev-insights/lib/analytics.py markdown

---

Privacy & Security

What's Logged

• ✅ Session metadata (timestamps, IDs, duration)
• ✅ Usage statistics (tokens, costs, tool counts)
• ✅ Session summary (one-line description)
• ✅ Ticket numbers (for issue tracking)
• ❌ Not logged: Actual code, conversation content, sensitive data

Data Location

• Local CSV: ~/.claude/session-logs/sessions.csv (your machine only)
• Google Sheets: Only if you explicitly configure it

Security Best Practices

If using Google Sheets:

1. Protect credentials - Keep service account keys private
2. Set permissions - Only share sheets with trusted team members
3. Use dedicated account - Create service account specifically for this
4. Rotate keys - Regularly update service account keys

---

Requirements

Required

• Claude Code CLI - To run the plugin
• jq - JSON parsing (usually pre-installed on macOS/Linux)
  • macOS: brew install jq
  • Linux: apt-get install jq

Optional

• Python 3 - For Google Sheets sync and analytics reports
• gspread, oauth2client - pip3 install gspread oauth2client

---

License

GPL-2.0-or-later - see LICENSE.md file for details.

---

Documentation

Full documentation is available at https://kanopi.github.io/claude-dev-insights/

Support

• Issues: GitHub Issues
• Source Code: GitHub Repository

---

Created and maintained by Kanopi Studios