> 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/workspace-mode-headless-and-multi-repo-agents.md).

# Workspace mode: headless and multi-repo agents

The per-repo flow assumes a session belongs to one checkout. That assumption breaks for headless and autonomous workers, which clone repositories on the fly, work across several of them, and may not have the target repo on disk at all. **Workspace mode** exists for that case: hooks are installed once for the machine, and the repository a session is tracing is bound at runtime.

## Global install

```bash
tracevault init --global                 # ~/.claude/settings.json + ~/.claude/CLAUDE.md
tracevault init --global --agent codex   # ~/.codex/hooks.json  + ~/.codex/AGENTS.md
```

The global install writes hooks once for **all** sessions on the machine, needs no git, and does not create a `.tracevault/config.toml`. Existing hook configuration is deep-merged: the installer appends to what is there and does not clobber it. Two session-level hooks are added: `SessionStart` exports the session ID and injects the bound repo's policies, and `UserPromptSubmit` re-injects them when the session's effective repo changes.

It also enables a **user-level context** at `~/.config/tracevault/context.json`, with `~/.config/tracevault/config.toml` pointing at it. That is the base layer beneath any per-repo context, and it can be populated with no checkout at all, through `tracevault context set --user --flow <id> --label <label> --param <key>=<value>`. Pass `--no-user-context` to skip enabling it, or `--user-context <path>` to read it from somewhere else. See [Context: flows, labels and params](/visdom-tracing/user-guide/context-flows-labels-and-params.md).

## Binding a repo mid-session

```bash
tracevault repo switch <path>            # bind by checkout path, and print the repo's policies
tracevault repo switch --name <project>  # bind by registered name, no checkout required
tracevault repo status [--path <path>]   # show the effective binding and where it came from
tracevault repo reset                    # clear the session's binding
```

Exactly one of `<path>` or `--name` must be given. `--name` is the one that matters for detached workers: it binds a session to a repository that is not cloned locally.

There is a matching `tracevault project` subcommand for binding and inspecting the **project** a detached session is attributed to, which is the level above the repository.

These commands resolve the session from `--session-id` or from the `TRACEVAULT_SESSION_ID` environment variable, which `tracevault init --global` sets.

{% hint style="danger" %}
**Workspace mode never creates a registration.** It resolves an existing one by git remote URL or by name. A repository that was never registered with the server cannot be bound. The fix is registration, not another `switch`.
{% endhint %}

## Precedence and status

High to low: `--path` override → subagent worktree override → session binding from `repo switch` → the bound `.tracevault/config.toml`.

`tracevault status` is mode-aware. On a global install it shows the workspace binding next to the usual checks. Without `--session-id` it uses `$TRACEVAULT_SESSION_ID`, and failing that falls back to the most recent session **that has a workspace binding**, which may well belong to another repo. When the output looks like somebody else's work, that fallback is why; pass `--session-id` to target the one you mean.

{% hint style="info" %}
**Migration note.** Repositories initialised with `--no-user-context` before this feature existed wrote nothing to disk, which is now read as "unset" and inherits the user-level context. To keep such a repo opted out after enabling `init --global`, run `tracevault context source --disable` in it to persist the opt-out explicitly.
{% 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/workspace-mode-headless-and-multi-repo-agents.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.