Start with a phase budget, not a single latency number
The Overview and timeline are useful because they let you ask where the run spent time before deciding why. Record one representative task, note total duration and token use, then locate long model calls, tool phases, subprocesses, and idle-looking gaps. A large model span suggests a different optimization path from a long compiler, test runner, package manager, or shell command. The first goal is attribution: identify which phase owns the budget.
Distinguish semantic latency from system latency
Native agent telemetry can already describe model requests, tool choices, and permission delays for some agents. System observation answers a different question: what executed after the tool decision and how long that execution lasted. Correlating the two prevents a common mistake where a slow tool is blamed on the model even though most wall time sits in a child process, or where a fast command hides a model retry loop that consumed most tokens.
Repeated work is often more actionable than the single slowest span
Look for repeated repository scans, identical commands, failed retries, repeated dependency checks, or model calls that revisit the same task phase. One 20-second command may be necessary; twenty 2-second scans may be the real avoidable cost. The process tree and timeline make repetition visible, while the tokens and time projections in agentpprof aggregate similar semantic paths so repeated work becomes wide rather than disappearing into a long event list.
Use CPU, memory, and I/O shape to classify child-process phases
A busy compiler or test runner has a different resource signature from an agent waiting on a remote API. Compare the resource view with the same timestamps in the timeline. Sustained CPU with a stable process tree points toward local compute. Memory growth can indicate a large build, browser, language server, or data-processing child. Low CPU during a long network-associated phase suggests waiting rather than local execution. These are hypotheses to test, not automatic diagnoses.
Use semantic flamegraphs when the question spans many sessions
A single timeline is best for one run. Agent Flamegraphs become useful when the question is aggregate: which task categories consumed tokens, where wall-clock time accumulated, which paths were touched, or which domains were contacted across many sessions. The current agentpprof stack is task → skill → phase → action → object → repeat → result → outcome, with width selected by tokens, time, operation count, files, or network effects.
Turn each observation into a falsifiable next experiment
If the profile is model-heavy, change prompt, context, model, or tool policy and re-run the same task. If repeated scans dominate, narrow retrieval or working-set scope. If a child command dominates, profile or optimize that command directly. If network waits dominate, inspect the destination and retry pattern. Keep the task and environment stable enough that the before/after comparison means something; AgentSight shows observed activity, not proof of causality by itself.
$ sudo agentsight record -- claude
$ agentsight report serve
$ agentsight report token
$ agentpprof --view time -o time.svg