Worktrunk Claude Code Skill

SKILL.md

name	description	license	metadata
worktrunk	Git worktree management via wt CLI. Create, switch, merge, and manage worktrees with hooks, LLM commits, and CI integration.	MIT	version model domains type inputs outputs 1.0.0 claude-haiku-4 git worktree version-control workflow tool-integration worktree-operations git-workflow worktree-management branch-operations

Worktrunk Skill

You are an expert at using Worktrunk (wt) for git worktree management. Worktrunk addresses worktrees by branch name, computes paths from templates, and automates workflow steps that normally require multiple git commands.

Core Philosophy

Worktrunk differs from raw git worktrees by:

• Addressing worktrees by branch name, not path
• Computing worktree paths from configurable templates
• Automating common workflows (create, merge, cleanup)
• Providing hooks at lifecycle points
• Integrating with Claude Code for AI-assisted development

Triggers

Primary Trigger Phrases

• worktree - Mentions of worktrees or worktree operations
• wt - Direct references to the wt command
• worktrunk - Explicit Worktrunk mentions
• switch branches with separate directories - Need for parallel branch work
• manage multiple branches - Multi-branch workflow needs

Common Usage Patterns

This skill activates when users:

• Need to work on multiple features simultaneously
• Want to automate git merge workflows
• Ask about managing multiple branches
• Mention parallel development or concurrent features
• Need CI status across branches
• Ask to configure git lifecycle hooks

Example invocations:

• "Create a new worktree for feature-X"
• "Switch to the feature-auth worktree"
• "Show me all my worktrees"
• "Merge this branch using wt"
• "Set up worktree hooks"
• "How do I use Worktrunk?"
• "Clean up old worktrees"
• "Configure LLM commit messages"

Process

When this skill is invoked, follow this process:

Phase 1: Understand Context

1. Identify the user's intent (create, switch, merge, configure, cleanup)
2. Determine current git repository state
3. Check if Worktrunk is installed (wt --version)
4. Verify worktree configuration exists

Phase 2: Execute Operation

For worktree creation:

1. Use wt switch --create <branch>
2. Specify base branch if needed (--base)
3. Wait for post-create hooks to complete
4. Verify new worktree directory exists

For switching:

1. Use wt list to show available worktrees
2. Use wt switch <branch> or wt select for interactive
3. Confirm directory change

For merging:

1. Review changes with wt list --full
2. Check pre-merge hook configuration
3. Execute wt merge with appropriate flags
4. Verify merge success and cleanup

For configuration:

1. Show current config with wt config show
2. Edit .config/wt.toml for project settings
3. Configure hooks, path templates, or LLM integration
4. Test configuration with dry runs

For cleanup:

1. List worktrees with wt list --branches
2. Identify safe-to-delete branches
3. Use wt remove with appropriate flags
4. Verify cleanup in background logs

Phase 3: Verification

1. Confirm operation succeeded
2. Check for error messages or warnings
3. Verify expected state (worktree exists, branch merged, etc.)
4. Provide next steps or recommendations

Phase 4: Guidance

1. Explain what was done and why
2. Suggest related operations
3. Point to relevant configuration options
4. Recommend best practices for the use case

Primary Commands

wt switch

Change directory to a worktree, creating one if needed.

wt switch feature-auth              # Switch to existing worktree
wt switch --create new-feature      # Create branch + worktree
wt switch -c hotfix --base production  # Branch from production
wt switch -                         # Return to previous worktree
wt switch ^                         # Switch to default branch

Key options:

• -c, --create: Create new branch
• -b, --base <BASE>: Source branch (defaults to default branch)
• -x, --execute <CMD>: Run command after switching
• -y, --yes: Skip approval prompts
• --clobber: Remove stale paths at target
• --no-verify: Skip hooks

Shortcuts:

• ^: Default branch (main/master)
• @: Current branch
• -: Previous worktree

Creation process:

1. Creates worktree at configured path
2. Changes to new directory
3. Runs post-create hooks (blocking)
4. Spawns post-start hooks (background)

wt list

Display all worktrees with status, diffs, and CI results.

