Routine Measurement Dashboard

Tracks, visualizes, and reports context window usage, execution duration, tool call breakdown, and cost estimates during routine execution.

When to Use

Primary Use Cases:

1. Auto-Measurement: Invoked AUTOMATICALLY when user includes --measure flag in /popkit:routine commands
2. Dashboard Display: Invoked when user requests viewing existing measurements
3. Trend Analysis: Invoked when comparing measurements across multiple runs

# Auto-measurement during routine execution
/popkit:routine morning --measure
/popkit:routine morning run p-1 --measure
/popkit:routine nightly --measure

# Viewing existing measurements
show routine measurements
show measurements for morning routine
routine performance dashboard

How It Works

1. Detect Flag: Parse command for --measure flag
2. Start Tracking: Enable measurement via environment variable
3. Initialize Tracker: Start RoutineMeasurementTracker
4. Execute Routine: Run the routine normally (pk, p-1, etc.)
5. Stop Tracking: Collect measurement data
6. Format Report: Display detailed breakdown
7. Save Data: Store JSON for analysis

Implementation Pattern

import os
import sys
sys.path.insert(0, "packages/plugin/hooks/utils")

from routine_measurement import (
    RoutineMeasurementTracker,
    enable_measurement,
    disable_measurement,
    format_measurement_report,
    save_measurement
)

# 1. Enable measurement mode
enable_measurement()

# 2. Start tracker
tracker = RoutineMeasurementTracker()
tracker.start(routine_id="p-1", routine_name="PopKit Full Validation")

# 3. Execute routine
# Use Skill tool to invoke the actual routine
# Example: Skill(skill="pop-morning-routine", args="--routine p-1")

# 4. Stop tracker and get measurement
measurement = tracker.stop()

# 5. Disable measurement mode
disable_measurement()

# 6. Display report
if measurement:
    report = format_measurement_report(measurement)
    print(report)

    # Save measurement data
    saved_path = save_measurement(measurement)
    print(f"\nMeasurement data saved to: {saved_path}")

Metrics Collected

See examples/metrics-reference.md for complete metrics documentation.

Key metrics:

• Duration (total execution time)
• Tool calls (count per tool type)
• Token usage (input/output split with ~4 chars/token estimation)
• Cost estimates (Claude Sonnet 4.5 pricing: $3/million input, $15/million output)
• Character counts (raw content length)

Measurement Data

See examples/data-format.md for complete JSON schema.

Measurements saved to .claude/popkit/measurements/{routine_id}_{YYYYMMDD}_{HHMMSS}.json

Key fields:

• routine_id, routine_name: Routine identification
• duration, start_time, end_time: Timing data
• total_tokens, input_tokens, output_tokens: Token counts
• tool_breakdown: Per-tool statistics
• cost_estimate: Estimated API costs

Usage Examples

See examples/usage.md for complete usage scenarios.

Quick examples:

# Measure default morning routine
/popkit:routine morning --measure

# Measure specific routine
/popkit:routine morning run pk --measure

# View dashboard
show routine measurements

Dashboard Visualization (NEW in v1.1.0)

See examples/dashboard-implementation.md for complete Python implementation.

Dashboard features:

• Summary metrics (duration, tokens, cost)
• Token usage breakdown (input/output split with percentages)
• Tool breakdown table (calls, tokens, duration per tool)
• Comparison with previous run (trend indicators)
• Aggregate statistics across multiple runs

View dashboard:

python examples/dashboard-implementation.py
python examples/dashboard-implementation.py --routine morning
python examples/dashboard-implementation.py --all

Integration

See examples/integration.md for detailed integration documentation.

Hook integration:

• post-tool-use.py hook automatically tracks tool calls when POPKIT_ROUTINE_MEASURE=true
• Tracks all tools: Bash, Read, Grep, Write, Edit, Skill, etc.
• Estimates tokens using ~4 chars/token heuristic
• Captures duration from hook execution time

Command integration:

• /popkit:routine command supports --measure flag
• This skill wraps routine execution with measurement tracking
• Results displayed after routine completion

Future Enhancements

See examples/roadmap.md for complete roadmap.

Planned features:

• Phase 2: Comparison mode for side-by-side routine comparison
• Phase 3: Trend analysis with visualization over time periods
• Phase 4: Optimization suggestions based on measurement data
• Phase 5: Token budget alerts and cost tracking

Related Skills

Skill	Purpose
pop-morning-routine	Execute morning routine
pop-nightly-routine	Execute nightly routine
pop-routine-generator	Create custom routines
pop-assessment-performance	Analyze performance metrics

Related Commands

Command	Purpose
/popkit:routine	Execute routines
/popkit:assess performance	Performance assessment
/popkit:stats	Session statistics

Testing

See examples/testing.md for complete testing instructions.

Quick test:

# Enable measurement manually
export POPKIT_ROUTINE_MEASURE=true

# Run a routine
/popkit:routine morning

# Verify measurement file created
ls -la .claude/popkit/measurements/
cat .claude/popkit/measurements/*.json | jq '.'

---

Version: 1.1.0 Author: PopKit Development Team Last Updated: 2025-12-19