Skip to main content
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(...):
Disable it for a workspace that should not emit file metadata or diffs:

​
What HUD records

The tracker separates environment setup from agent work: 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.
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.

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