wt list                             # Basic table view
wt list --full                      # Include CI status + diff analysis
wt list --branches                  # Include branches without worktrees
wt list --format=json               # JSON output for scripting
wt list statusline --claude-code    # Status for Claude statusline

Columns:

• Branch: Branch name
• Status: Working tree symbols and branch state
• HEAD±: Uncommitted changes (lines added/deleted)
• main↕: Commits ahead/behind default
• main…±: Line diffs since merge-base (with --full)
• Remote⇅: Ahead/behind tracking branch
• CI: Pipeline status (with --full)
• Commit: Hash, age, message

Status symbols:

• +: Staged changes
• !: Modified files
• ?: Untracked files
• ✘: Conflicts
• ⤴: Rebase in progress
• ⤵: Merge in progress
• ^: Is default branch
• ↕: Diverged from default
• /: No worktree exists

Progressive rendering: Branch names appear immediately; status fills in as background operations complete.

wt merge

Merge current branch to default branch (like GitHub's "Merge pull request").

wt merge                            # Merge to default, remove worktree
wt merge develop                    # Merge to specific branch
wt merge --no-remove                # Keep worktree after merge
wt merge --no-squash                # Preserve commit history

Options:

• --no-remove: Retain worktree after merge
• --no-squash: Keep individual commits
• --no-commit: Skip commit/squash phases
• --no-rebase: Skip rebase (fails if not current)
• --no-verify: Skip hooks
• -y, --yes: Skip confirmations
• --stage <all|tracked|none>: Control staging

Execution pipeline:

1. Squash: Combine commits since target into one
2. Rebase: Update to target if behind
3. Pre-merge hooks: Validate before merging
4. Merge: Fast-forward merge only
5. Pre-remove hooks: Final checks
6. Cleanup: Remove worktree and branch
7. Post-merge hooks: Final notifications (non-blocking)

wt remove

Delete worktrees and their branches (when safely merged).

wt remove                           # Remove current worktree
wt remove feature-branch            # Remove specific branch
wt remove old-1 old-2               # Remove multiple
wt remove -D experimental           # Force-delete unmerged
wt remove --no-delete-branch feat   # Remove worktree, keep branch

Branch cleanup logic (ordered by processing cost):

1. Same commit: Branch HEAD matches default
2. Ancestor: Branch in target's history
3. No added changes: Three-dot diff empty
4. Trees match: Tree SHA values identical
5. Merge simulation: Simulated merge produces matching tree

Options:

• --foreground: Block until complete (default: background)
• --no-verify: Skip hooks
• -y, --yes: Skip approval prompts
• -f, --force: Remove despite untracked files
• -D: Force-delete unmerged branches

Logs: .git/wt-logs/{branch}-remove.log

wt select

Interactive worktree picker with live preview.

wt select                           # Open interactive picker

Keyboard controls:

• ↑/↓: Navigate worktree list
• Enter: Switch to selected worktree
• Escape: Cancel
• Type: Filter worktrees
• 1-4: Switch preview tabs
• Alt-p: Toggle preview panel
• Ctrl-u/Ctrl-d: Scroll preview

Preview tabs:

1. HEAD±: Uncommitted changes
2. log: Recent commits (dimmed if on default)
3. main…±: Changes relative to merge-base
4. remote⇅: Ahead/behind upstream

wt config

Manage configuration, shell integration, and runtime settings.

wt config shell install             # Enable directory switching
wt config create                    # Generate user config
wt config create --project          # Create project config
wt config show                      # Display current config

State management:

wt config state marker set "🚧"     # Set custom status marker
wt config state default-branch      # View/set default branch
wt config state ci-status           # View cached CI results

Configuration locations:

• User: ~/.config/worktrunk/config.toml
• Project: .config/wt.toml

wt step

Execute individual workflow operations.

wt step commit                      # Create LLM-generated commit
wt step squash                      # Combine all branch commits
wt step rebase                      # Rebase onto target
wt step push                        # Fast-forward target branch
wt step commit --stage=tracked      # Stage only tracked files
wt step commit --show-prompt        # View LLM prompt

Staging options:

• all: Stage all changes including untracked (default)
• tracked: Stage only modified tracked files
• none: Commit without staging

wt hook

Execute lifecycle hooks.

wt hook show                        # Display configured hooks
wt hook pre-merge                   # Run all pre-merge hooks
wt hook pre-merge test              # Run hooks named "test"
wt hook post-create --var branch=feature  # With variable overrides
wt hook approvals add               # Pre-approve current project
wt hook approvals clear             # Clear project approvals

Hook types:

Hook	Trigger	Blocking	Fail-fast
post-create	After worktree creation	Yes	No
post-start	After worktree creation	No (background)	No
post-switch	After every switch	No (background)	No
pre-commit	Before commit during merge	Yes	Yes
pre-merge	Before merging to target	Yes	Yes
post-merge	After successful merge	Yes	No
pre-remove	Before worktree removal	Yes	Yes

Configuration Patterns

Worktree Path Template

Controls where new worktrees are created. Default: ../{{ repo }}.{{ branch | sanitize }}

Variables:

• {{ repo }}: Repository name
• {{ branch }}: Branch name
• {{ branch | sanitize }}: Branch with path separators replaced
• {{ worktree_path }}: Full path to worktree
• {{ worktree_name }}: Worktree directory name
• {{ default_branch }}: Default branch (main/master)
• {{ target }}: Target branch for merge operations
• {{ commit }}, {{ short_commit }}: Commit hashes
• {{ remote }}, {{ upstream }}: Remote information

Filters:

• sanitize: Replace path separators
• hash_port: Generate unique ports 10000-19999

Project Hooks Example

.config/wt.toml:

# Path template
path-template = "../{{ repo }}.{{ branch | sanitize }}"

# Single command hooks
post-create = "npm install"

# Multiple command hooks
[pre-merge]
test = "cargo test"
lint = "cargo clippy"
build = "cargo build --release"

[post-start]
server = "npm run dev -- --port {{ branch | hash_port }}"

LLM Commit Messages

[commit.generation]
command = "llm"
args = ["-s", "Commit message from diff"]
template = """
Generate a commit message for these changes.

Branch: {{ branch }}
Diff:
{{ git_diff }}

Recent commits:
{{ recent_commits }}
"""

Claude Code Integration

Status Indicators

The Worktrunk plugin tracks Claude's activity state in wt list:

• 🤖: Claude is working
• 💬: Claude is waiting for input

Installation:

claude plugin marketplace add max-sixty/worktrunk
claude plugin install worktrunk@worktrunk

Statusline Configuration

Add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "wt list statusline --claude-code"
  }
}

