Worktrunk

https://worktrunk.dev
Admin
Worktrunk is a CLI tool for Git worktree management designed for parallel AI agent workflows.
Tokens:102,483
Snippets:748
Trust Score:7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Project config TOML example

Source: https://worktrunk.dev/config

Example project configuration file at `.config/wt.toml` with pre-start and pre-merge hooks.

```toml
# .config/wt.toml
[pre-start]
deps = "npm ci"

[pre-merge]
test = "npm test"
```

--------------------------------

### TOML hooks configuration example

Source: https://worktrunk.dev/extending

Example TOML configuration defining three hooks: a pre-start hook to install dependencies, a post-start hook to run a dev server with a template variable, and a pre-merge hook to run tests. Hooks are defined in TOML config and support template variables.

```toml
[pre-start]
deps = "npm ci"

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

[pre-merge]
test = "npm test"

```

--------------------------------

### User config TOML example

Source: https://worktrunk.dev/config

Example user configuration file at `~/.config/worktrunk/config.toml` with worktree path template and LLM commit settings.

```toml
# ~/.config/worktrunk/config.toml
worktree-path = ".worktrees/{{ branch | sanitize }}"

[commit.generation]
command = "MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --safe-mode --setting-sources='user' --system-prompt=''"
```

--------------------------------

### wt hook post-start example output

Source: https://worktrunk.dev/hook

Shows the output of running the post-start hook manually, which runs the post-start project at a specific path.

```console
$ wt hook post-start
◎ Running post-start: project @ ~/acme
```

--------------------------------

### Create user config file

Source: https://worktrunk.dev/config

Creates a user config file with documented examples.

```console
$ wt config create
```

--------------------------------

### Reference task runners in hooks

Source: https://worktrunk.dev/tips-patterns

Use Taskfile, Justfile, or Makefile commands inside hook definitions. The example shows a `pre-start` hook running `task install` and a `pre-merge` hook running `just test lint`.

```toml
[pre-start]
"setup" = "task install"

[pre-merge]
"validate" = "just test lint"
```

--------------------------------

### Install shell integration with wt config shell install

Source: https://worktrunk.dev/config

Installs the shell integration required for Worktrunk to change directories when switching worktrees. Without it, `wt switch` prints the target directory but cannot `cd` into it. For manual setup, see `wt config shell init --help`.

```console
$ wt config shell install

```

--------------------------------

### Pipeline hook: [[post-start]] blocks in order

Source: https://worktrunk.dev/hook

A pipeline hook form runs [[hook]] blocks in order. Each block is one step; multiple keys within a block run concurrently. A failing step aborts the rest of the pipeline. Here install runs first, then build and server run together. Templates are syntax-checked before the pipeline starts and rendered as each step runs, so a step can store per-branch vars that later steps read via {{ vars.<key> }}.

```toml
[[post-start]]
install = "npm ci"

[[post-start]]
build = "npm run build"
server = "npm run dev"
```

--------------------------------

### Single-command hook: pre-start = "npm install"

Source: https://worktrunk.dev/hook

A string hook form runs a single command. Hooks can be defined in .config/wt.toml or ~/.config/worktrunk/config.toml; both use the same format.

```toml
pre-start = "npm install"
```

--------------------------------

### Install Worktrunk with Cargo and install shell integration

Source: https://worktrunk.dev/

Installs Worktrunk using Cargo, then configures shell integration.

```bash
cargo install worktrunk && wt config shell install

```

--------------------------------

### Using worktree_path_of_branch in a template including JSON example

Source: https://worktrunk.dev/hook

Shows how to use the worktree_path_of_branch function in a TOML setup command to copy a config file from the main worktree. Also includes a Python script that reads JSON context to conditionally run a command.

```toml
[pre-start]
# Copy config from main worktree
setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path }}"
```

```python
import json, sys, subprocess
ctx = json.load(sys.stdin)
if ctx.get('branch', '').startswith('feature/') and 'backend' in ctx['repo']:
    subprocess.run(['make', 'seed-db'])
```

--------------------------------

### Post-start hook configuration for dev server

Source: https://worktrunk.dev/step

Example `.config/wt.toml` configuration that runs a dev server via `wt step tether` in a `post-start` hook, automatically torn down when the worktree is removed.

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

--------------------------------

### wt hook pre-merge example output

Source: https://worktrunk.dev/hook

Shows the output of running `wt hook pre-merge` manually, displaying progress and test results for project hooks.

