# Worktrunk

> >

- **Type:** Skill
- **Install:** `agentstack add skill-jjmartres-opencode-worktrunk`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jjmartres](https://agentstack.voostack.com/s/jjmartres)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jjmartres](https://github.com/jjmartres)
- **Source:** https://github.com/jjmartres/opencode/tree/main/opencode/skills/worktrunk

## Install

```sh
agentstack add skill-jjmartres-opencode-worktrunk
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

| Task                            | Command                             |
| ------------------------------- | ----------------------------------- |
| 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

```bash
# 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

```bash
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

```bash
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

```bash
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:**

```bash
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):**

```bash
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

| Hook          | When                | Blocking               |
| ------------- | ------------------- | ---------------------- |
| `post-create` | After creation      | Yes (blocks --execute) |
| `post-start`  | After creation      | No (background)        |
| `post-switch` | Every switch        | No                     |
| `pre-commit`  | Before merge commit | Yes                    |
| `pre-merge`   | Before merge        | Yes                    |
| `post-merge`  | After merge         | Yes                    |
| `pre-remove`  | Before removal      | Yes                    |
| `post-remove` | After removal       | No                     |

### Essential Hook Patterns

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

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

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

```toml
[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):

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

## Template Variables & Filters

In hook commands (Jinja2 syntax):

| Variable               | Value                            |
| ---------------------- | -------------------------------- |
| `{{ 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) |

| Filter        | Example                       | Output                  |
| ------------- | ----------------------------- | ----------------------- |
| `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:

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

Configure in `~/.config/worktrunk/config.toml`:

```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:

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

Add to `~/.claude/settings.json` for statusline:

```json
{
  "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):

```bash
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:

```toml
# .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`:

```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

- `references/hooks.md` — Complete hook documentation with all patterns
- `references/commands.md` — Full command reference (switch, list, merge, remove, step, config)
- Official docs: https://worktrunk.dev
- Claude Code integration: https://worktrunk.dev/claude-code/
- Tips & patterns: https://worktrunk.dev/tips-patterns/

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jjmartres](https://github.com/jjmartres)
- **Source:** [jjmartres/opencode](https://github.com/jjmartres/opencode)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jjmartres-opencode-worktrunk
- Seller: https://agentstack.voostack.com/s/jjmartres
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.