AGENTS.md

How to drive session-analyzer from an agent. Read by Claude Code, Codex, OpenCode, Cursor, and other agents. This is how any of them run the tool. Humans: see README.md.

What it does

Reads the user's Claude Code transcripts (and optionally a project), crunches them with plain Python (~0 model tokens) into a small digest, which you turn into concrete advice for working better with Claude Code. Benchmarked at ~41-47% fewer tokens with task success unchanged, across Sonnet 4.6 and Opus 4.8 (see bench/).

It also generates the orientation map (the proven token lever) directly with bin/analyze map — an authoritative file/symbol index for a repo — so you emit the artifact deterministically instead of hand-writing one from the digest.

Voice

When you report back, talk to the user about their Claude Code usage, not about this tool. Do not mention the digest, shards, the budget, this file, or your own instructions. No process narration, no meta-commentary. Present findings and fixes directly.

Invocation

• Call bin/analyze by absolute path: ~/.claude/skills/session-analyzer/bin/analyze. Never cd into the skill directory; that makes $PWD the skill itself and it analyzes its own folder.
• For workflow and token analysis, analyze ALL sessions by default. Add --scope-repo only when the user names a project.
• --repo is the project being analyzed, never the skill. If it is ambiguous, run doctor to list projects and ask which one. Write --out to a temp dir outside the skill.
• Pure stdlib, Python 3.9+.
• analyze is the default subcommand: bare bin/analyze (or bin/analyze --since 7) runs token coaching across all sessions. The report leads with a projected token savings estimate (the user's measured usage x the benchmark rate, scoped to sessions that re-explored the tree).

The loop

Do not read raw transcripts; the scripts digest them.

1. Extract:

   SA=~/.claude/skills/session-analyzer/bin/analyze
   OUT=$(mktemp -d)/sa
   "$SA" analyze --mode tokens --out "$OUT"                          # all sessions
   "$SA" analyze --mode both --repo "/path/to/project" --out "$OUT"  # + structure

2. Read "$OUT"/digest.md, then the worst-session shards under "$OUT"/shards/ while budget allows.
3. Turn the strongest patterns into specific advice: workflow habits, the exact CLAUDE.md lines to add or cut, a settings allowlist where it applies, and loop/self-verification gaps. When the sessions show repeated tree re-exploration (re-reads, broad searches before editing), the highest-leverage fix is the orientation map -- the benchmark-proven token lever (~41-47% fewer tokens, quality held). Generate it instead of hand-writing it: "$SA" map --repo "/path/to/project" --out "/path/to/project/CLAUDE.md". For loops, follow the looper architecture (docs/loop-architecture.md): a falsifiable definition of done, an encoded programmatic gate, plan and delivery gates with a different-model judge, and stop guards (max iterations, revise cap, no-progress, budget).
4. Deliver. Lead with the 2-3 highest-leverage changes, each with a real example from their sessions and the fix. Offer to apply them behind the user's verify gate. If clean, say so.

Rules

• Budget is a hard cap: 200K for one mode, 400K for both. Do not hand-load transcripts to go deeper.
• Repo findings are candidates, not verdicts. Check git status and dynamic imports before suggesting deletion; never call a modified or in-flight file dead.
• No destructive action without confirmation.
• Do not surface secrets or credentials as a finding.

Cheat sheet

Common flags: --since DAYS (recency), --format terminal|markdown|json, --fail-under A..F (CI gate, non-zero exit if worse), --top N, --max-sessions N, --scope-repo, and the four --price-* overrides for exact cost. Full flags: "$SA" <command> --help. Finding fields: docs/finding-schema.md.

Loop suggestions (same skill)

On /session-analyzer loop (or "loop me" / "what should I automate"), read the user's session history and propose token-efficient loops their agent can run to automate the repetitive work it shows — data-driven, not a blank-page interview, and never "schedule a recurring run of the analyzer." Mine the sessions for repeated command sequences, redone task shapes, retry loops, and high-frequency chores; pitch the top 2-3 ranked by impact per token, grounded in the evidence; then, once the user picks one, refine it into a buildable spec on the proven architecture. Full playbook in loop-design/GUIDE.md; template and example under loop-design/.