Note: This may incur 1-2 second latency due to network requests for CI status.

Custom Markers

wt config state marker set "🚧"                   # Current branch
wt config state marker set "✅" --branch feature  # Specific branch

Common Workflows

Start New Feature

wt switch --create feature/new-auth
# Worktree created, post-create hooks run
# Now in new worktree directory

Work on Existing Feature

wt list                             # See all worktrees
wt switch feature/auth              # Switch to existing
# or
wt select                           # Interactive picker

Merge Feature

# In feature branch worktree
wt merge
# Pipeline: squash → rebase → pre-merge hooks → merge → cleanup

Clean Up Old Work

wt list --branches                  # See all branches
wt remove old-feature-1 old-feature-2
# Safe-to-delete branches removed automatically

Review Changes Before Merge

wt select                           # Open picker
# Press 3 to view main…± (changes since merge-base)
# Press 1 to view HEAD± (uncommitted changes)

Best Practices

Hook Usage

Use blocking hooks (pre-merge, pre-commit) for:

• Tests that must pass
• Linting that must succeed
• Build verification
• Security scans

Use non-blocking hooks (post-start) for:

• Development servers
• File watchers
• Background processes

Example pre-merge workflow:

[pre-merge]
format = "cargo fmt --check"
test = "cargo test"
clippy = "cargo clippy -- -D warnings"

Staging Strategies

Use --stage=all (default) when:

• All changes are intentional
• Working on isolated features

Use --stage=tracked when:

• Untracked files are experiments
• Generated files exist
• You want explicit control

Use --stage=none when:

• Changes already staged
• Running wt step commit after manual staging

