# wt

> Fast git worktree manager for humans and AI agents. Create, navigate, and clean up worktrees without the ceremony. Built with Bun, Effect TS, @effect/cli, and Ink.

## Install

Requires [Bun](https://bun.sh).

```sh
git clone https://github.com/Junnyyy/wt.git
cd wt
bun install
```

For development (source-linked, changes take effect immediately): `bun run link`
For daily use (compiled binary, faster startup): `bun run install:global`

Both methods install `wt` to `~/.local/bin/`. Make sure it's in your PATH:

```sh
export PATH="$HOME/.local/bin:$PATH"
```

Uninstall: `bun run uninstall` or `rm ~/.local/bin/wt`

## Commands

- `wt add <branch>`: Create a new worktree. Creates it at `.worktrees/<branch>`, symlinks `node_modules` and `.env` files from the main worktree, and runs any configured post-create hook.
- `wt add <branch> --base main`: Create a new branch off a specific base.
- `wt list` (or `wt ls`): List all worktrees with branch name, path, and clean/dirty status.
- `wt cd <branch>`: Outputs the path to a worktree. Designed for shell integration and scripts. Usage: `cd $(wt cd feat-auth)`
- `wt rm <branch>`: Remove a worktree. Fails if uncommitted changes exist.
- `wt rm <branch> -f`: Force remove a worktree.
- `wt prune`: Clean up metadata for worktrees whose directories were deleted manually.

## Interactive TUI

Run `wt` with no arguments in a terminal to launch the interactive TUI.

Keybindings:
- `j/k` or arrow keys: Navigate up/down
- `Enter`: Navigate to the selected worktree
- `d`: Remove a worktree (with confirmation)
- `q`: Quit

When piped or in a non-TTY context, falls back to `wt list`.

## Config (.wt.toml)

Create a `.wt.toml` in your repo root to customize behavior. All settings are optional, sensible defaults apply without it.

```toml
[symlinks]
# Files/directories to symlink from main worktree into new worktrees
patterns = ["node_modules", ".env", ".env.local"]

# Remove specific patterns from the list above (or from defaults)
# exclude = ["node_modules"]

[worktree]
# Directory for worktrees, relative to repo root
dir = ".worktrees"

[hooks]
# Shell command to run after creating a worktree
post_create = "bun install"

# Shell command to run before removing a worktree
pre_remove = ""
```

Defaults (no config needed):
- Symlinked patterns: `node_modules`, `.env`, `.env.local`
- Excluded patterns: none
- Worktree directory: `.worktrees/`
- Post-create hook: none
- Pre-remove hook: none

## Shell Integration

`wt cd` can't change your shell's directory directly. Add this function to your `.zshrc` or `.bashrc`:

```sh
wt() {
  if [ "$1" = "cd" ]; then
    local dir
    dir=$(command wt cd "$2" 2>/dev/null)
    if [ -n "$dir" ]; then
      cd "$dir"
    else
      command wt cd "$2"
    fi
  elif [ $# -eq 0 ]; then
    local dir
    dir=$(command wt)
    if [ -n "$dir" ] && [ -d "$dir" ]; then
      cd "$dir"
    fi
  else
    command wt "$@"
  fi
}
```

Then `wt cd feat-auth` changes your working directory, and bare `wt` lets you navigate interactively.

## For AI Agents

Every command is non-interactive and outputs clean text suitable for scripting:

```sh
# Get worktree path for a branch
path=$(wt cd feat-auth)

# Create a worktree
wt add my-task

# Force remove without prompts
wt rm my-task -f
```

- Non-TTY mode automatically uses plain list output (no TUI)
- All destructive operations use the `-f` flag instead of interactive prompts
- Exit codes: `0` success, non-zero on error

## Links

- [GitHub](https://github.com/Junnyyy/wt)
- [Bun](https://bun.sh)
- [Effect TS](https://effect.website)
- [@effect/cli](https://github.com/Effect-TS/effect/tree/main/packages/cli)
- [Ink](https://github.com/vadimdemedes/ink)