> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hud.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# File tracking

> How HUD records workspace changes and rebuilds any file at any point in a trace.

**File tracking** records how an agent changes a workspace during a trace. HUD combines the
deployed build source, setup changes, and agent edits so the trace viewer can reconstruct a file at
the point where each action occurred.

File tracking is enabled by default for workspaces created with `env.workspace(...)`:

```python theme={"dark"}
workspace = env.workspace("./workspace")
```

Disable it for a workspace that should not emit file metadata or diffs:

```python theme={"dark"}
workspace = env.workspace("./workspace", track_files=False)
```

## What HUD records

The tracker separates environment setup from agent work:

```mermaid theme={"dark"}
flowchart LR
    S["Build source"] --> P["Post-setup snapshot"]
    P --> D1["Agent change 1"]
    D1 --> D2["Agent change 2"]
    D2 --> F["Final artifacts"]
```

| Record              | Purpose                                                                  |
| ------------------- | ------------------------------------------------------------------------ |
| **Build source**    | The immutable files uploaded for the environment build.                  |
| **Setup changes**   | Files created or modified by task setup before the agent begins.         |
| **Snapshot**        | The post-setup path and content-hash baseline.                           |
| **Agent changes**   | Added, modified, or deleted files sampled during the rollout.            |
| **Final artifacts** | Eligible changed documents and images preserved for preview or download. |

The snapshot contains file identity and hashes, not a second copy of every file. The viewer starts
from the build source, applies setup patches, then applies agent patches in event order.

## Read files in a trace

Use **Source** to inspect the original deployed build. Use **Workspace** to inspect the reconstructed
state at a selected point in the trajectory. Selecting a file shows its diff and the steps that
changed it.

The code review view summarizes the final set of agent changes. A changed binary or large file can
appear without an inline text diff; eligible final artifacts remain available as downloads.

## Exclusions and redaction

HUD excludes common noise such as `node_modules`, virtual environments, caches, version-control
metadata, and compiled objects. It also honors supported patterns from the workspace root
`.gitignore`.

`.env` files, private keys, cloud credentials, and SSH configuration are detected as changed, but
their contents never enter trace telemetry.

<Note>
  Large scans and diffs are bounded. When a change exceeds a file or payload limit, the trace records
  that the file changed and marks the result as truncated instead of attempting an unbounded diff.
</Note>

## Global controls

The environment variable `HUD_FILE_TRACKING_ENABLED=false` disables the default for every
workspace in the process. An explicit `track_files=True` or `track_files=False` on
`env.workspace(...)` takes precedence for that workspace.

The `HUD_FILE_TRACKING_INTERVAL` setting controls the number of seconds between change snapshots.
The default interval is two seconds.

For the rest of the trace inspection workflow, see [evaluations](/platform/evaluations).