Waterfall

Waterfall shows what happened in a session, turn by turn, on a timeline: each call to the model, each tool the agent ran and each subagent, how long each took, and what went in and out. Use it to see where time went, why a turn was slow, or what the agent actually did.

Opening itCopy Anchor Link

• The Waterfall button at the top of the Andromity chat.
• The command Waterfall Trace (andromity.openWaterfall) from the Command Palette.
• The editor title-bar button while the agent is running.

Each session has its own Waterfall tab. By default it opens on its own when a session's first prompt starts; turn this off with the VS Code setting andromity.waterfallAutoOpen or in Andromity Hub (Preferences → Live Waterfall Auto-Open).

HeaderCopy Anchor Link

Buttons: Guide (a glossary of the terms on this page), Docs (this page), Fingerprint (opens Fingerprint for the same session), Auto-scroll, Clear (empties this panel's display only; the session is unchanged) and Export JSON (saves every turn and span with its timings, arguments, results and the log).

TimelineCopy Anchor Link

Each turn is a group headed by its prompt, token count and duration; click the header to collapse it. Every row inside is a span:

A bar's position shows when the span started within its turn and its length shows how long it took. Failed spans are red, cancelled ones are striped amber and running ones shimmer. On a model call, the lighter part at the start of the bar is the time to first token (TTFB): how long the model took to start answering.

Background processes (shell_bg) stay running on the timeline until the process exits or is stopped.

Span detailsCopy Anchor Link

Click a row to expand it:

• Model calls: model, TTFB, tokens split into prompt (P) and completion (C), speed in tokens per second, the thinking, the response, and the tool calls the model asked for.
• Tool calls: the call ID, the arguments and the result.
• Subagents: role, model, number of steps, the task it was given, each internal tool call with its arguments and result, and its final summary.

Every block has a Copy button.

Filters and searchCopy Anchor Link

Show All, LLM, Tools, Subagents or Errors. The search box filters spans by name; for model calls that is the model name. Filters apply to the Timeline only.

Stream LogCopy Anchor Link

Every event as it arrived, with a timestamp and a tag such as LLM-START, TOOL-END, BG-EXIT, SUBAGENT-DONE, APPROVAL, COMPACT or ERROR.

Stats & ProfilingCopy Anchor Link

• Execution latency breakdown: model time, tool time and total tokens.
• Tool execution profiler: for each tool, how many times it ran, total and average time, and success rate, including tools run inside subagents.
• Subagents: each subagent's model, duration, tools run and status.

Live and past sessionsCopy Anchor Link

When you open Waterfall, it rebuilds the session from its saved history and then follows new activity live. A turn that is still running is replayed from recent events kept in memory.

Past sessions show less detail than live ones, because the saved history does not keep every timing:

• TTFB is a placeholder and per-call token counts and speed are not shown.
• Every model call shows the session's model.
• Tool durations are estimated from timestamps.
• Spans are not marked as errors, so the Errors filter shows nothing.
• Collaboration spans (COORD) are not shown.
• Messages you sent while a turn was running appear as separate turns.

Keep the panel open while you work to capture full timings.