Claude Code sessions often feel worse before anyone can explain why. The agent repeats a tool call, forgets a buried rule, re-reads a swollen CLAUDE.md, or hits compaction while still doing the same job. Without session evidence, the usual fix is guesswork: shorten the prompt, blame the model, or add another instruction.
PRISM is a useful article seed because it moves that conversation from vibes to session records. It reads the JSONL files Claude Code already writes under ~/.claude/projects/, then grades token efficiency, tool health, context hygiene, CLAUDE.md adherence, and continuity. The practical question is not whether the dashboard looks nice. It is which CLAUDE.md change is justified by real session evidence.
The source of truth is the session file
The README says PRISM reads Claude Code's local session files from ~/.claude/projects/. The How PRISM Works doc explains the JSONL records: user messages, assistant responses, tool calls, tool results, and system compaction boundaries. That is the important boundary. PRISM should be run after real work, not on a theoretical prompt. If a session had retry loops, migration edits, interactive command hangs, or compaction loss, those traces are in the file. A normal CLAUDE.md review sees only the rules. PRISM sees whether the session behaved like the rules mattered.
Run it read-only first
Start with pip install prism-cc, then run prism analyze. Use prism analyze --project <path> if one repo is the problem, and prism analyze --json if you want to keep the result in a CI note or local report. The README also shows a Claude Code plugin path: /plugin marketplace add jakeefr/prism, /plugin install prism@prism, and /reload-plugins, but the Python package is still required. Keep the first pass read-only. prism advise prints recommendations; prism advise --apply is the step that can write to CLAUDE.md after confirmation.
CLAUDE.md re-read cost is the first suspect
PRISM's strongest diagnostic is the re-read cost. How PRISM Works defines claude_md_reread_tokens as the estimated CLAUDE.md size multiplied by tool call count. That matches the real pain of a long session: a 200-line instruction file is not paid once, it is paid again as tools run. The CLAUDE.md guide adds the editorial rule: put high-priority constraints at the top or bottom, move directory-specific rules into subdirectory CLAUDE.md files, and remove personality notes that Claude Code already gets from its system prompt. Do not rewrite the whole file. Delete or move the lines that PRISM ties to repeated cost.
Tool Health catches process bugs
The Tool Health dimension is useful because it points at process failure, not just prompt size. PRISM detects retry loops, interactive Bash commands that miss non-interactive flags, migration file edits, edit-revert cycles, and runs of consecutive failures. Those are concrete signals for a coding team. If the tool flags npm init hanging without --yes, add or move a rule about non-interactive commands. If it flags migration file edits despite a rule, make that rule shorter, stronger, and closer to the attention edge. The right response is a small rule change tied to a real failure, not another page of general guidance.
Context Hygiene explains the mid-task amnesia
Compaction is not automatically bad. It becomes a clue when a compacted session repeats the same tool pattern after the boundary. The How PRISM Works doc says PRISM looks for compaction records and checks whether tool names after compaction overlap with common tool names before it. That is a reasonable proxy for mid-task context loss. If PRISM flags this, the fix may be session discipline rather than CLAUDE.md edits: split the task earlier, summarize the current plan before a long run, or stop using one session as a dumping ground for unrelated work.
Use agentsview when precision matters
The default PRISM token estimate is len(text) // 4. The docs say this is fast and consistent, but it can undercount code-heavy text. The README notes that PRISM can read an agentsview SQLite database with prism analyze --source agentsview, using ~/.agentsview/sessions.db or a path supplied through --agentsview-db. Treat that as the higher-fidelity path when you are about to make a team policy decision. For one developer cleaning up a noisy CLAUDE.md, the default estimate is enough. For a shared rule set, run the agentsview path before calling a line expensive.
The dashboard is evidence, not the fix
prism dashboard generates a self-contained HTML report, and prism analyze also regenerates ~/.claude/prism/dashboard.html. That report is useful for review because it shows the score dimensions and project issues in one place. It should not become a scoreboard. A C grade is only useful if it points to a specific change: move three React-only rules into src/CLAUDE.md, add a non-interactive command rule, or remove a tone block. If the dashboard does not lead to one concrete diff, keep it as observation and rerun after more session data.
Privacy still matters on local files
The README says PRISM is local and read-only against Claude Code sessions. That is good, but local session files can contain project paths, prompts, tool outputs, errors, and snippets of source. The safe workflow is to run PRISM on your own machine, share only the recommendation or redacted JSON summary, and avoid posting raw dashboard exports from private repos. If you use prism advise --apply, review the diff like any other config change. A diagnostic tool should not silently become the maintainer of your instruction file.
Save PRISM as a Claude Code diagnostics article. Use it to justify small CLAUDE.md edits from real sessions, not to chase a dashboard grade.
Practical takeaway
Install with pip install prism-cc, run prism analyze --project <repo>, read the five score dimensions, then pick one issue with clear evidence. For CLAUDE.md cost, move or remove only the lines PRISM ties to repeated tool-call reads. For tool failures, add one short rule and rerun prism analyze. Use prism advise --apply only after reviewing the proposed diff, and switch to prism analyze --source agentsview when exact token data matters.