> 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.md).

# User Guide

What Visdom AI Tracing captures, how it is wired in, and where to start.

Visdom AI Tracing is a service whose goal is to record and prove **what an AI coding agent did inside a repository**. The scope of what it manages is the **development event stream**: sessions, prompts and transcripts, tool calls, models used, token counts and cost, file changes, and the commits those changes ended up in. On the server side those records are hash-chained and Ed25519-signed, so a change to the history is detectable rather than merely unlikely.

{% hint style="info" %}
Visdom AI Tracing by design **does not** review the change, run its tests, or decide whether the code is good. It records how the change was produced and enforces the rules the organisation set for producing it. Judging the change itself belongs to Code Review and Testing.
{% endhint %}

Capture happens through **hooks, not a proxy**. `tracevault init` installs the coding agent's own hooks (`.claude/settings.json` for Claude Code, `.codex/hooks.json` for the Codex CLI) plus two git hooks. From then on there is nothing to remember: the agent fires its hooks, the CLI streams events as they happen, and git pushes commit metadata after every commit.

On top of that stream sit three interaction points a developer actually notices:

* **policy injection**: at session start, and again whenever the effective repo changes, the repo's active policies are injected into the agent's context, so the agent's behaviour matches what the server will later enforce
* `tracevault check`: runs from the pre-push git hook, evaluates unpushed sessions against the policies, and can block the push
* `tracevault verify`: run in CI (a ready-made GitHub Action ships with the CLI), fails the build when commits in a range have no sealed trace on the server

Everything is scoped to a **repository registered with the server**. Registration happens through `tracevault init` or up front by an administrator; workspace mode resolves an existing registration by git remote URL or by name, it never creates one.

* CLI: `brew install VirtusLab/visdom-ai-tracing/tracevault` or `cargo install tracevault-cli`
* Source: [VirtusLab/visdom-ai-tracing-cli](https://github.com/VirtusLab/visdom-ai-tracing-cli) (Apache-2.0)
* Product site: [tracevault.dev](https://tracevault.dev/)

{% hint style="info" %}
**Recommended setup**: sign in against your organisation's server, run `tracevault init` in one repository, do a normal agent session and look at what the session captured. Add policies only after you can see the stream. A blocked push is a bad first impression of a tool nobody has watched work yet. Put verification in CI last, once traces are reliably sealed.
{% endhint %}


---

# 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.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.