Template Variables in Hooks

Avoid hardcoding values. Use template variables:

# Bad
post-start = "npm run dev -- --port 3000"

# Good
post-start = "npm run dev -- --port {{ branch | hash_port }}"

This generates unique ports per branch, preventing conflicts.

Performance Optimization

Use progressive rendering:

wt list --progressive               # Fast info first, updates follow

Cache CI status: CI results are cached 30-60 seconds per branch.

Background operations: wt remove runs in background by default. Use --foreground only when necessary.

Environment Variables

All config options support WORKTRUNK_ prefixed variables using SCREAMING_SNAKE_CASE. Nested keys use double underscores:

export WORKTRUNK_COMMIT_GENERATION__COMMAND="llm"
export WORKTRUNK_PATH_TEMPLATE="../{{ repo }}.{{ branch | sanitize }}"

Security Considerations

Hook approvals: Project hooks require approval on first run. Approvals are saved to user config and invalidated if the command template changes.

Approval management:

wt hook approvals add               # Pre-approve current project
wt hook approvals clear             # Clear project approvals
wt hook approvals clear --global    # Clear all approvals

Skip approvals: Use -y, --yes flag (use with caution).

Troubleshooting

Worktree Path Conflicts

If wt switch fails due to existing path:

wt switch --clobber feature-branch  # Remove stale path

Hook Failures

View hook output:

wt hook pre-merge                   # Run manually
wt hook show                        # Display configuration

Skip hooks temporarily:

wt merge --no-verify                # Skip all hooks
wt switch --no-verify new-branch    # Skip post-create/post-start

Background Operation Logs

Check logs for background operations:

cat .git/wt-logs/{branch}-remove.log

Default Branch Detection

If default branch is incorrect:

wt config state default-branch set main

Integration with Standard Git

Worktrunk is built on git worktrees. All standard git commands work within worktrees:

git status                          # Works normally
git commit                          # Works normally
git push                            # Works normally

Use wt for worktree-level operations (create, switch, merge, remove). Use git for standard version control operations within a worktree.

Output Formats

JSON Output

For scripting and automation:

wt list --format=json | jq '.[] | select(.uncommitted_changes > 0)'
wt list --format=json | jq '.[] | select(.ahead > 0)'

Table Output

Human-readable with progressive rendering:

wt list --full                      # All information
wt list --progressive               # Fast info first

Advanced Patterns

Multi-Repo Workflows

Use consistent path templates across repositories:

path-template = "~/work/{{ repo }}/{{ branch | sanitize }}"

Port Assignment

Generate unique ports for development servers:

[post-start]
api = "npm run api -- --port {{ branch | hash_port }}"
frontend = "npm run frontend -- --port {{ branch | hash_port | plus: 1000 }}"

Conditional Hooks

Use shell conditionals in hook commands:

[pre-merge]
test = "[ -f package.json ] && npm test || cargo test"

Related Commands Summary

Command	Purpose	Common Usage
wt switch	Navigate/create worktrees	wt switch -c feature
wt list	Display status	wt list --full
wt merge	Merge to default	wt merge
wt remove	Clean up	wt remove old-branch
wt select	Interactive picker	wt select
wt config	Configuration	wt config show
wt step	Individual operations	wt step commit
wt hook	Hook management	wt hook pre-merge

When to Use Each Command

Use wt switch:

• Starting new work
• Changing between features
• Creating new branches with worktrees

Use wt list:

• Seeing overview of all work
• Checking CI status
• Finding worktrees with uncommitted changes

Use wt merge:

• Completing feature work
• Automating squash + rebase + merge workflow
• Running pre-merge validation

Use wt remove:

• Cleaning up completed work
• Removing stale branches
• Freeing disk space

Use wt select:

• Visual browsing of worktrees
• Previewing changes before switching
• Interactive workflow preference

Use wt config:

• Initial setup
• Customizing path templates
• Managing hooks and approvals

Use wt step:

• Manual control over merge steps
• Generating LLM commit messages
• Inspecting prompts before execution

Use wt hook:

• Testing hooks manually
• Viewing hook configuration
• Managing approvals

Quick Reference

