OpenSkillIndex← back to search
claude-code

Opencode worktrunk

install
source · Clone the upstream repo
git clone https://github.com/jjmartres/opencode
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/jjmartres/opencode "$T" && mkdir -p ~/.claude/skills && cp -r "$T/opencode/skills/worktrunk" ~/.claude/skills/jjmartres-opencode-worktrunk && rm -rf "$T"
manifest: opencode/skills/worktrunk/SKILL.md
source content

Worktrunk Skill

Worktrunk (

wt
) is a CLI for git worktree management designed to run AI agents (like Claude Code) in parallel across isolated branches. Think of it as making 
git worktree
as easy as 
git branch
.

Quick Reference

TaskCommand
Create worktree + switch
wt switch --create feat
Create worktree + launch Claude
wt switch --create feat -x claude
List all worktrees
wt list
Merge & clean up
wt merge main
Remove current worktree
wt remove
Commit staged changes
wt step commit

Installation

# macOS/Linux (recommended)
brew install worktrunk && wt config shell install

# Cargo
cargo install worktrunk && wt config shell install

# Windows
winget install max-sixty.worktrunk
git-wt config shell install

Shell integration (

wt config shell install
) is required so that 
wt switch
can actually change the shell's directory.

Core Workflow

1. Create and Switch

wt switch --create feature-auth         # New branch + worktree
wt switch --create feature-auth -x claude  # + launch Claude in it
wt switch existing-branch               # Switch to existing worktree
wt switch -                             # Previous worktree

Worktrees are placed at 

../repo.branch-name
by default (configurable).

2. Inspect Status

wt list                    # All worktrees with status, commits, CI
wt list --full --branches  # Include remote branches without worktrees
wt list --format=json      # Machine-readable output

Key indicators in 

wt list
:

  • @
    = current worktree
  • +
    / 
    -
    = staged / unstaged changes
  • ↑
    / 
    ↓
    = ahead / behind remote
  • ⇡
    / 
    ⇣
    = ahead / behind default branch
  • 🤖
    = Claude is working (Claude Code plugin)
  • 💬
    = Claude waiting for input

3. Parallel Agents Pattern

wt switch -x claude -c feature-a -- 'Add user authentication'
wt switch -x claude -c feature-b -- 'Fix the pagination bug'
wt switch -x claude -c feature-c -- 'Write tests for the API'


-x
/ 
--execute
runs a command after switching; arguments after 
--
are passed to it.

4. Merge or Clean Up

PR workflow:

wt step commit              # Commit staged changes with optional LLM message
gh pr create                # Open PR
wt remove                   # After PR merged

Local merge (squash + rebase + fast-forward):

wt merge main
# Commits, rebases onto main, fast-forward merges, removes worktree

Hooks

Hooks automate worktree lifecycle events. Define in 

.config/wt.toml
(project) or 
~/.config/worktrunk/config.toml
(user/global).

See 

references/hooks.md
for the full hook reference, template variables, and common patterns (dev servers, databases, cold-start elimination).

Hook Types at a Glance

HookWhenBlocking
post-create
After creationYes (blocks --execute)
post-start
After creationNo (background)
post-switch
Every switchNo
pre-commit
Before merge commitYes
pre-merge
Before mergeYes
post-merge
After mergeYes
pre-remove
Before removalYes
post-remove
After removalNo

Essential Hook Patterns

Eliminate cold starts (copy deps/caches/env from main):

[post-start]
copy = "wt step copy-ignored"

Dev server per worktree (deterministic port from branch name):

[post-start]
server = "npm run dev -- --port {{ branch | hash_port }}"
[pre-remove]
server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/dev/null || true"

Local CI gate (run tests before merge):

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

Template Variables & Filters

In hook commands (Jinja2 syntax):

VariableValue
{{ branch }}
Branch name
{{ repo }}
Repository directory name
{{ worktree_path }}
Absolute path to this worktree
{{ default_branch }}
Default branch name
{{ target }}
Target branch (merge hooks only)
FilterExampleOutput
sanitize
{{ branch | sanitize }}
/
and 
\
→ 
-
sanitize_db
{{ branch | sanitize_db }}
DB-safe identifier
hash_port
{{ branch | hash_port }}
Stable port 10000-19999

LLM Commit Messages

Generate commit messages from diffs:

wt step commit              # Commit staged changes, generate message
wt step commit --all        # Stage all + commit

Configure in 

~/.config/worktrunk/config.toml
:

[commit.generation]
model = "claude-opus-4-5"   # or any supported model
provider = "anthropic"

Claude Code Integration

Install the plugin for activity tracking (

🤖
/ 
💬
in 
wt list
) and configuration skill:

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

Add to 

~/.claude/settings.json
for statusline:

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

Zellij Integration

Spawn agent handoffs directly into Zellij panes (great with your existing Zellij setup):

zellij run -- wt switch --create fix-auth -x claude -- \
  'Fix the session timeout bug in auth module'

Or use hooks for a full multi-pane layout per worktree:

# .config/wt.toml
[post-create]
zellij = """
zellij action new-tab --name {{ branch | sanitize }}
zellij action new-pane -- claude
"""

Common Commands for devops Work

For microservice's repos, a typical 

.config/wt.toml
:

[post-create]
env = "cp {{ primary_worktree_path }}/.env.local .env.local 2>/dev/null || true"

[post-start]
copy = "wt step copy-ignored"

[pre-merge]
lint = "make lint"
test = "make test"

[post-merge]
notify = "echo '✓ Merged {{ branch }} → {{ target }}'"

Further Reference