metrics

Metrics Plugin

Anonymous usage metrics collection for ai-helpers slash commands, skills, and sessions.

Overview

The metrics plugin provides anonymous usage tracking for:

• Events: Individual slash commands and skill invocations
• Sessions: Aggregate session-level metrics (duration, tool usage, conversation patterns)

This helps maintainers understand usage patterns and make data-driven decisions about feature development and improvements.

How It Works

The plugin uses Claude Code's hook system to automatically track usage:

Event Tracking (Slash Commands & Skills)

1. Hook Triggers:
   • UserPromptSubmit: Fires when you submit a prompt that starts with / (slash commands)
   • PreToolUse: Fires when Claude invokes a Skill tool
2. Data Collection: The send_metrics.py script extracts the command/skill name and system information
3. Background Transmission: Events are sent asynchronously to the events endpoint
4. Local Logging: If verbose mode is enabled, all activity is logged to metrics.log

Session Tracking (Session-Level Aggregates)

1. Hook Trigger: SessionEnd fires when your Claude Code session ends
2. Transcript Parsing: The send_session_metrics.py script parses the session transcript file
3. Metrics Extraction: Aggregates are calculated (tool usage, conversation turns, duration, etc.)
4. Background Transmission: Session metrics are sent asynchronously to the sessions endpoint
5. Privacy: Only counts and aggregates are collected - no command arguments, file paths, or message content

Hook Configuration

The plugin is defined in plugins/metrics/hooks/hooks.json:

{
  "description": "Anonymous Usage Metric Collection",
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/send_metrics.py",
            "timeout": 30
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": {
          "tool": "Skill"
        },
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/send_metrics.py",
            "timeout": 30
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/send_session_metrics.py",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

What Data is Collected

The plugin collects two types of anonymous data:

Event Metrics (Slash Commands & Skills)

Collected when you use a slash command or invoke a skill:

Field	Description	Example
type	Metric type	"slash_command" or "skill"
name	The command or skill name	"jira:solve" or "prow-job:prow-job-analyze-install-failure"
engine	Always "claude"	"claude"
version	Plugin version	"1.0"
timestamp	UTC timestamp	"2025-10-30T12:34:56Z"
session_id	Claude session identifier	"abc123..."
user_id	Persistent anonymous UUID	"550e8400-e29b-41d4-a716-446655440000"
os	Operating system	"darwin", "linux", "windows"
mac	SHA256 hash of session_id + timestamp	"a1b2c3..."
prompt_length	Character count of the prompt	42

Privacy Guarantees:

• No command arguments or sensitive data are transmitted
• No personal identifying information (PII) is collected
• Session IDs are ephemeral and rotate between Claude sessions
• A persistent anonymous UUID is stored locally in .anonymous_id, used only to correlate events across sessions
• The user_id contains no PII and can be regenerated/cleared by deleting the .anonymous_id file
• The user_id is treated as anonymous for analytics and integrity purposes
• The MAC is used for data integrity verification only

Example payloads:

Slash command:

{
  "type": "slash_command",
  "name": "jira:solve",
  "engine": "claude",
  "version": "1.0",
  "timestamp": "2025-10-30T12:34:56Z",
  "session_id": "abc123...",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "os": "darwin",
  "mac": "a1b2c3...",
  "prompt_length": 42
}

Skill invocation:

{
  "type": "skill",
  "name": "prow-job:prow-job-analyze-install-failure",
  "engine": "claude",
  "version": "1.0",
  "timestamp": "2025-10-30T12:34:56Z",
  "session_id": "abc123...",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "os": "darwin",
  "mac": "a1b2c3...",
  "prompt_length": 0
}

Session Metrics (Session-Level Aggregates)

Collected when your Claude Code session ends: