> For the complete documentation index, see [llms.txt](https://docs.visdom.virtuslab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.visdom.virtuslab.com/visdom-tracing/user-guide/what-a-session-captures.md).

# What a session captures

The unit of capture is a **session**, one run of the coding agent. Within a session the CLI streams five kinds of event, defined in the shared wire-protocol crate so the CLI and the server depend on one source of truth:

* `session_start` and `session_end`: the boundaries, with the final statistics attached to the end
* `tool_use`: one per tool call: tool name, tool-use ID, the input, the response, and whether it errored
* `transcript`: the conversation itself, streamed in lines with an offset so a long session is sent incrementally rather than re-sent whole
* `verification_phase_start`: a marker the agent (or you) can set to declare that changes are finished and quality checks have begun

Every event carries the session ID, a timestamp, the model, the working directory, and the [context](/visdom-tracing/user-guide/context-flows-labels-and-params.md) in force at that moment: the flow ID, labels and params. That last part is what makes the analytics views useful: without a flow ID every session is an island, with one you can group everything an agent did across several repositories under a single piece of work.

Ordering uses a client-minted **UUIDv7**, stamped when the hook fires. Because UUIDv7 is time-ordered, events sort correctly even when they arrive out of order or late from a flush. Older clients sent a per-session counter instead; the server still accepts it as a fallback.

In the UI the same stream is a session: the tool calls in order, the model, the cost, and the files touched.

![A captured session in the trace view](https://2686717926-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2dUajTQaSdFnN24ip7Qo%2Fuploads%2FLAsTVo1x7X8yp1Va4VVe%2Ftraces.png?alt=media)

The transcript is kept alongside it, so a reviewer can read what the agent was actually told and what it answered.

![The transcript of a session, turn by turn](https://2686717926-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2dUajTQaSdFnN24ip7Qo%2Fuploads%2Fy0vP6kTQGtvwviNzYCFT%2Ftraces-transcript.png?alt=media)

## Session statistics

`session_end` carries the numbers the cost views are built from: duration, total / input / output tokens, cache-read and cache-write tokens, user and assistant message counts, and total tool calls. Cache tokens are reported separately rather than folded into the input count, which is what makes a cache hit-rate meaningful instead of a guess.

## Commits and attribution

The post-commit hook sends the commit SHA, branch, author, message, commit time and diff. The server answers with how many **attributions** it created for that commit: the link between lines in the commit and the agent events that produced them. This is the mechanism behind line-level AI attribution overlaid on git history; the diff-side extraction records, per file, the change type, the diff text and a content hash.

On the capture side the tools treated as file-modifying are `Write`, `Edit` and `Bash`. For Codex, file changes come from the session rollout (`apply_patch`) instead of from typed tool events.

{% hint style="success" %}
**Very large events are trimmed, not dropped.** Before sending, the CLI drops optional fields largest-first until the payload is under 512 KB, so a huge tool response or transcript chunk does not fail the send with a 413. The event still arrives; some of its bulkier fields will be missing.
{% endhint %}

## What happens on the server, not in the CLI

Signing, hash-chaining and secret redaction are server-side. The CLI's job ends at streaming the event; the ledger properties that make a trace evidence (the Ed25519 signature and the hash chain that makes tampering detectable) are applied when the server seals the session. Redaction of secrets in captured tool calls is configured there too, so what a developer sees leaving the machine and what is stored are not necessarily the same payload.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.visdom.virtuslab.com/visdom-tracing/user-guide/what-a-session-captures.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.