> 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/setting-up-tracevault-in-a-repository.md).

# Setting up a repository

`tracevault init` wires Visdom AI Tracing into one repository. It installs the AI-agent hooks that capture sessions, adds two git hooks, creates `.tracevault/`, and registers the repository with the server.

Run it once per repository, from the primary checkout. Do not run it from a linked git worktree.

```bash
tracevault init --server-url https://your-tracevault-server.example.com
```

What gets installed:

* **agent hooks**: a capture hook on every tool event, a `SessionStart` hook that exports the session ID and injects the repo's policies, and a `UserPromptSubmit` hook that re-injects them when the session's effective repo changes
* `.git/hooks/pre-push`: runs `tracevault check`, the policy gate described in [Policies and the pre-push check](/visdom-tracing/user-guide/policies-and-the-pre-push-check.md)
* `.git/hooks/post-commit`: pushes commit metadata (SHA, branch, author, message, diff) to the server, which is what makes line-level attribution possible
* `.tracevault/`: `config.toml`, per-session state, and the context files described in [Context: flows, labels and params](/visdom-tracing/user-guide/context-flows-labels-and-params.md)

A repository shows up in the server's repository list once `init` has registered it, and that is where its policies and its per-repository settings live.

![The repository list: everything registered with the server, with its tracing status](https://2686717926-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2dUajTQaSdFnN24ip7Qo%2Fuploads%2FdAgQIm0XvNbyCCGNsuDx%2Frepositories.png?alt=media)

## Choosing the agent: `--agent`

Visdom AI Tracing captures sessions from more than one coding agent. `--agent` selects which one to install hooks for; the default is `claude-code`.

| Command                            | Installs                      | For                                   |
| ---------------------------------- | ----------------------------- | ------------------------------------- |
| `tracevault init`                  | `.claude/settings.json` hooks | Claude Code (default)                 |
| `tracevault init --agent codex`    | `.codex/hooks.json` hooks     | OpenAI Codex CLI                      |
| `tracevault init --agent gsd`      | the agent's own hook config   | GSD, on the pi coding-agent framework |
| `tracevault init --agent opencode` | the bundled OpenCode plugin   | OpenCode                              |

All of them wire up the same capture pipeline. The agent's hooks invoke `tracevault`, which streams the session (transcript, tokens, cost, file changes) to the server tagged with the agent, so Claude Code and Codex sessions appear side by side, each with its own badge. One difference is worth knowing: Codex file changes are read from the session rollout (`apply_patch`) rather than from typed tool events.

## Where the Claude Code hooks land: `--claude-settings`

`--claude-settings shared` writes `.claude/settings.json`, which is normally committed, so the whole team is traced. `--claude-settings local` writes `.claude/settings.local.json`, which is git-ignored and personal. Omit the flag and the CLI prompts when stdin is a TTY, otherwise it defaults to `shared`.

The flag applies only to `--agent claude-code`. With `--agent codex` it is rejected: Codex always writes `.codex/hooks.json`.

`--no-gitignore` skips updating `.gitignore`. Use it when the project manages `.gitignore` separately, or when you deliberately want to commit the Claude settings files.

{% hint style="info" %}
`tracevault init --global` installs hooks once for **every** session on the machine, rather than for one repository, and pairs with binding a repo mid-session. That mode is for headless and multi-repo agents, see [Workspace mode](/visdom-tracing/user-guide/workspace-mode-headless-and-multi-repo-agents.md).
{% endhint %}

## Checking and repairing the wiring

* `tracevault status`: shows the session's tracing status. It is mode-aware: on a global install it also shows the workspace binding.
* `tracevault sync`: syncs the repository's git remote URL with the server. Run it after the remote changes, because workspace mode resolves repositories by remote URL.
* `tracevault flush`: re-sends events that failed to stream live. Nothing is lost when the network drops mid-session; it queues locally and goes up on the next flush.
* `tracevault stats`: local session statistics, read from disk without asking the server.


---

# 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/setting-up-tracevault-in-a-repository.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.