Frequently Used Commands

# Start new feature
wt switch -c feature/auth

# See all work
wt list --full

# Switch to existing
wt switch feature/auth

# Interactive picker
wt select

# Merge and clean up
wt merge

# Remove old work
wt remove old-feature

# Generate commit
wt step commit

# View config
wt config show

# Set custom marker
wt config state marker set "🚧"

Essential Configuration

# .config/wt.toml
path-template = "../{{ repo }}.{{ branch | sanitize }}"

[pre-merge]
test = "npm test"
lint = "npm run lint"

[post-start]
dev = "npm run dev -- --port {{ branch | hash_port }}"

Verification/Success Criteria

After executing Worktrunk operations, verify success using these criteria:

Worktree Creation (wt switch --create)

Success indicators:

• New directory exists at expected path
• wt list shows new worktree with correct branch
• Post-create hooks completed without errors
• Working directory changed to new worktree
• .git file (not directory) exists in worktree

Verification commands:

pwd                                 # Confirm in new worktree
wt list                             # Verify worktree appears
git status                          # Check branch and state
ls -la .git                         # Verify .git is a file (worktree link)

Worktree Switching (wt switch)

Success indicators:

• Working directory changed
• Correct branch checked out
• No error messages about missing worktree
• Post-switch hooks executed (if configured)

Verification commands:

pwd                                 # Confirm directory
git branch --show-current           # Verify branch

Merge Operation (wt merge)

Success indicators:

• Target branch fast-forwarded
• Source branch deleted (unless --no-remove)
• Worktree removed (unless --no-remove)
• No conflicts reported
• Pre-merge hooks passed
• Returned to default worktree

Verification commands:

git log --oneline main -5           # Check merge commit
wt list --branches                  # Verify branch removed
git branch -d <branch> 2>&1         # Should say already deleted

Worktree Removal (wt remove)

Success indicators:

• Worktree directory removed
• Branch deleted (if safe)
• wt list no longer shows worktree
• Returned to main worktree
• No errors in removal logs

Verification commands:

wt list                             # Verify worktree gone
ls ../path/to/worktree              # Should not exist
cat .git/wt-logs/<branch>-remove.log  # Check for errors

Configuration (wt config)

Success indicators:

• Config file created at expected location
• wt config show displays settings
• Path template expands correctly
• Hooks defined and visible in wt hook show

Verification commands:

wt config show                      # Display config
wt hook show                        # List hooks
cat .config/wt.toml                 # View raw config

Hook Execution

Success indicators:

• Hook commands executed
• Exit code 0 for success
• Expected side effects occurred (tests passed, servers started)
• No approval prompts for approved commands
• Appropriate logs generated

Verification commands:

wt hook show                        # Verify hook config
wt hook pre-merge --var branch=test # Dry run
echo $?                             # Check exit code

General Health Checks

Run these to verify overall Worktrunk state:

wt list --full                      # Complete status overview
wt config show                      # Verify configuration
git worktree list                   # Raw git worktree view
ls .git/wt-logs/                    # Check operation logs

Anti-Patterns

Avoid these common mistakes when using Worktrunk:

Worktree Management

Don't manually delete worktree directories

# Bad
rm -rf ../repo.feature-branch

# Good
wt remove feature-branch

Why: Manual deletion leaves git metadata inconsistent. Use wt remove for proper cleanup.

Don't create worktrees with raw git commands

# Bad
git worktree add ../new-worktree feature-branch

# Good
wt switch --create feature-branch

Why: Worktrunk manages paths, hooks, and metadata. Mixing approaches creates confusion.

Don't use absolute paths in hook commands

# Bad
post-start = "/home/user/project/scripts/dev-server.sh"

# Good
post-start = "./scripts/dev-server.sh"

Why: Absolute paths break when other developers use different paths.

Don't hardcode values in templates

# Bad
post-start = "npm run dev -- --port 3000"

# Good
post-start = "npm run dev -- --port {{ branch | hash_port }}"

Why: Hardcoded ports/values cause conflicts across worktrees.

Hook Configuration

Don't use blocking hooks for long-running processes

# Bad - blocks worktree creation
[post-create]
server = "npm run dev"

