worktrunk Documentation

Worktrunk uses Authenticode signatures for its Windows release binaries (wt.exe and git-wt.exe) to prevent false positive detections by Microsoft Defender (e.g., Trojan:Win32/Wacatac.B!ml).

Scope of Signing:

• Signed: Windows binaries (wt.exe and git-wt.exe) distributed via GitHub Releases and winget (winget install max-sixty.worktrunk).
• Not Signed: macOS and Linux release artifacts, crates.io source distributions, and cargo install builds (which compile locally from source).

Security Model:

• Certificates are provided by the SignPath Foundation.
• Private keys are held on a Hardware Security Module (HSM) and are never possessed by maintainers.
• Signing is triggered by version tags in the official repository and requires manual approval by an authorized Approver.

Worktrunk is designed to make git worktrees as easy to manage as branches, specifically optimized for running multiple AI agents in parallel.

Key Capabilities:

• Parallelism: Each agent gets its own working directory via git worktrees to prevent state conflicts.
• Automation: Supports hooks (create, pre-merge, post-merge), LLM-generated commit messages, and automated merge workflows.
• Developer Experience: Includes an interactive picker for browsing worktrees, PR checkout (wt switch pr:123), and build cache sharing (e.g., target/ or node_modules/) to speed up environment setup.
• Customization: Supports aliases and per-branch variables for complex workflows.

Worktrunk uses two distinct configuration files with different scopes:

1. User config (~/.config/worktrunk/config.toml): Contains personal preferences like LLM integration, worktree path templates, and personal hooks. This file is never checked into git.
2. Project config (<repo>/.config/wt.toml): Contains team-wide automation and lifecycle hooks (e.g., pre-start, post-merge). This file is checked into git and is versioned with the repository.

Use User config for your own environment settings and Project config for automation that should run for everyone on the team.

To merge your work from a specific worktree back into the target branch and clean up the environment, use wt merge. This command runs from within the feature worktree and performs the merge into the target branch, similar to a GitHub merge button, automating the lifecycle management that git worktree requires manually.

$ wt merge

To avoid port collisions between multiple worktrees, use the hash_port filter to generate a stable, deterministic port (10000-19999) based on the branch name. Use wt step tether in a post-start hook to run the server in a managed process group that is automatically cleaned up when the worktree is removed.

# .config/wt.toml
[post-start]
server = "wt step tether -- npm run dev -- --port {{ branch | hash_port }}"

[list]
url = "http://localhost:{{ branch | hash_port }}"

If you encounter C compilation errors related to tree-sitter or C99 mode (e.g., le16toh undefined) during installation, you can install Worktrunk without the syntax highlighting feature. This is useful for older systems or minimal Docker images.

cargo install worktrunk --no-default-features --features cli

Project hooks (defined in .config/wt.toml) require manual approval on their first run for security. Approvals are stored in ~/.config/worktrunk/approvals.toml.

• Bypass prompts: Use the --yes flag for CI or automation.
• Skip all hooks: Use the --no-hooks flag.
• Manage approvals: Use wt config approvals add or wt config approvals clear.

If a command changes, a new approval is required. Declining a prompt skips all project commands for that specific operation.

Because a bare .git directory has no tracked files, the project configuration file (.config/wt.toml) must be created within an existing worktree. Once created, it will be automatically available in all other worktrees of that project.

Steps:

1. Create the first worktree: wt switch <branch>.
2. Enter the worktree: cd <worktree_path>.
3. Create the project config: wt config create --project.

cd myproject/main
wt config create --project

By default, alias bodies are rendered once at dispatch in the invoking worktree. If you are using an alias to run a command across all worktrees (like wt step for-each), variables like {{ branch }} will be 'baked in' to the current worktree's value before the loop starts.

To defer expansion so the variable is evaluated per worktree, wrap the variable in {% raw %}…{% endraw %}.

Important: When using for-each, the deferred variable contains spaces. To prevent shell splitting errors, wrap the command in sh -c '...' to keep the value as a single token.

Example of a deferred alias to show each worktree's branch:

[aliases]
show-branches = "wt step for-each -- sh -c 'echo {% raw %}{{ branch }}{% endraw %}'"