Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

Change shell code blocks to console

Maximilian Roos7f238d3bb8f8
diff --git a/.claude-plugin/skills/worktrunk/SKILL.md b/.claude-plugin/skills/worktrunk/SKILL.md
index 07f2bb5ea..7c903a2a7 100644
--- a/.claude-plugin/skills/worktrunk/SKILL.md
+++ b/.claude-plugin/skills/worktrunk/SKILL.md
@@ -58,17 +58,17 @@ When a user asks for configuration help, determine which type based on:
Most common request. Follow this sequence:
1. **Check if LLM tool exists**
- ```bash
+ ```console
which llm # or: which aichat
```
2. **If not installed, guide installation (don't run it)**
- ```bash
+ ```console
uv tool install -U llm
```
3. **Guide API key setup (don't run it)**
- ```bash
+ ```console
llm install llm-anthropic
llm keys set anthropic
llm models default claude-3.5-sonnet
@@ -87,7 +87,7 @@ Most common request. Follow this sequence:
- Read, modify, write preserving structure
6. **Suggest testing**
- ```bash
+ ```console
llm "say hello"
wt merge # in a repo with uncommitted changes
```
@@ -99,7 +99,7 @@ Most common request. Follow this sequence:
Common request for workflow automation. Follow discovery process:
1. **Detect project type**
- ```bash
+ ```console
ls package.json Cargo.toml pyproject.toml
```
@@ -114,7 +114,7 @@ Common request for workflow automation. Follow discovery process:
- Long builds → `post-start-command`
4. **Validate commands work**
- ```bash
+ ```console
npm run lint # verify exists
which cargo # verify tool exists
```
@@ -134,7 +134,7 @@ Common request for workflow automation. Follow discovery process:
6. **Add comments explaining choices**
7. **Suggest testing**
- ```bash
+ ```console
wt switch --create test-hooks
```
@@ -171,7 +171,7 @@ Common request for workflow automation. Follow discovery process:
## Key Commands
-```bash
+```console
# View all configuration
wt config list
@@ -189,7 +189,7 @@ Load **reference/README.md** for general features, installation, commands, and e
Load **reference files** for detailed configuration, hook specifications, and troubleshooting.
Find specific sections with grep:
-```bash
+```console
grep -A 20 "## Installation" reference/README.md
grep -A 20 "## LLM Setup" reference/user-config.md
grep -A 30 "### post-create-command" reference/project-config.md
diff --git a/.claude-plugin/skills/worktrunk/reference/project-config.md b/.claude-plugin/skills/worktrunk/reference/project-config.md
index de47cd907..b8f7a1a92 100644
--- a/.claude-plugin/skills/worktrunk/reference/project-config.md
+++ b/.claude-plugin/skills/worktrunk/reference/project-config.md
@@ -18,7 +18,7 @@ When users say "set up some hooks for me", follow this discovery process:
### Step 1: Detect Project Type
Check for package manifests:
-```bash
+```console
ls package.json Cargo.toml pyproject.toml pom.xml go.mod
```
@@ -27,7 +27,7 @@ ls package.json Cargo.toml pyproject.toml pom.xml go.mod
<example type="detecting-npm-scripts">
For npm projects, read `package.json`:
-```bash
+```console
cat package.json | grep -A 20 '"scripts"'
```
@@ -57,7 +57,7 @@ Match hooks to project needs using this decision tree:
### Step 4: Validate Commands Work
Before adding to config, check:
-```bash
+```console
npm run lint # Check script exists
which cargo # Check tool exists
```
@@ -115,7 +115,7 @@ pre-commit-command = ["npm run lint", "npm run typecheck"]
### Step 7: Suggest Testing
-```bash
+```console
# Create a test worktree to verify hooks work
wt switch --create test-hooks
```
@@ -126,7 +126,7 @@ When users want to add automation to an existing project:
### Step 1: Read Existing Config
-```bash
+```console
cat .config/wt.toml
```
@@ -381,7 +381,7 @@ Check commands are safe and exist:
<example type="validation-checks">
-```bash
+```console
# Verify command exists
which npm
which cargo
@@ -446,7 +446,7 @@ post-start-command = "npm run build" # Slow, background
## Key Commands
-```bash
+```console
wt config list # View project config
cat .config/wt.toml # Read config directly
wt switch --create test-hooks # Test hooks work
diff --git a/.claude-plugin/skills/worktrunk/reference/user-config.md b/.claude-plugin/skills/worktrunk/reference/user-config.md
index 0554bed4e..ff51168f8 100644
--- a/.claude-plugin/skills/worktrunk/reference/user-config.md
+++ b/.claude-plugin/skills/worktrunk/reference/user-config.md
@@ -18,7 +18,7 @@ Most users want this for LLM commit messages. Follow this sequence:
### Step 1: Check if LLM Tool Exists
-```bash
+```console
which llm
# or
which aichat
@@ -29,12 +29,12 @@ which aichat
<example type="llm-install-guide">
For `llm` (Python-based, recommended):
-```bash
+```console
uv tool install -U llm
```
For `aichat` (Rust-based, 20+ providers):
-```bash
+```console
# See: https://github.com/sigoden/aichat
```
@@ -45,7 +45,7 @@ For `aichat` (Rust-based, 20+ providers):
<example type="api-key-setup">
For Claude (via llm):
-```bash
+```console
llm install llm-anthropic
llm keys set anthropic
# User pastes API key from: https://console.anthropic.com/settings/keys
@@ -53,7 +53,7 @@ llm models default claude-3.5-sonnet
```
For OpenAI (via llm):
-```bash
+```console
llm keys set openai
# User pastes API key from: https://platform.openai.com/api-keys
```
@@ -77,7 +77,7 @@ Ask: "Should I add this to your config at `~/.config/worktrunk/config.toml`?"
### Step 5: After Approval, Check if Config Exists
-```bash
+```console
wt config list
```
@@ -89,7 +89,7 @@ Read existing config, add the `[commit-generation]` section, preserve existing s
### Step 7: Suggest Testing
-```bash
+```console
# Test LLM works
llm "say hello"
@@ -257,7 +257,7 @@ command = "npm install"
## Key Commands
-```bash
+```console
wt config list # View current config
wt config create # Create initial config file
wt config --help # Show LLM setup guide
diff --git a/CLAUDE.md b/CLAUDE.md
index 85c1bb6a4..61c784485 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -36,7 +36,7 @@ fn parse_config() { ... }
### Running Tests
-```bash
+```console
# Unit tests (fast, ~200 tests)
cargo test --lib --bins
@@ -58,7 +58,7 @@ The pre-merge hook runs the full test suite and is the recommended way to verify
When working in Claude Code web, run the setup script first:
-```bash
+```console
./dev/setup-claude-code-web.sh
```
@@ -515,7 +515,7 @@ Use `--force` to skip interactive prompts in tests. Don't pipe input to stdin.
### Running Benchmarks Selectively
Run specific benchmarks by name to skip expensive ones:
-```bash
+```console
cargo bench --bench list bench_list_by_worktree_count
cargo bench --bench completion
```
diff --git a/README.md b/README.md
index 30d2a7933..af50a93b2 100644
--- a/README.md
+++ b/README.md
@@ -32,7 +32,7 @@ List worktrees, create a worktree, make a trivial change, merge the change:
<!-- README:snapshot:tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_simple_switch.snap -->
-```bash
+```console
$ wt switch --create fix-auth
✅ Created new worktree for fix-auth from main at ../repo.fix-auth
```
@@ -45,7 +45,7 @@ $ wt switch --create fix-auth
<!-- README:snapshot:tests/snapshots/integration__integration_tests__merge__readme_example_simple.snap -->
-```bash
+```console
$ wt merge
🔄 Merging 1 commit to main @ a1b2c3d (no commit/squash/rebase needed)
* a1b2c3d Implement JWT validation
@@ -63,7 +63,7 @@ See [`wt merge`](#wt-merge) for all options.
<!-- README:snapshot:tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snap -->
-```bash
+```console
$ wt list
Branch Status HEAD± main↕ Path Remote⇅ Commit Age Message
@ main ^ ./test-repo ↑0 ↓0 b834638e 10mo Initial commit
@@ -79,7 +79,7 @@ See [`wt list`](#wt-list) for all options.
## Installation
-```bash
+```console
cargo install worktrunk
wt config shell install # Sets up shell integration
```
@@ -126,7 +126,7 @@ Then `wt merge` will generate commit messages automatically:
<!-- README:snapshot:tests/snapshots/integration__integration_tests__merge__readme_example_complex.snap -->
-```bash
+```console
$ wt merge
🔄 Squashing 3 commits into a single commit (3 files, +33)...
🔄 Generating squash commit message...
@@ -191,7 +191,7 @@ Automate tasks at different points in the worktree lifecycle. Configure hooks in
<!-- README:snapshot:tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_hooks_post_create.snap -->
-```bash
+```console
$ wt switch --create feature-x
🔄 Running post-create install:
uv sync
@@ -210,7 +210,7 @@ $ wt switch --create feature-x
<!-- README:snapshot:tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_hooks_pre_merge.snap -->
-```bash
+```console
$ wt merge
🔄 Squashing 3 commits into a single commit (2 files, +45)...
🔄 Generating squash commit message...
@@ -257,7 +257,7 @@ Worktrunk requires shell integration in order to switch directories, during `wt
switch` & `wt merge`/`wt remove`. To add automatic setup to shell config files
(Bash, Zsh, and Fish):
-```bash
+```console
wt config shell install
```
@@ -269,13 +269,13 @@ For manual setup instructions, see `wt config shell --help`.
new agent-in-worktree in a couple of seconds. For example, to create a worktree
and immediately start Claude:
-```bash
+```console
alias wsl='wt switch --create --execute=claude'
```
Then:
-```bash
+```console
wsl new-feature
```
@@ -402,37 +402,37 @@ See `wt config approvals --help`.
Switch to existing worktree:
-```bash
+```console
wt switch feature-branch
```
Create new worktree from main:
-```bash
+```console
wt switch --create new-feature
```
Switch to previous worktree:
-```bash
+```console
wt switch -
```
Create from specific base:
-```bash
+```console
wt switch --create hotfix --base production
```
Create and run command:
-```bash
+```console
wt switch --create docs --execute "code ."
```
Skip hooks during creation:
-```bash
+```console
wt switch --create temp --no-verify
```
@@ -440,7 +440,7 @@ wt switch --create temp --no-verify
Use `@` for current HEAD, `-` for previous, `^` for main:
-```bash
+```console
wt switch @ # Switch to current branch's worktree
wt switch - # Switch to previous worktree
wt switch --create new-feature --base=^ # Branch from main (default)
@@ -537,25 +537,25 @@ See `wt config approvals --help`.
Basic merge to main:
-```bash
+```console
wt merge
```
Merge without squashing:
-```bash
+```console
wt merge --no-squash
```
Keep worktree after merging:
-```bash
+```console
wt merge --no-remove
```
Skip all hooks:
-```bash
+```console
wt merge --no-verify
```
@@ -619,37 +619,37 @@ Stops any git fsmonitor daemon for the worktree before removal. This prevents or
Remove current worktree and branch:
-```bash
+```console
wt remove
```
Remove specific worktree and branch:
-```bash
+```console
wt remove feature-branch
```
Remove worktree but keep branch:
-```bash
+```console
wt remove --no-delete-branch feature-branch
```
Remove multiple worktrees:
-```bash
+```console
wt remove old-feature another-branch
```
Remove in foreground (blocking):
-```bash
+```console
wt remove --no-background feature-branch
```
Switch to default in main:
-```bash
+```console
wt remove # (when already in main worktree)
```
@@ -759,7 +759,7 @@ Note: `locked` and `prunable` are top-level fields on worktree objects, not in s
**Query examples:**
-```bash
+```console
# Find worktrees with conflicts
jq '.[] | select(.status.branch_state == "Conflicts")'
@@ -808,19 +808,19 @@ Options:
1. Set up shell integration
- ```bash
+ ```console
wt config shell install
```
Or manually add to your shell config:
- ```bash
+ ```console
eval "$(wt config shell init bash)"
```
2. (Optional) Create config file
- ```bash
+ ```console
wt config create
```
@@ -841,7 +841,7 @@ Options:
For Claude:
-```bash
+```console
llm install llm-anthropic
llm keys set anthropic
llm models default claude-3.5-sonnet
@@ -849,7 +849,7 @@ llm models default claude-3.5-sonnet
For OpenAI:
-```bash
+```console
llm keys set openai
```
@@ -906,7 +906,7 @@ Options:
By default, worktrees live as siblings to the main repo (`myapp.feature-x/`).
-```bash
+```console
wt config list # Show all config files and locations
wt config create # Create global config with examples
wt config --help # Show setup guide, file locations, and options
@@ -918,7 +918,7 @@ wt config --help # Show setup guide, file locations, and options
Add emoji status markers to branches that appear in `wt list`.
-```bash
+```console
# Set status for current branch
wt config status set "🤖"
@@ -930,7 +930,7 @@ git config worktrunk.status.feature-x "💬"
<!-- README:snapshot:tests/snapshots/integration__integration_tests__list__with_user_status.snap -->
-```bash
+```console
$ wt list
Branch Status HEAD± main↕ Path Remote⇅ Commit Age Message
@ main ^ ./test-repo b834638e 10mo Initial commit
@@ -959,7 +959,7 @@ When using Claude:
<!-- README:snapshot:tests/snapshots/integration__integration_tests__list__with_user_status.snap -->
-```bash
+```console
$ wt list
Branch Status HEAD± main↕ Path Remote⇅ Commit Age Message
@ main ^ ./test-repo b834638e 10mo Initial commit
@@ -1044,7 +1044,7 @@ Worktrunk gives each branch its own directory with independent build caches, pro
Git's built-in worktree commands work but require manual lifecycle management:
-```bash
+```console
# Plain git worktree workflow
git worktree add -b feature-branch ../myapp-feature main
cd ../myapp-feature
@@ -1057,7 +1057,7 @@ git branch -d feature-branch
Worktrunk automates the full lifecycle:
-```bash
+```console
wt switch --create feature-branch # Creates worktree, runs setup hooks
# ...work...
wt merge # Squashes, merges, removes worktree
@@ -1092,7 +1092,7 @@ Git TUIs operate on a single repository. Worktrunk manages multiple worktrees, r
If you encounter errors related to tree-sitter or C compilation (like "error: 'for' loop initial declarations are only allowed in C99 mode" or "undefined reference to le16toh"), install without syntax highlighting:
-```bash
+```console
cargo install worktrunk --no-default-features
```
@@ -1124,7 +1124,7 @@ cargo test --test integration --features shell-integration-tests
Use [cargo-release](https://github.com/crate-ci/cargo-release) to publish new versions:
-```bash
+```console
cargo install cargo-release
# Bump version, update Cargo.lock, commit, tag, and push
diff --git a/benches/CLAUDE.md b/benches/CLAUDE.md
index 30d2689c8..f25a19c43 100644
--- a/benches/CLAUDE.md
+++ b/benches/CLAUDE.md
@@ -2,7 +2,7 @@
## Quick Start
-```bash
+```console
# Run fast synthetic benchmarks (skip slow ones)
cargo bench --bench list -- --skip cold --skip real
@@ -44,7 +44,7 @@ The rust-lang/rust repository is automatically cached:
## Faster Iteration During Development
### Option 1: Skip Slow Benchmarks
-```bash
+```console
# Skip cold cache and real repo benchmarks
cargo bench --bench list -- --skip cold --skip real
@@ -53,7 +53,7 @@ cargo bench --bench list bench_list_by_worktree_count
```
### Option 2: Use Pattern Matching
-```bash
+```console
# Run all benchmarks with "list_by" in the name
cargo bench --bench list "list_by"
diff --git a/dev/wt-demo/CLAUDE.md b/dev/wt-demo/CLAUDE.md
index 473882dfb..5ffe7cc4a 100644
--- a/dev/wt-demo/CLAUDE.md
+++ b/dev/wt-demo/CLAUDE.md
@@ -4,7 +4,7 @@
Build and record the demo GIF:
-```bash
+```console
python3 dev/wt-demo-build.py
```
diff --git a/src/cli.rs b/src/cli.rs
index 9af1b42e8..a8a910dbe 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -146,7 +146,7 @@ pub enum ConfigShellCommand {
Add one line to your shell config:
Bash (~/.bashrc):
-```bash
+```console
eval "$(wt config shell init bash)"
```
@@ -158,7 +158,7 @@ wt config shell init fish | source
Zsh (~/.zshrc):
```zsh
eval "$(wt config shell init zsh)"
-```bash
+```console
## Auto Setup
@@ -173,17 +173,17 @@ Use `wt config shell install` to automatically add to your shell config."#)]
#[command(after_long_help = r#"## Auto Setup
Detects existing shell config files and adds integration:
-```bash
+```console
wt config shell install
```
Install for specific shell only:
-```bash
+```console
wt config shell install zsh
```
Skip confirmation prompt:
-```bash
+```console
wt config shell install --force
```"#)]
Install {
@@ -200,17 +200,17 @@ wt config shell install --force
#[command(after_long_help = r#"## Removal
Removes shell integration lines from config files:
-```bash
+```console
wt config shell uninstall
```
Remove from specific shell only:
-```bash
+```console
wt config shell uninstall zsh
```
Skip confirmation prompt:
-```bash
+```console
wt config shell uninstall --force
```
@@ -234,7 +234,7 @@ Detects various forms of the integration pattern regardless of:
Generate completions for your shell:
-```bash
+```console
wt config shell completions zsh > ~/.zfunc/_wt
```
@@ -346,17 +346,17 @@ commands.
## Examples
Pre-approve all commands for current project:
-```bash
+```console
wt config approvals ask
```
Clear approvals for current project:
-```bash
+```console
wt config approvals clear
```
Clear global approvals:
-```bash
+```console
wt config approvals clear --global
```"#)]
Approvals {
@@ -518,19 +518,19 @@ pub enum Commands {
1. Set up shell integration
- ```bash
+ ```console
wt config shell install
```
Or manually add to your shell config:
- ```bash
+ ```console
eval "$(wt config shell init bash)"
```
2. (Optional) Create config file
- ```bash
+ ```console
wt config create
```
@@ -551,7 +551,7 @@ pub enum Commands {
For Claude:
-```bash
+```console
llm install llm-anthropic
llm keys set anthropic
llm models default claude-3.5-sonnet
@@ -559,7 +559,7 @@ llm models default claude-3.5-sonnet
For OpenAI:
-```bash
+```console
llm keys set openai
```
@@ -667,7 +667,7 @@ Note: `locked` and `prunable` are top-level fields on worktree objects, not in s
**Query examples:**
-```bash
+```console
# Find worktrees with conflicts
jq '.[] | select(.status.branch_state == \"Conflicts\")'
@@ -757,37 +757,37 @@ See `wt config approvals --help`.
Switch to existing worktree:
-```bash
+```console
wt switch feature-branch
```
Create new worktree from main:
-```bash
+```console
wt switch --create new-feature
```
Switch to previous worktree:
-```bash
+```console
wt switch -
```
Create from specific base:
-```bash
+```console
wt switch --create hotfix --base production
```
Create and run command:
-```bash
+```console
wt switch --create docs --execute "code ."
```
Skip hooks during creation:
-```bash
+```console
wt switch --create temp --no-verify
```
@@ -795,7 +795,7 @@ wt switch --create temp --no-verify
Use `@` for current HEAD, `-` for previous, `^` for main:
-```bash
+```console
wt switch @ # Switch to current branch's worktree
wt switch - # Switch to previous worktree
wt switch --create new-feature --base=^ # Branch from main (default)
@@ -859,37 +859,37 @@ Stops any git fsmonitor daemon for the worktree before removal. This prevents or
Remove current worktree and branch:
-```bash
+```console
wt remove
```
Remove specific worktree and branch:
-```bash
+```console
wt remove feature-branch
```
Remove worktree but keep branch:
-```bash
+```console
wt remove --no-delete-branch feature-branch
```
Remove multiple worktrees:
-```bash
+```console
wt remove old-feature another-branch
```
Remove in foreground (blocking):
-```bash
+```console
wt remove --no-background feature-branch
```
Switch to default in main:
-```bash
+```console
wt remove # (when already in main worktree)
```"#)]
Remove {
@@ -952,25 +952,25 @@ See `wt config approvals --help`.
Basic merge to main:
-```bash
+```console
wt merge
```
Merge without squashing:
-```bash
+```console
wt merge --no-squash
```
Keep worktree after merging:
-```bash
+```console
wt merge --no-remove
```
Skip all hooks:
-```bash
+```console
wt merge --no-verify
```"#)]
Merge {
diff --git a/src/commands/CLAUDE.md b/src/commands/CLAUDE.md
index cd7cd50f2..3cacf02ac 100644
--- a/src/commands/CLAUDE.md
+++ b/src/commands/CLAUDE.md
@@ -6,7 +6,7 @@ When debugging TUI commands like `wt beta select`, use the `tmux-cli` skill (pre
### 1. Create Test Environment
-```bash
+```console
cargo run --bin setup-select-test
```
@@ -18,7 +18,7 @@ This creates a reproducible test repo at `/tmp/wt-select-test/test-repo`.
Load the `tmux-cli` skill, then use the `tmux-cli` tool. Install if needed: `uv tool install claude-code-tools` (requires tmux).
-```bash
+```console
# Launch shell in test repo
pane=$(tmux-cli launch "zsh")
tmux-cli send "cd /tmp/wt-select-test/test-repo" --pane=$pane
@@ -60,7 +60,7 @@ mcp__node-terminal__terminal_read({ sessionId: "test" })
### 3. Analyze Logs
-```bash
+```console
tail -100 debug.log | grep -E "error|hang|stuck"
```
@@ -69,7 +69,7 @@ tail -100 debug.log | grep -E "error|hang|stuck"
- **`-C <path>`**: Set working directory (alternative to `cd`)
- **`--source`**: Use local source (only needed with installed `wt`, not with `cargo run`)
-```bash
+```console
# Testing with cargo run (already uses local source):
cargo run --quiet -- -C /path/to/repo beta select