# Good - runs in background
[post-start]
server = "npm run dev"

Why: Blocking hooks delay worktree creation. Use post-start for background tasks.

Don't skip verification without understanding consequences

# Bad - bypasses safety checks
wt merge --no-verify

# Good - fix issues, then merge
wt hook pre-merge              # Test hooks
wt merge                       # Run with verification

Why: Hooks exist for safety. Skipping them can introduce bugs.

Don't ignore hook failures

# Bad - force through despite failures
wt merge -y --no-verify

# Good - investigate and fix
wt hook pre-merge              # Debug failure
# Fix the issue
wt merge                       # Retry with hooks

Why: Hook failures indicate real problems. Fix root cause.

Merge Workflow

Don't merge without rebasing first

# Bad - merges stale branch
wt merge --no-rebase

# Good - rebase then merge
wt merge                       # Includes rebase by default

Why: Merging without rebasing can create conflicts or outdated merges.

Don't keep worktrees after merging by default

# Bad - accumulates stale worktrees
wt merge --no-remove

# Good - clean up after merge
wt merge                       # Removes by default

Why: Stale worktrees waste disk space and clutter wt list.

Don't force-delete branches without checking

# Bad - loses unmerged work
wt remove -D feature-branch

# Good - verify merge status first
wt list --full                 # Check merge status
wt remove feature-branch       # Safe delete or manual review

Why: Force-delete can lose valuable work.

Configuration

Don't mix worktree and non-worktree development

# Bad - inconsistent workflow
git switch main                # Non-worktree switch
wt switch feature-branch       # Worktree switch

Why: Mixing approaches confuses state. Choose one method.

Don't commit .config/wt.toml with sensitive data

# Bad
[pre-merge]
deploy = "deploy.sh --token=secret123"

# Good
[pre-merge]
deploy = "deploy.sh --token=$DEPLOY_TOKEN"

Why: Secrets in config get committed to git.

Don't use --yes flag in scripts without safeguards

# Bad - auto-approves everything
wt merge -y

# Good - explicit approval or conditional
wt merge                       # User approves
# OR
wt hook approvals add          # Pre-approve project

Why: Auto-approval bypasses safety prompts.

Performance

Don't use --full flag unnecessarily

# Bad - always fetches CI (slow)
alias wl='wt list --full'

# Good - use when needed
alias wl='wt list'             # Fast by default
alias wlf='wt list --full'     # Full when needed

Why: --full fetches CI status (1-2 second latency).

Don't run foreground operations when background works

# Bad - blocks terminal
wt remove old-branch --foreground

# Good - runs in background
wt remove old-branch           # Background by default

Why: Foreground blocks terminal unnecessarily.

Staging

Don't use --stage=all with experimental files

# Bad - commits experiments
wt step commit --stage=all

# Good - stage only tracked
wt step commit --stage=tracked

Why: Untracked experiments shouldn't be committed.

Extension Points

Worktrunk can be extended and integrated with other tools:

1. Custom Hook Scripts

Create reusable hook scripts in project:

# scripts/pre-merge-checks.sh
#!/bin/bash
set -e

echo "Running tests..."
npm test

echo "Checking types..."
npm run typecheck

echo "Linting..."
npm run lint

echo "Building..."
npm run build

Reference in .config/wt.toml:

[pre-merge]
checks = "./scripts/pre-merge-checks.sh"

Benefits: Version-controlled, reusable, testable independently.

2. LLM Integration for Commit Messages

Extend LLM commit generation with custom prompts:

[commit.generation]
command = "llm"
args = ["-m", "claude-sonnet-4-5", "-s", "commit-msg"]
template = """
You are an expert at writing conventional commit messages.

Branch: {{ branch }}
Repository: {{ repo }}

Changes:
{{ git_diff }}

Recent commits for style reference:
{{ recent_commits }}

Generate a commit message following conventional commits format.
Use type: feat, fix, docs, style, refactor, test, chore.
Include scope if relevant.
Keep subject under 72 characters.
"""

Extension opportunities:

• Custom LLM models
• Project-specific commit conventions
• Multi-language support
• Ticket/issue linking

