Worktrunk: parallel worktrees, lifecycle control and source analysis
Operate Worktrunk safely: hooks, confidential diffs and asynchronous removal
Review actual command authority, optional model data flow and recovery limits before automating merge or cleanup.
What you will learn
- Approval is not a sandbox or a content signature
- Optional commit generation can move source information
- Removal is not a durable recycle bin
Before you start
- Basic Git branches and command-line navigation
- A disposable repository for optional reader exercises
Explain worktree boundaries, verify a first checkout and review configured commands before adopting automation.
Key takeaways
- Approved templates can still call changed executable code.
- A hosted commit generator may receive confidential diffs.
- Background trash is temporary machinery, not a backup policy.
Approval is not a sandbox or a content signature
A project hook is a shell command running with the invoking account’s authority. The approval mechanism creates a consent boundary, not an operating-system isolation boundary. A familiar template such as a test command can invoke scripts changed in a later checkout. Review project configuration and the scripts it references whenever the trust context changes.
User hooks have a different approval path, and manual pattern approvals may cover multiple repositories. Examine both sources before assuming a new checkout is inert. Avoid --yes as the default for unreviewed projects. A separate worktree does not isolate credentials, network access or the rest of the filesystem.
Optional commit generation can move source information
The documented commit-message feature builds a prompt and sends it to an external command through standard input. If that command calls a hosted model, a diff can leave the machine. Review the exact prompt, selected content and provider arrangement before enabling the feature for confidential code. Local command execution does not imply local-only inference.
Keep production credentials out of trial hooks and use a disposable data environment. When startup fails, inspect the relevant hook log and whether the task was blocking or background. Do not interpret a completed main command as proof that every background process succeeded or stopped. Assign ownership for servers and external resources created by hooks.
Removal is not a durable recycle bin
The pinned remove documentation describes background removal that can rename a worktree into .git/wt/trash and then delete it through a detached process, with a cross-filesystem fallback. An intermediate trash location is therefore not a promised recovery window. Preserve important work before removal; do not rely on racing a cleanup process to retrieve a file.
The force flags have different targets: --force concerns a dirty worktree, while -D concerns an unmerged branch. Neither belongs in an unexplained onboarding one-liner. Check exact branch, path, worktree status and the intended retention policy first. The documented logs can explain asynchronous failure; verify final Git and filesystem state rather than treating the command’s return as completed cleanup.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Review hook templates and referenced scripts.
- 2
Trace any external command receiving source content.
- 3
Record branch, path and preserved work before cleanup.
- 4
Check logs and final state after asynchronous operations.
Copy-ready example
{
"beforeRemoval": {
"exactBranch": null,
"exactPath": null,
"workingTreeReviewed": false,
"importantWorkPreserved": false,
"branchRetentionDecided": false
},
"removalExecuted": false
}Frequently asked questions
Does approval guarantee a hook is safe?
No. It records a consent decision about a template, not a complete security review of everything the command can reach.
Can I recover from the trash directory later?
Do not rely on it; the documented background cleanup deletes that intermediate directory.
Sources
- Worktrunk / docs/src/content/docs/hook.mdSource checked 2026-09-14
- Worktrunk / docs/src/content/docs/llm-commits.mdSource checked 2026-09-14
- Worktrunk / docs/src/content/docs/remove.mdSource checked 2026-09-14
- Worktrunk / src/config/approvals.rsSource checked 2026-09-14