Beginner Guide

You just started using Claude Code and want to make sure you're not burning tokens unnecessarily. This guide gets you from zero to your first diagnosis.

What Are Tokens and Why Do They Matter?

Every interaction with Claude Code consumes tokens — small units of text that the model reads and generates. Tokens are consumed in four categories:

Input tokens — The context Claude reads each turn (your code, conversation history, CLAUDE.md)
Cache read tokens — Input that was already cached from a previous turn (10x cheaper than fresh input)
Cache creation tokens — New input being written to cache for the first time (1.25x the input price)
Output tokens — Claude's response text and tool calls

Even on a Claude Max subscription where you're not billed per token, tokens matter because they determine how much work you can do in a given time window. Inefficient sessions consume your rate limit faster, leading to throttling. On API billing, inefficient sessions cost real money.

Install AgentSight

One command:

brew tap RealNerd/agentsight && brew install agentsight

Or if you prefer Cargo:

cargo install agentsight

Verify it works:

$ agentsight health --quick

 ── Environment ────────────────────────────────────
 Claude dir:  ~/.claude  (found)
 Sessions:    47 sessions across 8 projects
 Config:      ~/.agentsight/config.toml (default)

Install the Slash Command Skill

AgentSight ships with a /agentsight-diagnose slash command for Claude Code, but it's not set up automatically. You need to install it as a separate step after installing the CLI:

agentsight install-skill agentsight-diagnose

This writes a skill file to ~/.claude/commands/agentsight-diagnose.md, which is where Claude Code looks for slash commands. The skill is embedded in the binary — no network fetch, no extra dependencies. You only need to run this once.

The Simplest Workflow

You don't even need to learn AgentSight's commands. Once the skill is installed, tell Claude Code to do it for you:

Open Claude Code in your project
Type: /agentsight-diagnose

Claude Code will run AgentSight, analyze your most recent session, read your project's CLAUDE.md, and suggest specific improvements. It handles everything — you just approve or reject the changes.

Running Diagnose Manually

If you prefer to see the output yourself:

$ agentsight diagnose

 ── Diagnose: my-project ──────────────────────────────────
 Project:  work/my-project
 Tokens:   318,293 across 17 turns (35m)
 Cache:    70.6% hit ratio
 Cost:     $4.31

 ── Cache Stability ───────────────────────────────────────
 Classification: STABLE
 Cache front-loading looks healthy.

 ── Context Growth ────────────────────────────────────────
 Context size remained stable across the session.

 ── Tool Patterns ─────────────────────────────────────────
 No concerning tool patterns detected.

 ── Recommendations ───────────────────────────────────────
 Your session looks efficient. No changes needed.

What to Look For

The diagnose output flags problems automatically, but here's what the key indicators mean:

Cache hit ratio: Above 60% is good. Below 40% means your context is changing too much between turns (cache churning).
Cache Stability: CHURNING or DEGRADING: Your CLAUDE.md or project structure may be causing the model to rebuild context every turn. The Intermediate Guide covers fixes.
Bash retry loops: AgentSight detects when Claude Code runs the same command repeatedly or hits the same error multiple times. This is a sign your CLAUDE.md is missing setup instructions.
Exploration flagged: Too many Read/Grep/Glob calls relative to Edit/Write calls. Claude Code is spending too long searching and not enough time making changes. Better CLAUDE.md context helps.

Build the Habit

Run /agentsight-diagnose once a week in each active project. It only reads your most recent session, so it stays relevant. Over time, you'll see your cache hit ratios climb and your token usage drop as your CLAUDE.md gets dialed in.