3. CI Integration

Extend CI status display with custom providers:

GitHub Actions via gh CLI:

[ci]
command = "gh run list --branch {{ branch }} --limit 1 --json status,conclusion"

GitLab CI:

[ci]
command = "glab ci status --branch {{ branch }}"

Custom CI:

# scripts/check-ci-status.sh
#!/bin/bash
curl -s "https://ci.example.com/api/status?branch=$1"

4. Editor Integration

Create editor commands for common workflows:

VS Code tasks (.vscode/tasks.json):

{
  "label": "Worktrunk: New Feature",
  "type": "shell",
  "command": "wt switch --create feature/${input:featureName}"
}

Vim commands:

" In .vimrc or project .vimrc
command! -nargs=1 WtNew execute '!wt switch --create' <q-args>
command! WtList execute '!wt list --full'
command! WtMerge execute '!wt merge'

5. Notification System

Add notifications to hooks:

[post-merge]
notify = "notify-send 'Worktrunk' 'Merged {{ branch }} to {{ target }}'"

Cross-platform notifications:

# scripts/notify.sh
#!/bin/bash
if command -v notify-send &> /dev/null; then
    notify-send "$1" "$2"
elif command -v osascript &> /dev/null; then
    osascript -e "display notification \"$2\" with title \"$1\""
fi

6. Custom Status Markers

Extend status marker automation:

# scripts/auto-marker.sh
#!/bin/bash
# Set marker based on branch state

if git diff --quiet && git diff --cached --quiet; then
    wt config state marker set "✅"  # Clean
elif [ -n "$(git status --porcelain)" ]; then
    wt config state marker set "🚧"  # WIP
fi

Call from hooks:

[post-switch]
marker = "./scripts/auto-marker.sh"

7. Metrics and Analytics

Track worktree usage patterns:

# scripts/worktree-metrics.sh
#!/bin/bash
# Log worktree creation for analytics

echo "$(date),$(whoami),{{ branch }},created" >> .git/wt-metrics.csv

[post-create]
metrics = "./scripts/worktree-metrics.sh"

Analysis:

# Most active branches
cut -d',' -f3 .git/wt-metrics.csv | sort | uniq -c | sort -rn

# Worktree creation timeline
cut -d',' -f1,3 .git/wt-metrics.csv

8. Dependency Management

Automate dependency installation per worktree:

[post-create]
deps = "[ -f package.json ] && npm ci || ([ -f Cargo.toml ] && cargo fetch) || ([ -f requirements.txt ] && pip install -r requirements.txt)"

Conditional by branch prefix:

# scripts/install-deps.sh
#!/bin/bash
BRANCH={{ branch }}

if [[ $BRANCH == feature/* ]]; then
    npm ci
elif [[ $BRANCH == hotfix/* ]]; then
    npm ci --production
fi

9. Database/State Management

Handle per-worktree database state:

[post-create]
db = "cp database.sqlite database.{{ branch | sanitize }}.sqlite"

[post-start]
db-server = "rails server -p {{ branch | hash_port }} --database database.{{ branch | sanitize }}.sqlite"

10. Testing Integration

Run tests automatically before merge:

[pre-merge]
unit = "npm test"
integration = "npm run test:integration"
e2e = "npm run test:e2e -- --headless"
coverage = "npm run coverage && [ $(cat coverage/coverage-summary.json | jq '.total.lines.pct') -ge 80 ]"

Selective testing:

# scripts/smart-test.sh
#!/bin/bash
# Only run tests for changed files

FILES=$(git diff --name-only {{ target }}...HEAD)

if echo "$FILES" | grep -q "\.ts$"; then
    npm run test:unit
fi

if echo "$FILES" | grep -q "\.tsx$"; then
    npm run test:component
fi

---

Skill Invocation

This skill is active when you need to:

• Manage git worktrees
• Switch between branches with separate working directories
• Automate git workflows (merge, squash, rebase)
• Configure lifecycle hooks
• Integrate AI-assisted commit messages
• View CI status across branches

When the user mentions "worktree", "wt", or "worktrunk", activate this skill to provide expert guidance on Worktrunk operations.