```console
$ wt hook pre-merge
◎ Running pre-merge project:test
  cargo test
    Finished test [unoptimized + debuginfo] target(s) in 0.12s
    Running unittests src/lib.rs (target/debug/deps/worktrunk-abc123)

running 18 tests
test auth::tests::test_jwt_decode ... ok
test auth::tests::test_jwt_encode ... ok
test auth::tests::test_token_refresh ... ok
test auth::tests::test_token_validation ... ok

test result: ok. 18 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.08s
◎ Running pre-merge project:lint
  cargo clippy
    Checking worktrun v0.1.0
    Finished dev [unoptimized + debuginfo] target(s) in 1.23s
```

--------------------------------

### Create and start Claude: wt switch -c -x claude feat vs git worktree add, cd, claude

Source: https://worktrunk.dev/worktrunk

Create a new worktree and start Claude Code in one command with wt switch -c -x claude feat. The plain git equivalent requires three sequential shell commands: git worktree add -b feat ../repo.feat, cd ../repo.feat, then claude.

```plaintext
wt switch -c -x claude feat
```

```bash
git worktree add -b feat ../repo.feat && \
cd ../repo.feat && \
claude
```

--------------------------------

### Install shell integration

Source: https://worktrunk.dev/config

Installs shell integration required for directory switching.

```console
$ wt config shell install
```

--------------------------------

### Install Worktrunk with Pixi and install shell integration

Source: https://worktrunk.dev/

Installs Worktrunk globally with Pixi, then configures shell integration. Community-maintained feedstock.

```bash
pixi global install worktrunk && wt config shell install

```

--------------------------------

### Configure post-start hook to copy gitignored files

Source: https://worktrunk.dev/step

Adds a `[post-start]` hook in `.config/wt.toml` that runs `wt step copy-ignored` after a worktree starts, copying gitignored files from the primary worktree to the new one.

```toml
# .config/wt.toml
[post-start]
copy = "wt step copy-ignored"
```

--------------------------------

### Show all stored state with wt config state get

Source: https://worktrunk.dev/config

Displays all stored state entries, including configuration and log files.

```console
$ wt config state get
```

--------------------------------

### Install Pi plugin

Source: https://worktrunk.dev/claude-code

Installs the activity hook for Pi. Writes to `~/.omp/agent/hooks/pre/worktrunk.ts`. Uninstall with `wt config plugins pi uninstall`.

```bash
wt config plugins pi install
```

--------------------------------

### Custom subcommand execution examples

Source: https://worktrunk.dev/extending

Demonstrates how custom subcommands follow the wt-<name> pattern and how arguments and flags are forwarded to the child process.

```bash
wt sync origin              # runs: wt-sync origin
wt -C /tmp/repo sync        # -C is forwarded as the child's working directory
```

--------------------------------

### wt step rebase examples

Source: https://worktrunk.dev/step

Shows three ways to invoke `wt step rebase`: with no target (default branch), with a branch name, and with a tag.

```console
$ wt step rebase            # Rebase onto default branch
$ wt step rebase develop    # Rebase onto develop
$ wt step rebase v1.2.0     # Rebase onto a tag
```

--------------------------------

### Schema 2 JSON envelope example

Source: https://worktrunk.dev/list

Example of the schema 2 envelope format emitted by `--format=json`. Shows the envelope object with `schema`, `repo`, `collected`, and `items` array, where each item carries independent facts and rendered strings under `display`. Note that `null` is used for requested-but-not-determined values, while absent fields mean not applicable or not requested.

```json
{
  "schema": 2,
  "repo": {
    "default_branch": "main",
    "forge": {"url": "https://github.com/org/repo", "provider": "github",
              "host": "github.com", "owner": "org", "name": "repo", "remote": "origin"}
  },
  "collected": {"ci": false, "summary": false},
  "items": [
    {
      "branch": "feature",
      "head": {"sha": "05a4a45d…", "short_sha": "05a4a45", "subject": "Add login page",
               "committed_at": "2025-01-01T08:00:00Z"},
      "worktree": {"path": "/home/user/repo.feature", "main": false, "current": true,
                   "previous": false, "detached": false, "branch_mismatch": false,
                   "duplicate_branch": false,
                   "changes": {"staged": false, "modified": true, "untracked": false,
                               "renamed": false, "deleted": false, "conflicted": false,
                               "diff": {"added": 10, "deleted": 2}}},
      "default_branch": {"ahead": 3, "behind": 1, "diff": {"added": 50, "deleted": 20},
                         "orphan": false, "integration": null, "merge_conflicts": false},
      "upstream": {"remote": "origin", "branch": "feature", "ahead": 0, "behind": 2},
      "display": {"state": "diverged", "symbols": "!↕", "statusline": "feature …"}
    }
  ]
}
```

