dsisnero/wktrees.cr

# GitHub Repository: dsisnero/wktrees.cr

**URL:** https://github.com/dsisnero/wktrees.cr
**Author:** dsisnero
**Description:** manage git worktrees 
**Homepage:** 
**Language:** Crystal

## Stats
- Stars: 0
- Forks: 0
- Open Issues: 0
- Commits: 149
- Created: 2026-05-29T19:21:49Z
- Updated: 2026-06-22T00:14:24Z
- Pushed: 2026-06-22T00:14:20Z

## README
# wktrees

A CLI for Git worktree management, designed for parallel AI agent workflows.
Crystal port of [worktrunk](https://github.com/max-sixty/worktrunk) (Rust, v0.51.0).

The binary is installed as `wktrees`.

```
wktrees switch <branch>         # switch to a worktree
wktrees switch --create <name>  # create and switch
wktrees switch                   # interactive TUI picker (bubbletea)
wktrees list                     # list worktrees with status
wktrees list --full              # full status with diffs + CI
wktrees list --format=json       # machine-readable JSON
wktrees remove <branch>          # cleanup worktrees
wktrees merge                    # commit, squash, rebase, FF merge
wktrees step commit              # conventional commit with LLM
wktrees step for-each 'cmd'      # run command on every worktree
wktrees config show              # view configuration
wktrees config show --full       # resolved config with defaults
wktrees config approvals add     # pre-approve project hooks
wktrees shell install            # shell integration (bash/zsh/fish/nu/ps)
wktrees -vv list                 # trace all git commands for debugging
wktrees hook show                # display configured hooks
wktrees hook run <type>          # manually trigger hooks
```

## Features

- **Interactive Picker**: Bubbletea TUI with 5 preview modes (diff, log, summary)
- **10 Hook Types**: pre/post-start, pre/post-switch, pre/post-commit, pre/post-merge, pre/post-remove
- **LLM Integration**: Commit messages via Claude/Codex/LLM, branch summaries
- **CI Status**: GitHub Actions, GitLab CI, Azure Pipelines, Gitea (auto-detected)
- **Config System**: User + project TOML with env var overrides and deprecation migration
- **Plugin System**: Custom subcommands via `wktrees-<name>` on PATH or `.work_trees/bin/`
- **Approvals**: Per-project command approval with persistent state
- **Shell Integration**: 5 shells, cd directive protocol, completions
- **Verbose Tracing**: `-vv` shows [wt-trace] records with microsecond timing
- **Template Engine**: 9 filters with `{{ var | filter(args) }}` syntax

## Installation

```bash
# Clone and build
git clone https://github.com/dsisnero/wktrees.git
cd wktrees
make install    # shards install
make build      # → bin/wktrees

# Optional: install to PATH
cp bin/wktrees /usr/local/bin/
```

## Shell Integration

**Required for `wktrees switch` to change your directory.**

A program cannot change its parent shell's working directory — `chdir()` only
affects the `wktrees` process, which then exits, leaving your shell where it
was. (This is why `cd` is a shell builtin, and why tools like `zoxide`,
`direnv`, and `fzf` all need a shell hook.) So `wktrees switch` writes the
target path to a temp file (`WORKTRUNK_DIRECTIVE_CD_FILE`); a small **shell
wrapper function** — running *inside* your shell — reads it and does the `cd`.

```bash
# Install (adds the wrapper function to your shell rc file)
wktrees shell install

# Restart your shell or re-source the rc file
source ~/.zshrc   # or ~/.bashrc
```

Or eval it directly in your rc file (bash/zsh/fish/nu/ps supported):

```bash
eval "$(wktrees shell init zsh)"
```

**Without shell integration**, `wktrees switch` still creates/locates the
worktree, but cannot move you into it — it prints the target path and a warning
instead:

```
▲ Worktree for <branch> @ <path>, but cannot change directory — shell integration not installed
↳ To change directory, run wktrees switch <branch>
```

`wktrees list` marks the current worktree (`@`) based on your shell's current
directory, so until the `cd` actually happens it will keep showing your old
worktree.

## Development

```bash
make install       # install dependencies (shards install)
make update        # update dependencies (shards update)
make build         # compile binary → bin/wktrees
make format        # format code
make lint          # lint code (ameba)
make test          # run specs (675 examples)
make clean         # remove build artifacts
```

Tests: 675 specs, 0 failures. Requires Crystal >= 1.20.2.

### Dependencies

- [crystal-community/toml.cr](https://github.com/crystal-community/toml.cr) — TOML config parsing
- [dsisnero/lipgloss](https://github.com/dsisnero/lipgloss) — Terminal styling (ANSI, borders, tables)
- [dsisnero/bubbles](https://github.com/dsisnero/bubbles) — TUI components (bubbletea framework)

## Contributing

1. Fork it (<https://github.com/dsisnero/wktrees/fork>)
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request

## Contributors

- [Dominic Sisneros](https://github.com/dsisnero) - creator and maintainer