Intermediate Guide

You're comfortable with Claude Code and want to understand what AgentSight is measuring so you can systematically optimize your workflow.

The /agentsight-diagnose Slash Command

If you haven't installed the skill yet:

agentsight install-skill agentsight-diagnose

This installs a skill file to ~/.claude/commands/agentsight-diagnose.md. When you type /agentsight-diagnose in Claude Code, it:

Runs agentsight diagnose --project <your-project> --json
Parses the JSON output for flagged patterns
Reads your project's CLAUDE.md
Suggests specific edits to fix each detected problem

Use it regularly. Every session is different, and your CLAUDE.md should evolve with your project.

Understanding the Diagnose Output

Cache Stability

The cache stability classification is the single most important metric. It tells you whether Claude Code is reusing context efficiently between turns.

STABLE: Cache hit ratio is healthy. Your CLAUDE.md and project context are well-structured. Most input tokens come from cache reads (cheap) rather than fresh input (expensive).
CHURNING: Cache is being invalidated and rebuilt frequently. Common causes: a CLAUDE.md that's too long or changes often, volatile file contents being read every turn, or tool calls that produce different output each time.
DEGRADING: Cache hit ratio is dropping as the session progresses. This usually means context is growing uncontrollably — more files are being read, conversation history is ballooning, or tool output is accumulating.

Context Growth

AgentSight tracks input token counts across turns. If tokens grow 2x or more from turn 5 onwards, it flags the session. This means the conversation is accumulating context faster than the model can prune it. Solutions:

Keep your CLAUDE.md concise — reference external docs instead of inlining them
Break long tasks into separate sessions
Use /clear when switching to unrelated work within the same project

Tool Patterns

AgentSight detects four problematic tool patterns:

bash_loops: Sequences where Claude Code ran bash commands in a tight loop — often stuck retrying a failing build or test. Fix: add build/test commands and common error resolutions to your CLAUDE.md.
bash_retries (identical_command): The exact same command was run multiple times. Claude Code is expecting a different result without changing anything. Your CLAUDE.md should document environment prerequisites.
same_error retries: Bash outputs contain identical error messages across turns. Claude Code is hitting the same wall repeatedly. Add known issues and their fixes to CLAUDE.md.
exploration_flagged: The ratio of read operations (Read, Grep, Glob) to write operations (Edit, Write) is too high. Claude Code is spending most of its tokens navigating rather than making changes. A better project overview in CLAUDE.md helps it find things faster.
subagent_flagged: Too many Task tool calls spawning subagents. Each subagent creates a new context window, which means duplicated token costs. Consider whether the work could be done in fewer, more focused subagent calls.

Cache Efficiency Deep Dive

Claude Code's prompt caching works by storing a prefix of the input context. When the prefix matches on the next turn, those tokens are read from cache instead of reprocessed. Key things that help cache efficiency:

Stable CLAUDE.md — This is typically the first thing in context. If it doesn't change between turns, it stays cached.
Consistent tool output — If the same files are read in the same order, caching works well.
Shorter conversations — Longer conversations push the cacheable prefix ratio down.

Things that hurt cache efficiency:

Dynamic content in CLAUDE.md — Timestamps, auto-generated sections, or frequently changing TODO lists.
Large file reads mid-conversation — Reading new large files changes the context prefix and invalidates cache.
Switching tasks without /clear — The old conversation history stays in context but is no longer relevant.

Comparing Sessions

The best way to measure improvement is to compare sessions before and after CLAUDE.md changes. Use agentsight sessions to list recent sessions and their cache hit ratios:

$ agentsight sessions --project my-project --sort date

 ── Recent Sessions ──────────────────────────────────────
 #  Slug          Date         Turns  Tokens     Cache
 1  fix-login     May 08 14:00    23  482,103    58.2%
 2  add-tests     May 07 10:30    31  891,244    72.4%
 3  refactor-db   May 06 16:15    18  305,821    81.0%

After updating your CLAUDE.md based on diagnose recommendations, run a similar task and compare. You should see cache hit ratios improve and total token counts drop for equivalent work.

Using Summary for Trends

The summary command aggregates across sessions to show trends over time:

$ agentsight summary --days 7

 ── Last 7 Days ──────────────────────────────────────
 Sessions:            14
 Total tokens:        4,821,392
 Avg tokens/session:  344,385

 ── Cost by Project ──────────────────────────────────
 work/api:         $14.20  (60.7%)
 personal/tools:    $6.81  (29.1%)
 personal/site:     $2.40  (10.2%)

 ── Cache Performance ────────────────────────────────
 Avg cache hit ratio:  68.2%

Run this weekly to track whether your overall efficiency is improving.

Using Timeline for Concurrency

If you run multiple Claude Code sessions simultaneously, timeline shows how they overlap and whether concurrency hurts your cache efficiency:

$ agentsight timeline

 13:00  14:00  15:00  16:00  17:00
 my-project   ████████████████████████████████████
 side-task         ██████████    ████████
 docs                        ████████████████████

 ── Concurrency ────────────────────────────────────
 Peak concurrent sessions:     3
 Avg concurrent sessions:      1.8

High concurrency with dropping cache efficiency means your sessions are competing for the model's attention. Consider staggering work or reducing parallel sessions.