--------------------------------

### wt step copy-ignored

Source: https://worktrunk.dev/step

Copies gitignored files from a source worktree to a destination worktree, eliminating cold starts by copying build caches and dependencies. Supports dry-run, force overwrite, and requiring .worktreeinclude.

```APIDOC
## wt step copy-ignored

### Description
Copies gitignored files to another worktree. Eliminates cold starts by copying build caches and dependencies.

### Usage
wt step copy-ignored [OPTIONS]

### Options

#### --from <FROM>
- Type: string
- Optional
- Source worktree branch. Defaults to primary worktree.

#### --to <TO>
- Type: string
- Optional
- Destination worktree branch. Defaults to current worktree.

#### --dry-run
- Type: flag
- Optional
- Show what would be copied.

#### --force
- Type: flag
- Optional
- Overwrite existing files in destination.

#### --require-include
- Type: flag
- Optional
- Require .worktreeinclude to copy anything.

#### --format <FORMAT>
- Type: string
- Optional
- Output format. JSON prints structured result to stdout after the copy completes. Default: text. Possible values: text, json.

#### -h, --help
- Type: flag
- Optional
- Print help (see a summary with '-h').

### Global Options

#### -C <path>
- Type: string
- Optional
- Working directory for this command.

#### --config <path>
- Type: string
- Optional
- User config file path.

#### --config-set <toml>
- Type: string
- Optional
- Override config with inline TOML, e.g. --config-set list.full=true (repeatable).

#### -v, --verbose...
- Type: flag
- Optional
- Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to apply the same level everywhere.

#### -y, --yes
- Type: flag
- Optional
- Skip approval prompts.

```

--------------------------------

### Run a shell command with pipes or redirects via sh -c

Source: https://worktrunk.dev/step

Wraps the command in `sh -c` to support pipes, redirects, variables, or globs. The shell process is the command that gets tethered.

```console
$ wt step tether -- sh -c 'PORT=$P npm run dev | tee dev.log'
```

--------------------------------

### wt step copy-ignored command reference

Source: https://worktrunk.dev/step

Full CLI help output for `wt step copy-ignored`, showing usage, options, and global flags. Use this command to copy gitignored files (e.g., build caches) to another worktree, eliminating cold starts. Options include `--from`, `--to`, `--dry-run`, `--force`, `--require-include`, and `--format` (text or json).

```text
wt step copy-ignored - Copy gitignored files to another worktree

Eliminates cold starts by copying build caches and dependencies.

Usage: wt step copy-ignored [OPTIONS]

Options:
      --from <FROM>
          Source worktree branch

          Defaults to primary worktree.

      --to <TO>
          Destination worktree branch

          Defaults to current worktree.

      --dry-run
          Show what would be copied

      --force
          Overwrite existing files in destination

      --require-include
          Require .worktreeinclude to copy anything

  -h, --help
          Print help (see a summary with '-h')

Automation:
      --format <FORMAT>
          Output format

          JSON prints structured result to stdout after the copy completes.

          [default: text]
          [possible values: text, json]

Global Options:
  -C <path>
          Working directory for this command

      --config <path>
          User config file path

      --config-set <toml>
          Override config with inline TOML, e.g. --config-set list.full=true (repeatable)

  -v, --verbose...
          Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug
          logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to
          apply the same level everywhere — including shell completion, which no flag can reach

  -y, --yes
          Skip approval prompts
```

--------------------------------

### Get database URL from state vars in a shell command

Source: https://worktrunk.dev/tips-patterns

Shows how to retrieve the `db_url` var set by the pipeline and use it as the `DATABASE_URL` environment variable when starting an app.

```bash
DATABASE_URL=$(wt config state vars get db_url) npm start
```

--------------------------------

### Subdomain routing with Caddy worktree config

Source: https://worktrunk.dev/tips-patterns

Configures Caddy subdomain routing for worktrees. The post-start hook starts the dev server on a deterministic port and registers a Caddy route mapping {{ branch | sanitize }}.{{ repo }}.localhost to that port; pre-remove deletes the route; list shows the clean URL. Requires Caddy installed (brew install caddy).

