Skip to content

README.md

Latest commit

 

History

History
169 lines (122 loc) · 6.63 KB

README.md

File metadata and controls

169 lines (122 loc) · 6.63 KB

Agent Session Analytics

MCP server and CLI for queryable analytics on Claude Code session logs.

Related: agent-event-bus shares design patterns with this project.

What It Does

Parses your Claude Code session logs (~/.claude/projects/**/*.jsonl) and provides:

  • Tool frequency - Which tools you use most (Read, Edit, Bash, Grep, etc.)
  • Command breakdown - Bash command patterns (git, make, cargo, npm, etc.)
  • Workflow sequences - Common tool chains like Read → Edit → Bash
  • Permission gaps - Commands that should be added to settings.json
  • Token usage - Usage breakdown by day, session, or model
  • Session timeline - Events across conversations with filtering
  • Cross-session insights - Gotchas, patterns, and learnings from event-bus

Data is stored persistently in SQLite and auto-refreshes when stale (>5 min old).

Installation

make install

This will:

  1. Create a virtual environment and install dependencies
  2. Set up a LaunchAgent for auto-start (macOS) or systemd service (Linux)
  3. Add the MCP server to Claude Code
  4. Install the CLI to your path

CLI Usage

# Status & Ingestion
agent-session-analytics-cli status              # Database stats
agent-session-analytics-cli ingest --days 7     # Refresh data from logs

# Core Analytics
agent-session-analytics-cli frequency           # Tool usage (--no-expand to hide breakdowns)
agent-session-analytics-cli commands            # Bash command breakdown (--prefix git)
agent-session-analytics-cli sessions            # Session metadata and tokens
agent-session-analytics-cli tokens --by day     # Token usage (day/session/model)

# Workflow Analysis
agent-session-analytics-cli sequences           # Tool chains (--expand for command-level)
agent-session-analytics-cli permissions         # Commands needing settings.json
agent-session-analytics-cli insights            # Pre-computed patterns for /improve-workflow

# File & Project Activity
agent-session-analytics-cli file-activity       # File reads/edits/writes
agent-session-analytics-cli languages           # Language distribution
agent-session-analytics-cli projects            # Activity by project
agent-session-analytics-cli mcp-usage           # MCP server/tool usage

# Agent Activity
agent-session-analytics-cli agents              # Task subagent activity vs main session

# Session Analysis
agent-session-analytics-cli signals             # Raw session metrics for LLM interpretation
agent-session-analytics-cli classify            # Categorize sessions (debug/dev/research)
agent-session-analytics-cli failures            # Error patterns and rework detection
agent-session-analytics-cli error-details       # Detailed errors with tool parameters
agent-session-analytics-cli trends              # Compare usage across time periods
agent-session-analytics-cli handoff             # Context summary for session handoff

# User Messages
agent-session-analytics-cli journey             # User messages across sessions
agent-session-analytics-cli search <query>      # Full-text search on messages

# Session Relationships
agent-session-analytics-cli parallel            # Find simultaneously active sessions
agent-session-analytics-cli related <id>        # Find sessions with similar patterns

# Git Integration
agent-session-analytics-cli git-ingest          # Import git commit history
agent-session-analytics-cli git-correlate       # Link commits to sessions
agent-session-analytics-cli session-commits     # Show commits per session

# Event-Bus Integration
agent-session-analytics-cli bus-events          # Query cross-session events (gotchas, patterns)

# Pattern Inspection
agent-session-analytics-cli sample-sequences    # Sample instances of a pattern with context

# Performance
agent-session-analytics-cli benchmark           # Benchmark all MCP tool response times

All commands support:

  • --json for machine-readable output
  • --days N to specify time range (default: 7)
  • --project PATH to filter by project

MCP Tools

31 tools available when running as an MCP server:

Category Tools
Status get_status, ingest_logs
Analytics get_tool_frequency, get_command_frequency, get_session_events, list_sessions, get_token_usage
Patterns get_tool_sequences, sample_sequences, get_permission_gaps, get_insights
Files get_file_activity, get_languages, get_projects, get_mcp_usage
Agents get_agent_activity
Sessions get_session_signals, classify_sessions, analyze_failures, get_error_details, analyze_trends, get_handoff_context
Messages get_session_messages, search_messages
Relationships detect_parallel_sessions, find_related_sessions
Git ingest_git_history, correlate_git_with_sessions, get_session_commits
Event-Bus ingest_bus_events, get_bus_events

For detailed usage, read the MCP resource agent-session-analytics://guide or see guide.md.

Development

# Install dev dependencies
make dev

# Run in dev mode with auto-reload
./scripts/dev.sh

# Run checks (format, lint, test)
make check

# Run tests only
.venv/bin/pytest tests/ -v

Data Location

  • Database: ~/.claude/contrib/agent-session-analytics/data.db
  • Logs parsed from: ~/.claude/projects/**/*.jsonl
  • Event-bus source: ~/.claude/contrib/agent-event-bus/data.db (if agent-event-bus is installed)

How It Works

  1. Ingestion: Parses JSONL session logs incrementally (tracks file mtime/size)
  2. Storage: SQLite database with events, sessions, and patterns tables
  3. Auto-refresh: Queries detect stale data (>5 min) and trigger re-ingestion
  4. Patterns: Pre-computes tool sequences and permission gaps for fast queries

See docs/SCHEMA.md for detailed database schema documentation.

Architecture

Key patterns used in the codebase:

  • Public Storage API: Use storage.execute_query() for reads, execute_write() for writes
  • Query Helpers: build_where_clause() reduces duplication across query functions
  • Formatter Registry: CLI uses @_register_formatter(predicate) for extensible output formatting
  • Schema Migrations: @migration(version, name) decorator for future DB schema changes

See CLAUDE.md for more details on contributing.

Related

Uninstall

make uninstall

License

MIT