Worktree
[worktree] says what goes into the conversation's worktree, the copy of your
project the model works in, and what is linked to your tree instead.
[worktree]
link = ["node_modules", ".venv"]
max_file_size = "10MB"
shared_target = true
| Key | Meaning | Default |
|---|---|---|
link | Paths symlinked from your tree into each worktree rather than copied, and excluded from the snapshot whether or not your repository ignores them. Never diffed, never reviewed. User and project lists concatenate. | none |
max_file_size | Files above this size are symlinked rather than copied, so the model's tools can still read them, and are never diffed or reviewed. Written as 10MB, 512KB, 1G, or a number of bytes. | 10MB |
shared_target | Set CARGO_TARGET_DIR, for model commands and turn- and commit-time gates, to one directory per project under heph's data directory, shared across all worktrees, so builds reuse what is already compiled. Concurrent builds serialize on Cargo's own lock. | true |
How the worktree is filled
At the start of every turn heph fetches the conversation's upstream, its base branch or its own branch (Branches), and combines it with the conversation's accepted private snapshot. It does not import staged, unstaged, or untracked files from your checkout. Paths your repository ignores are not in the snapshot; configured linked paths remain symlinks.
So target/ and node_modules/ are not copied, which is why link exists: a
model that needs to run your tests needs node_modules to be there, and a
symlink to yours gives it that without a copy. Anything linked is outside the
change heph tracks and reviews.
A project that is not a git repository works too: the whole directory is
observed, less target/, node_modules/, and .git/, plus whatever you
link.