```toml
# .config/wt.toml
[post-start]
server = "wt step tether -- npm run dev -- --port {{ branch | hash_port }}"
proxy = """
  curl -sf --max-time 0.5 http://localhost:2019/config/ || caddy start
  curl -sf http://localhost:2019/config/apps/http/servers/wt || \
    curl -sfX PUT http://localhost:2019/config/apps/http/servers/wt -H 'Content-Type: application/json' \
      -d '{"listen":[":8080"],"automatic_https":{"disable":true},"routes":[]}'
  curl -sf -X DELETE http://localhost:2019/id/wt:{{ repo }}:{{ branch | sanitize }} || true
  curl -sfX PUT http://localhost:2019/config/apps/http/servers/wt/routes/0 -H 'Content-Type: application/json' \
    -d '{"@id":"wt:{{ repo }}:{{ branch | sanitize }}","match":[{"host":["{{ branch | sanitize }}.{{ repo }}.localhost"]}],"handle":[{"handler":"reverse_proxy","upstreams":[{"dial":"127.0.0.1:{{ branch | hash_port }}"}]}]}'
"""

[pre-remove]
proxy = "curl -sf -X DELETE http://localhost:2019/id/wt:{{ repo }}:{{ branch | sanitize }} || true"

[list]
url = "http://{{ branch | sanitize }}.{{ repo }}.localhost:8080"
```

--------------------------------

### wt step rebase command reference

Source: https://worktrunk.dev/step

Full help output for `wt step rebase`, including usage, arguments, options, and global options.

```text
wt step rebase - Rebase onto target

Usage: wt step rebase [OPTIONS] [TARGET]

Arguments:
  [TARGET]
          Target branch, tag, or commit

          Defaults to default branch.

Options:
  -h, --help
          Print help (see a summary with '-h')

Automation:
      --format <FORMAT>
          Output format

          JSON prints structured result to stdout after the rebase completes.

          [default: text]
          [possible values: text, json]

Global Options:
  -C <path>
          Working directory for this command

      --config <path>
          User config file path

      --config-set <toml>
          Override config with inline TOML, e.g. --config-set list.full=true (repeatable)

  -v, --verbose...
          Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug
          logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to
          apply the same level everywhere — including shell completion, which no flag can reach

  -y, --yes
          Skip approval prompts
```

--------------------------------

### Configure dev server per worktree with hash_port and wt step tether

Source: https://worktrunk.dev/tips-patterns

Sets up a post-start hook that runs `npm run dev` on a deterministic port derived from the branch name, and a list URL that shows that port. The `wt step tether` command runs the server in its own process group and tears it down when the worktree is removed.

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

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

--------------------------------

### Run full diagnostics with wt config show --full

Source: https://worktrunk.dev/config

Runs diagnostic checks for CI tool status, commit generation, and version availability. Warnings exit zero; failures are rendered before exiting.

```console
$ wt config show --full
```

--------------------------------

### Install Worktrunk with Conda and install shell integration

Source: https://worktrunk.dev/

Installs Worktrunk from conda-forge using Conda, then configures shell integration. Community-maintained feedstock.

```bash
conda install -c conda-forge worktrunk && wt config shell install

```

--------------------------------

### Install Worktrunk on Arch Linux with pacman and install shell integration

Source: https://worktrunk.dev/

Installs Worktrunk via pacman on Arch Linux, then configures shell integration.

```bash
sudo pacman -S worktrunk && wt config shell install

```

--------------------------------

### Install Worktrunk with Homebrew and install shell integration

Source: https://worktrunk.dev/

Installs Worktrunk via Homebrew on macOS and Linux, then configures shell integration so commands can change directories.

```bash
brew install worktrunk && wt config shell install

```

--------------------------------

### Command reference for wt step for-each

Source: https://worktrunk.dev/step

Full command reference showing usage, arguments, options, and global options. Includes default output format and possible values.

```text
wt step for-each - Run command in each worktree

Executes sequentially with real-time output; continues past command failures.

Usage: wt step for-each [OPTIONS] -- <ARGS>...

Arguments:
  <ARGS>...
          Command template (see --help for all variables)

Options:
      --format <FORMAT>
          Output format

          [default: text]
          [possible values: text, json]

  -h, --help
          Print help (see a summary with '-h')

Global Options:
  -C <path>
          Working directory for this command

      --config <path>
          User config file path

      --config-set <toml>
          Override config with inline TOML, e.g. --config-set list.full=true (repeatable)

  -v, --verbose...
          Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug
          logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to
          apply the same level everywhere — including shell completion, which no flag can reach

  -y, --yes
          Skip approval prompts
```

--------------------------------

### Install Claude Code plugin

Source: https://worktrunk.dev/claude-code

Installs the Worktrunk plugin for Claude Code. The manual equivalent uses `claude plugin marketplace add` and `claude plugin install`. Uninstall with `wt config plugins claude uninstall`.

```bash
wt config plugins claude install
```

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

--------------------------------

### wt config update examples

