Worktee

wtt is a Git worktree manager: index worktrees, fast interactive fuzzy switching and a full-screen dashboard, creates managed worktrees, and plans removals and pruning without weakening Git safety checks.

Install

WTT requires Git and a Rust toolchain. Install the published crate with:

cargo install worktee

To install the current source checkout instead, run cargo install --path . --locked from the repository root.

Both methods install the wtt binary. GitHub pull-request status is optional and uses the authenticated gh CLI; all local worktree features continue to work without it.

Quick start

Run WTT and follow the setup wizard. It creates an editable, commented configuration and asks which folders contain your Git repositories:

wtt

WTT starts the daemon automatically. Wait for the initial scan, then inspect the index:

wtt scan --wait
wtt list --all

Shell integration

Plug into your configuration

wtt shell init <bash|fish|zsh> # required for the switcher to work

wtt shell completions <bash|fish|zsh> # optional

St

wtt switch
wtt tui

wtt switch opens the compact picker. wtt tui opens Mission, the full-screen global inventory.

Everyday workflows

Find and switch worktrees

Inside a Git repository, commands default to that repository. Outside Git, they use the global index. Pass --all when you explicitly want global scope.

wtt list
wtt list --filter 'feature state:clean'
wtt list --all --repo api --sort updated
wtt list --all --json

wtt switch feature
wtt switch --all feature
wtt switch                         # interactive picker

Filters accept fuzzy text and structured qualifiers including repo:, wt:, branch:, state:, pr:, repo-pr:, ci:, fresh:, and hide:. The CLI, picker, and dashboard share the same query semantics.

Switching requires the generated shell wrapper because a child process cannot change its parent shell's directory. Without the wrapper, the picker remains browsable but accepting a destination fails with installation guidance.

Create worktrees

Create and enter a managed sibling worktree through shell integration:

wtt switch --create feature-new-ui --new-branch feature/new-ui
wtt switch --create hotfix --branch release

Use create when the calling shell should stay where it is:

wtt create investigation --detach HEAD~3
wtt create feature-api --new-branch feature/api

Use the Mission dashboard

wtt tui

Mission is the global repository and worktree inventory. It starts with a focused view of active worktrees. Use Show all or clear the filter chips to reveal the complete index.

Use ctrl-P to reveal actions and shortkeys, further configurable through the config file.

Remove and prune safely

Prune worktrees matching certain criteria with wtt prune.

• See --help for filters and options.
• Supports --dry-run

Configuration and daemon operation

Default paths follow XDG conventions on Linux and macOS:

• configuration: $XDG_CONFIG_HOME/wtt/config.toml, normally ~/.config/wtt/config.toml;
• state and index: $XDG_STATE_HOME/wtt, normally ~/.local/state/wtt.

Relative XDG values are ignored. Global --config and --database options override the defaults.

The daemon owns filesystem discovery and provider synchronization. Snapshot readers such as list, switching, completion, and the dashboard remain responsive and never start a filesystem scan themselves.

wtt doctor performs read-only checks of configuration, scan roots, the index, daemon, Git, watchers, and shell integration:

wtt doctor
wtt doctor --provider
wtt doctor --json

Shell completions

wtt shell completions SHELL generates completions from the current command graph. Use the shell name and destination listed in Quick start.

Create the destination directory first if necessary. WTT prints scripts but never edits shell configuration. Dynamic completions use cached index data only; they do not scan, contact providers, start the daemon, or create persistent state.

Repository hooks

Place executable setup files in .wtt/hooks/post-create, then install and trust their contents from any worktree in the repository:

wtt hooks install
wtt hooks trust

Post-create hooks run directly in lexical order with the new worktree as their working directory. They receive WTT_EVENT, WTT_REPOSITORY, WTT_WORKTREE, and WTT_BRANCH. Changing and reinstalling a hook changes its digest and requires trust again; wtt hooks revoke removes trust.

If Git creation succeeds but hook approval or execution fails, WTT preserves the new worktree and reports its recovery path.