performance

Performance Digest

Measurement layer for Claude Code. Turns session telemetry into prescriptive behavioral rules that Claude reads on the next session start.

A static rule is a wish. A measured rule is a system.

---

What it does

Every seven days, reads all Claude Code session files from the last week and computes:

• Activity distribution: Coding, Exploration, Debugging, Delegation, Planning, Conversation
• One-shot edit rate: percentage of file edits that landed without a retry cycle
• Agent spawn analysis: how many subagents fired and how many turns each took
• Model mix: Opus vs. Sonnet vs. Haiku across all turns
• Project allocation: which codebases consumed the most attention
• Hookify firings: which behavioral guardrails actually triggered

Then runs six diagnostic rules. When a rule fires, one of two things happens:

1. Behavioral prescriptions (verbose agents, model routing, low one-shot rate, exploration overhead) are written directly to ~/.claude/CLAUDE.md as permanent rules Claude reads on future session starts.
2. Investigation prescriptions (recurring errors, hookify repeats) are appended to a Claude To-dos list for the user to review.

Next week the digest re-measures. If the number moved, the rule worked. If it did not, the rule fires again with updated numbers.

---

Setup

Expected vault layout (follows ai-brain-starter conventions):

<vault-root>/
  ⚙️ Meta/
    Performance/            (reports land here)
    Claude To-dos.md        (prescriptions go here)
    scripts/
      claude_performance_digest.py

Copy scripts/claude_performance_digest.py into your vault at the matching path. The script self-locates via __file__ and expects to sit at <vault>/⚙️ Meta/scripts/.

Optional: edit the PROJECT_LABELS dict at the top of the script to map project directory substrings to clean display labels.

Optional: tune the THRESHOLDS dict. Defaults are calibrated for daily power users.

---

Usage

Run manually:

python3 "<vault>/⚙️ Meta/scripts/claude_performance_digest.py"

Or schedule weekly. Examples:

Cron (Monday 1am UTC, adjust offset for your timezone):

0 1 * * 1 /usr/bin/python3 "/path/to/vault/⚙️ Meta/scripts/claude_performance_digest.py"

Or via the scheduled-tasks Claude Code plugin, if installed.

---

Flags

• --days N: lookback window (default 7)
• --dry-run: print report to stdout, do not write files
• --no-report: skip the markdown report, apply prescriptions only

---

What the output looks like

A dated markdown file at ⚙️ Meta/Performance/weekly-YYYY-MM-DD.md:

# Performance Digest: 2026-04-09 to 2026-04-16

**767 sessions** across 3 projects. 20,822 assistant turns. 773 files edited.

## Activity Distribution
| Category     | Turns | %  |
| Coding       | 1392  | 7% |
| Exploration  | 3062  | 15%|
| Debugging    | 2719  | 13%|
| Delegation   | 324   | 2% |
| Planning     | 2292  | 11%|
| Conversation | 13033 | 52%|

## One-Shot Edit Rate
**83%** (773 files edited, 129 required retries) - on target

## Agent Spawns
**324 agents spawned**. Average turns per agent: **22.0**

## Diagnostics
- **VERBOSE AGENTS**: Avg agent turns is 22.0 (target: <5). Review agent
  prompts: add file paths, expected output format, and clear scope.

## Trending
*Baseline week. No prior data for comparison.*

And a behavioral rule written into ~/.claude/CLAUDE.md:

- [VERBOSE AGENTS fix](performance_verbose_agents.md) | Agent briefings must
  include: specific file paths, expected output format, and scope boundary.
  Target: <8 turns per agent. Current avg: 22.0. (updated 2026-04-16)

---

Why this exists

Self-improvement by memory alone has a failure mode: a rule gets written, Claude reads it at session start, and under the wrong context the behavior recurs anyway. Without measurement, you cannot tell whether a correction actually worked. You can only tell that you wrote the rule.

This skill closes the loop. Rules come with a number attached. Baseline, target, check-in. Next week the measurement tells you whether the rule is alive, needs revising, or can retire.

---

Integration

If you use the /weekly skill from claude-insights, the weekly review auto-surfaces the most recent performance digest in its report. The two skills compose: /weekly tells you what happened in your life, /performance tells you what happened in your AI workflow.