worktrunk

name	worktrunk
description	Use Worktrunk for git worktree workflows whenever working in a git repository. Prefer `wt` over manual branch/worktree lifecycle commands when creating task branches, switching contexts, spawning parallel agents, merging locally, cleaning up merged branches, configuring hooks, or inspecting multi-worktree status. Triggers include git workflow requests, branch creation, branch switching, worktrees, parallel agents, stacked branches, merge cleanup, hook setup, and worktree status.
allowed-tools	Bash(wt:*), Bash(git:*), Bash(gh:*), Bash(tmux:*)

Worktrunk

Use Worktrunk as the default workflow layer for git repositories.

Worktrunk does not replace all git commands. Use it for worktree and branch lifecycle operations, and use plain git for low-level inspection like git diff, git show, git log, git commit, and git push.

Core Rules

1. Prefer wt switch over manual git switch, git checkout, git worktree add, or cd-based worktree navigation when the task involves changing working context.
2. Prefer wt switch --create <branch> for new task branches.
3. Prefer wt switch --create <branch> --base=@ for stacked work that should build on the current branch.
4. Prefer wt list to understand all active worktrees before proposing branch cleanup or parallel work.
5. Prefer wt merge for local merge-and-cleanup workflows, and wt remove for deleting merged worktrees after remote PR merges.
6. Never use raw git worktree add/remove unless Worktrunk cannot express the operation.

Start Here

When a task touches git inside a repository, orient with:

git rev-parse --show-toplevel
git status --short --branch
wt list

If the task may involve CI or branches without worktrees, use:

wt list --full --branches

This gives the agent a worktree-aware view before making changes.

Preferred Workflows

New task branch

Create a new worktree instead of reusing the current directory:

wt switch --create feature-branch

If the user also wants to launch a tool immediately:

wt switch --create feature-branch -x '<command>'

Arguments after -- are passed through to the command:

wt switch --create feature-branch -x claude -- 'Implement the feature'

Switch contexts

Use Worktrunk shortcuts whenever they fit:

wt switch ^
wt switch -
wt switch @
wt switch pr:123

Parallel agent handoff

When spawning another agent or long-running parallel task, create a dedicated worktree and launch it inside tmux:

tmux new-session -d -s feature-auth "wt switch --create feature-auth -x claude -- 'Implement auth flow'"

Use branch-based tmux session names derived from {{ branch | sanitize }} when templating hooks or commands.

Stacked work

When the next task should build on the current branch instead of the default branch:

wt switch --create feature-part-2 --base=@

Local merge workflow

If the user wants a local merge into the default branch, prefer:

wt merge

Useful variants:

wt merge develop
wt merge --no-remove
wt merge --no-squash

Cleanup after remote merge

If a PR merged on GitHub and the local worktree just needs cleanup:

wt remove

Mark branch status

Use markers when they help coordinate parallel work:

wt config state marker set "🤖"
wt config state marker set "💬" --branch feature-auth
wt config state marker clear --branch feature-auth

Hooks And Project Automation

When the user asks to set up project automation, prefer .config/wt.toml hooks instead of one-off shell rituals.

Common patterns:

• post-create for blocking setup like dependency installation or env file generation
• post-start for background tasks like dev servers, cache copying, or watchers
• pre-commit for fast validation
• pre-merge for tests and builds that gate wt merge
• post-remove for cleanup of background services

Read references/common-patterns.md before writing hook configs.

Decision Rules

• Use wt for branch/worktree lifecycle.
• Use git for diff/log/show/commit/push level operations.
• Use gh with wt switch pr:<n> when a GitHub PR branch needs a local worktree.
• Use tmux for background agent sessions or long-running commands tied to a worktree.

Avoid These Anti-Patterns

• Creating a feature branch in the current directory when a dedicated worktree is more appropriate
• Running git worktree add manually when wt switch --create would do it
• Manually deleting worktree directories instead of wt remove
• Using ad hoc branch names without checking wt list first when several parallel branches already exist
• Using git switch to retarget a worktree unless the task specifically requires changing branches in place

Common Failure Cases

• Branch does not exist: use wt switch --create <branch>
• Target path occupied: switch to the existing worktree or use --clobber only when the stale path is clearly safe to remove
• Shell does not change directories: run wt config shell install
• Hooks block progress: use --no-verify only when the user wants hooks skipped, otherwise inspect .config/wt.toml and logs
• Need the default branch name without assuming main: use wt config state default-branch

Quick Reference

wt list
wt list --full --branches
wt switch --create feature-x
wt switch --create feature-y --base=@
wt switch pr:123
wt merge
wt remove
wt config show --full
wt config state default-branch

References

Reference	When to Read
references/common-patterns.md	Before configuring hooks or parallel-agent workflows