How to Monitor Claude Code Sessions, Tool Calls, and Token Usage
Something interesting happens when an engineering org adopts Claude Code seriously: a meaningful share of engineering work starts being performed by an agent that reads files, edits code, runs terminal commands, spawns subagents, and consumes tokens at a rate that varies by 10x or more between sessions doing apparently similar work. Then the first real invoice arrives, and an engineering leader asks a completely reasonable question — what did we get for this? — and discovers that no existing tool can answer it.
The data is scattered by design. Terminal logs show commands but not why the agent ran them. Git history shows the diff but not the forty-minute session behind it. Provider billing shows total spend with no notion of a session, a repo, or a team. The interesting questions all live in the joins: which sessions are expensive and why, where agents loop or stall, which repos and task types drive spend, and whether the expensive sessions are the productive ones or the pathological ones.
The anatomy of an expensive session
Treat a Claude Code session the way you'd treat any production agent run: as a trace. One coding task produces a structured tree of model calls, tool calls (file reads, edits, searches), terminal commands, subagent handoffs, and retries — each consuming tokens, each carrying context about what the agent was trying to do.
flowchart TD
S["<b>Session</b><br/>one coding task<br/><i>user · repo · model</i>"]
S --> M["model calls<br/><i>context growth</i>"]
S --> TC["tool calls<br/><i>read · edit · grep</i>"]
S --> TERM["terminal commands<br/><i>tests · builds</i>"]
S --> SUB["subagent<br/>handoffs"]
M --> OUT["<b>tokens + cost + outcome</b><br/><i>the explainable session</i>"]
TC --> OUT
TERM --> OUT
SUB --> OUT
style S stroke:#f4ae30,stroke-width:2px
style OUT stroke:#59ca6f,stroke-width:2pxOnce you see sessions this way, the cost question stops being mysterious, because expensive sessions have signatures. There's the exploration spiral: an agent repeatedly greps and reads through an unfamiliar codebase, growing its context window with every file until each subsequent model call carries the accumulated weight. There's the test-fix loop: run tests, read failures, edit, run tests again — productive at three iterations, pathological at fifteen. There's the oversized read that pulls a giant file into context and pays for it on every turn thereafter. And there's the session that quietly escalated to a more expensive model and never came back.
A session that costs five times the median is almost always exhibiting one of these patterns, and each has a different fix — better context hygiene, a subagent boundary, a tighter tool policy, a model routing rule. But you can only tell which fix applies if you can see the session's actual shape. Total spend per seat tells you nothing; the same dollar amount can be one productive marathon or thirty tiny failures.
What to capture, and what it unlocks
The instrumentation that makes sessions explainable is a session ID grouping everything one task did, user and repo attribution, the full tool-call and terminal-command record, token usage per step, model changes mid-session, subagent handoffs, and the resulting edits. In AnoSys, the Claude Code integration captures this as a connected operational view — session traces alongside cost, tool patterns, and quality context — rather than as another silo.
That connected view is what lets an engineering lead ask questions that are currently unanswerable in most orgs:
Which Claude Code sessions used the most tokens this week, and were they tied to failed tests or repeated tool calls?
AnoSys can walk the token spike back to the session timeline, the tool usage pattern, the repo, and the outcome. That turns anecdotes ("Claude was really burning tokens yesterday") into findings ("the top-decile sessions are all in the payments repo, all hit the test-fix loop, and most started after the flaky integration suite came back — fix the suite and the spend follows").
It also elevates the conversation past cost. Sessions that loop are signals about your codebase — missing docs, confusing structure, flaky tests — surfaced by an agent that explores it all day. Teams that monitor coding agents well end up using the telemetry to improve the environment the agents work in, which is where the durable wins are.
Patterns worth separating
Claude Code spend is not one problem. The session timeline usually reveals one of several patterns, and each has a different response.
| Pattern | What it looks like | Useful response |
|---|---|---|
| Exploration spiral | many reads and searches before any edit | add repo maps, docs, narrower task prompts, or preloaded context |
| Test-fix loop | repeated terminal runs with small edits between them | isolate flaky tests, improve failure messages, add deterministic local checks |
| Oversized context | one large file or transcript inflates every later call | split files, summarize artifacts, or exclude generated output |
| Tool permission friction | repeated failed commands or denied operations | fix environment setup and permissions before blaming the model |
| Model escalation drift | sessions move to a larger model without better outcomes | define routing rules and review high-cost escalations |
This is where monitoring becomes engineering leverage. A weekly review of the worst sessions should not end with "Claude is expensive." It should produce backlog items: document this repo boundary, fix this test harness, split this generated file, reduce this prompt, or change this model route.
Getting started is deliberately boring — two commands:
The installer registers a native Claude Code Stop hook: when a session ends, the hook scans the transcript and ships the session data to your AnoSys workspace. It prompts for your ingestion API key (Console → API tab), an optional OTEL key for standard traces alongside the hook data, and an optional content redaction mode that replaces all prompt and response text with REDACTED while keeping metadata and token counts — useful if your governance team wants usage telemetry without conversation content. A npx anosys-sdk-claude-code install variant exists for Node shops, and both support headless flags for rolling out via dotfiles or CI.
From there: build the dashboards for token usage, tool patterns, duration, and failures; alert on user-visible or workflow-impacting signals — failed sessions, test loops, latency spikes, error-rate changes, and abnormal token cost per completed task — and review model escalation patterns by team and repo monthly. The patterns will tell you where to invest.
Explore Claude Code Observability, the AI Cost Intelligence product, and the Claude Code documentation.
Create a free account or schedule a demo.
Related solution: AI Agent Debugging.