Source: https://worktrunk.dev/config

These commands preview and apply config migrations, skip confirmation with --yes, or write the migration artifact to a file or stdout. The --output flag omits deprecated approved-commands with a stderr warning; only an in-place update migrates them to approvals.toml.

```console
$ wt config update
```

```console
$ wt config update --yes
```

```console
$ wt config update --output migrated.toml
```

```console
$ wt config update --output=-
```

--------------------------------

### Install Worktrunk on Windows with Winget

Source: https://worktrunk.dev/worktrunk

Installs Worktrunk on Windows via Winget. Because `wt` defaults to Windows Terminal's command, Worktrunk is installed as `git-wt` to avoid conflict. Alternatively, disable Windows Terminal's alias to use `wt` directly.

```bash
winget install max-sixty.worktrunk
git-wt config shell install
```

--------------------------------

### First-run approval prompt for project commands

Source: https://worktrunk.dev/hook

Shown when a project command runs for the first time. Approvals are saved to ~/.config/worktrunk/approvals.toml; if a command changes, a new approval is required. Declining skips every project command for that operation, including already approved ones, and continues without them; saved approvals are unaffected. Use --yes to bypass prompts and --no-hooks to skip hooks (accepted by wt switch, wt merge, wt remove, wt step commit, wt step squash, not by wt hook).

```text
▲ repo needs approval to execute 3 commands:

○ pre-start install:
   npm ci
○ pre-start build:
   cargo build --release
○ pre-start env:
   echo 'PORT={{ branch | hash_port }}' > .env.local

❯ Allow and remember? [y/N]
```

--------------------------------

### Matching several repositories with wildcard keys

Source: https://worktrunk.dev/config

Shows how to match several repositories with one entry using the * wildcard. A key containing * matches any run of characters, including /, so one entry can cover a whole host or namespace. * is the only wildcard; every other character is literal.

```toml
# Every repository on a self-hosted forge whose hostname carries no brand
[projects."git.company.example/*"]
forge.platform = "gitlab"

# Everything under one namespace shares a layout
[projects."git.company.example/platform/*"]
worktree-path = ".worktrees/{{ branch | sanitize }}"
```

--------------------------------

### Show wt list output with per-worktree dev server URLs

Source: https://worktrunk.dev/tips-patterns

Example output of `wt list` showing each worktree's URL column with deterministic ports. The URL dims if the server isn't running.

```console
$ wt list
  Branch       Status      HEAD±     main↕    main…±    Remote⇅  URL                     Commit
@ main           ? ^⇅      +5                            ⇡1  ⇣1  http://localhost:12107  41ee083
+ feature-api  +   ↕⇡     +54   -5   ↑4  ↓1  +234  -24   ⇡3      http://localhost:10703  6814f02
+ fix-auth         ↕|                ↑2  ↓1   +25  -11     |     http://localhost:16460  b772e68
+ fix-typos        _|                                      |     http://localhost:14301  41ee083

○ Showing 4 worktrees, 2 with changes, 2 ahead, hidden: Path, Age, Message
```

--------------------------------

### wt hook command reference

Source: https://worktrunk.dev/hook

Command-line help output for `wt hook`, listing all hook subcommands (show, pre-switch, post-switch, pre-start, post-start, pre-commit, post-commit, pre-merge, post-merge, pre-remove, post-remove) and global options. Use `-h` for a summary, `-C` to set the working directory, `--config` for a user config file, `--config-set` for inline TOML overrides, `-v` for verbose output (with `WORKTRUNK_VERBOSE` environment variable), and `-y` to skip approval prompts.

```text
wt hook - Run configured hooks

Usage: wt hook [OPTIONS] <COMMAND>

Commands:
  show         Show configured hooks
  pre-switch   Run pre-switch hooks
  post-switch  Run post-switch hooks
  pre-start    Run pre-start hooks
  post-start   Run post-start hooks
  pre-commit   Run pre-commit hooks
  post-commit  Run post-commit hooks
  pre-merge    Run pre-merge hooks
  post-merge   Run post-merge hooks
  pre-remove   Run pre-remove hooks
  post-remove  Run post-remove hooks

Options:
  -h, --help
          Print help (see a summary with '-h')

Global Options:
  -C <path>
          Working directory for this command

      --config <path>
          User config file path

      --config-set <toml>
          Override config with inline TOML, e.g. --config-set list.full=true (repeatable)

  -v, --verbose...
          Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug
          logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to
          apply the same level everywhere — including shell completion, which no flag can reach

  -y, --yes
          Skip approval prompts
```
Tokens:
Raw