Wktrees

wktrees

Help users work with wktrees, a CLI tool for managing git worktrees. Crystal port of worktrunk (Rust, v0.51.0).

Available Documentation

Reference files are maintained in this repository:

• plans/parity.md: Port status and feature parity tracking
• plans/interactive_picker.md: Bubbletea TUI interactive picker architecture
• plans/plugins.md: Plugin system architecture (two-tier: config hooks + custom subcommands)
• plans/cli_research.md: clip vs clim CLI framework comparison (conclusion: keep OptionParser)
• docs/architecture.md: Source tree layout, design decisions, divergences
• docs/development.md: Development workflow, coding guidelines

Two Types of Configuration

wktrees uses two separate config files with different scopes and behaviors:

User Config (~/.config/worktrees/config.toml)

• Scope: Personal preferences for the individual developer
• Location: ~/.config/worktrees/config.toml (never checked into git)
• Contains: LLM integration, worktree path templates, command settings, user hooks, approved commands
• Permission model: Always propose changes and get consent before editing

Project Config (.config/wt.toml)

• Scope: Team-wide automation shared by all developers
• Location: /.config/wt.toml (checked into git)
• Contains: Hooks for worktree lifecycle (pre-start, pre-merge, etc.)
• Permission model: Proactive (create directly, changes are reversible via git)

Determining Which Config to Use

When a user asks for configuration help, determine which type based on:

User config indicators:

• "set up LLM" or "configure commit generation"
• "change where worktrees are created"
• "customize commit message templates"
• Affects only their environment

Project config indicators:

• "set up hooks for this project"
• "automate npm install"
• "run tests before merge"
• Affects the entire team

Both configs may be needed: For example, setting up commit message generation requires user config, but automating quality checks requires project config.

Core Workflows

Setting Up Commit Message Generation (User Config)

1. Detect available tools

``bash which claude codex llm aichat 2>/dev/null ``

1. If none installed, recommend Claude Code (already available in Claude Code sessions)

1. Propose config change

``toml [commit.generation] command = "llm -m haiku" # or claude, codex, etc. `` Ask: "Should I add this to your config?"

1. After approval, apply

• Check if config exists: wktrees config show
• If not, guide through wktrees config create
• Read, modify, write preserving structure

1. Suggest testing

``bash wktrees step commit --show-prompt # verify prompt builds ``

Setting Up Project Hooks (Project Config)

Common request for workflow automation. Follow discovery process:

1. Detect project type

``bash ls package.json Cargo.toml pyproject.toml ``

1. Identify available commands

• For npm: Read package.json scripts
• For Rust: Common cargo commands
• For Python: Check pyproject.toml

1. Design appropriate hooks (10 hook types available)

• Dependencies (fast, must complete) → pre-start
• Tests/linting (must pass) → pre-commit or pre-merge
• Long builds, dev servers → post-start
• Terminal/IDE updates → post-switch
• Deployment → post-merge
• Cleanup tasks → pre-remove

1. Validate commands work

``bash npm run lint # verify exists which cargo # verify tool exists ``

1. Create .config/wt.toml

```toml # Install dependencies when creating worktrees pre-start = "npm install"

# Validate code quality before committing [pre-commit] lint = "npm run lint" typecheck = "npm run typecheck"

# Run tests before merging pre-merge = "npm test" ```

1. Add comments explaining choices

1. Suggest testing

``bash wktrees switch --create test-hooks ``

Adding Hooks to Existing Config

When users want to add automation to an existing project:

1. Read existing config: cat .config/wt.toml

1. Determine hook type - When should this run?

• Creating worktree (blocking) → pre-start
• Creating worktree (background) → post-start
• Every switch → post-switch
• Before committing → pre-commit
• Before merging → pre-merge
• After merging → post-merge
• Before removal → pre-remove

1. Handle format conversion if needed

Single command to named table: ```toml # Before pre-start = "npm install"

# After (adding migrate) [pre-start] install = "npm install" migrate = "npm run db:migrate" ```

1. Preserve existing structure and comments

Validation Before Adding Commands

Before adding hooks, validate:

# Verify command exists
which npm
which cargo

