metrics — Claude Code command: per-turn report
Turns the log kept by the track-metrics hook into a short report: how many turns ran, which files changed, what got committed.
MIT ★ 1,424 updated 2026-10-06
.claude/commands/metrics.mdWhat metrics does
The command reads .claude/agent-metrics.jsonl, where the track-metrics hook appends one record for every agent reply. From those lines it builds an overview: total turns, turns from the past 7 days, average number of files touched per turn.
Then comes a table of the ten newest turns — UTC timestamp, file count, short commit message. A patterns section follows: which turns touched many files, how often commits appear, how many turns changed nothing at all. It works with Read, Bash and Glob.
The recording belongs to the hook, not to the command. Without track-metrics installed there is no file, and /metrics simply says nothing has been logged yet.
What it helps with
- check how many turns were logged in the past week
- spot turns that changed no files
- see recent commits next to the turns behind them
- measure the average number of files touched per turn
- catch stretches where one turn rewrites a lot
Example prompts for the agent
- Run
/metricsand tell me how many turns landed in the last week. - Use
/metricsto list the ten newest turns with their commits. - Run
/metricsand flag the turns that changed nothing.
How to install metrics
Manually: put the files in place
.claude/commands/metrics.mdCall it with /metrics. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/metrics.mdCall it with /prompts:metrics. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/metrics.prompt.mdManually: put the files in place
.gemini/commands/metrics.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about metrics
How do I install metrics in Claude Code?
Copy the command file to .claude/commands/metrics.md inside your project. Call it afterwards as /metrics.
What does the metrics command do?
It parses .claude/agent-metrics.jsonl, filled by the track-metrics hook, and prints an overview, a table of the ten latest turns and any patterns it notices.
Why does /metrics say nothing has been recorded?
Records come only from the track-metrics hook. Skip it and .claude/agent-metrics.jsonl never exists, so the command has nothing to read.
Source text
metrics.md · MIT
--- allowed-tools: Read, Bash, Glob description: "Summarise the per-turn records written by the track-metrics hook: activity over time, files changed, and latest commits." --- ## Context - Metrics file: !`cat .claude/agent-metrics.jsonl 2>/dev/null || echo "NO_METRICS_FILE"` ## Task Analyze the recorded metrics and present a summary. **If the metrics file does not exist or the context above shows "NO_METRICS_FILE":** Print exactly: "No metrics recorded yet. Metrics are automatically collected after each turn." **If metrics data exists**, parse each JSON line and present: 1. **Overview** - Total turns logged (the hook writes one record each time Claude finishes responding) - Turns in the last 7 days (compare timestamps to now) - Average files changed per turn 2. **Recent Turns** (last 10) Format as a markdown table: | # | Timestamp (UTC) | Files Changed | Commit | | --- | --------------- | ------------- | ------ | - Show the most recent 10 turns, newest first - For "Commit", show the short commit message or "—" if none 3. **Patterns** - Note any trends (e.g., turns with many file changes, frequency of commits) - If there are turns with 0 files changed, note how many were "no-op" turns Keep the output concise and well-formatted.
© CloudAI-X · MIT · CloudAI-X/claude-workflow-v2