# For npm, verify script exists
npm run lint --dry-run

# For shell commands, check syntax
bash -n -c "if [ true ]; then echo ok; fi"

Dangerous patterns — Warn users before creating hooks with:

• Destructive commands: rm -rf, DROP TABLE
• External dependencies: curl http://...
• Privilege escalation: sudo

Permission Models

User Config: Conservative

• Never edit without consent - Always show proposed change and wait for approval
• Never install tools - Provide commands for users to run themselves
• Preserve structure - Keep existing comments and organization
• Validate first - Ensure TOML is valid before writing

Project Config: Proactive

• Create directly - Changes are versioned, easily reversible
• Validate commands - Check commands exist before adding
• Explain choices - Add comments documenting why hooks exist
• Warn on danger - Flag destructive operations before adding

Key Commands

# View all configuration
wktrees config show
wktrees config create
wktrees --help
wktrees list --full
wktrees switch 
wktrees switch --create 
wktrees merge
wktrees hook run 
wktrees step commit
wktrees step diff
wktrees step for-each ''

Hook Approvals in Non-Interactive Sessions

Project hooks and project aliases prompt for approval on first run, so an untrusted .config/wt.toml can't silently execute arbitrary commands. Agents running wktrees merge, wktrees switch, or other commands that trigger hooks will hit an error like:

▲ cargo-difftest needs approval to execute 1 command:
○ post-merge install:
  cargo install --path .
✗ Cannot prompt for approval in non-interactive environment
↳ To skip prompts in CI/CD, add --yes; to pre-approve commands, run wktrees config approvals add

Two resolutions exist — pick based on who the agent is running for:

• wktrees config approvals add — interactive prompt that stores approvals to ~/.config/worktrees/approvals.toml. Run once per project; persists across invocations until the command template changes or the project moves. This is the right choice when the human owns the trust decision.
• --yes / -y — bypasses approval for a single invocation. Appropriate for CI/CD where hook contents are controlled by the pipeline itself.

When invoked as an agent, stop and escalate to the user — pre-approval is a security decision about whether this project's hooks should be trusted to run arbitrary commands on their machine. Tell the user to run wktrees config approvals add (or review and re-run with --yes if they accept the CI-style one-shot bypass). Don't reach for --yes on the user's behalf just to unblock the command.

Advanced: Agent Handoffs

When the user requests spawning a worktree with an agent in a background session ("spawn a worktree for...", "hand off to another agent"), use the appropriate pattern for their terminal multiplexer. Substitute ` with the CLI you are running as: claude for Claude Code, 'opencode run'` for OpenCode.

tmux (check $TMUX env var):

tmux new-session -d -s  "wktrees switch --create  -x  -- ''"

Zellij (check $ZELLIJ env var):

zellij run -- wktrees switch --create  -x  -- ''

Requirements (all must be true):

• User explicitly requests spawning/handoff
• User is in a supported multiplexer (tmux or Zellij)
• The user's project instructions (CLAUDE.md or AGENTS.md) or an explicit prompt authorize this pattern

Do not use this pattern for normal worktree operations.

Example (tmux, Claude Code):

tmux new-session -d -s fix-auth-bug "wktrees switch --create fix-auth-bug -x claude -- \
  'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'"

Parallel sub-Agents (single Claude Code session)

To spawn multiple sub-Agents that each work in their own worktree from one Claude Code session — no terminal multiplexer, no human in the other pane — pre-create each worktree from the parent and pass the path into the sub-Agent prompt:

wktrees switch --create  --no-cd --no-hooks

Then call the Agent tool without isolation: "worktree", naming the path in the prompt:

You are working in /abs/path/to/worktrunk. on branch ``.
All edits must stay in that worktree.

--no-cd skips the shell-integration cd script the parent can't consume; --no-hooks is appropriate when each sub-Agent will run its own build/test step and you don't need post-start setup repeated per worktree.

Do not use Agent { isolation: "worktree" } for this. Pre-creating with wktrees switch --create keeps path, branch, and hook target aligned.

Source & license

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

• Author: dsisnero
• Source: dsisnero/wktrees.cr
• License: MIT

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