workthreads 0.1.0

Developer-first git worktree workflow CLI

workthreads

workthreads provides the wt CLI: a developer-first workflow tool for creating, preparing, listing, and deleting git worktrees.

Setup

Prerequisites:

• Git
• Python 3.12+

Install the latest release from PyPI:

uv tool install workthreads
wt --help

Alternative user-level install without uv-managed tools:

python3 -m pip install --user workthreads
wt --help

For local development, install uv and sync dependencies:

uv sync

Run the CLI from the repo during development:

uv run wt --help

Install the local checkout once so it is available globally on your PATH and you do not need to use uv run every time:

uv tool install -e .
wt --help

Shell setup

Full shell integration includes completion, wt add --cd, and wt cd support:

eval "$(wt shell init zsh)"   # zsh
eval "$(wt shell init bash)"  # bash
wt shell init fish | source   # fish

Completion only:

eval "$(wt shell completion zsh)"

Basic usage

Configure wt defaults for this repo:

wt config init
wt config edit

Repo configuration lives in wt.toml at the repository root. It can stay untracked for local workflow settings, or be committed only when the repo intentionally wants shared defaults. Use wt config path to print the active path.

By default, wt add feature/payment-retry creates .worktrees/feature/payment-retry under the repo root. When the selected base ref belongs to a configured remote, wt add fetches that remote first; pass --no-fetch to skip this for one command.

Recommended local workflow:

[defaults]
fetch = true
copyLocal = true
deleteBranch = false

[shell]
cdAfterAdd = true

Keep copyLocal = false if you do not want local ignored and untracked files copied automatically. Enable it when fresh worktrees usually need local setup files such as .env, editor config, generated credentials, or scratch project config before the app can run.

Create a worktree:

wt add feature/payment-retry

Create one at an exact path and copy ignored/untracked local files:

wt add feature/payment-retry \
  --base origin/main \
  --path ../external-worktrees/payment-retry \
  --copy-local

Full shell integration enters newly created worktrees by default. To stay in the current directory for one command:

wt add feature/payment-retry --no-cd

Jump to an existing worktree when shell integration is enabled:

wt cd payment-retry

wt cd accepts exact names and unique prefixes. For a worktree named feat/foo, both wt cd feat and wt cd foo can resolve it when unique. If fzf is installed, unresolved or ambiguous queries open a filtered picker instead of silently choosing a fuzzy match.

List worktrees:

wt list

Delete the current linked worktree:

wt delete

Delete a named worktree from elsewhere:

wt delete feature/payment-retry

Hooks

Configure lifecycle hooks:

wt hooks init
wt hooks edit post-create

Hooks receive stable WT_* environment variables such as WT_EVENT, WT_REPO_ROOT, WT_WORKTREE_PATH, WT_BRANCH, and WT_BASE.

Recommended repo-local hook script layout:

.git/
  workthreads/
    hooks/
      post-create.sh
      pre-delete.sh

Use wt hooks dir or wt hooks path post-create to inspect the generated paths.

User-global hook scripts are also fine:

~/.config/
  workthreads/
    hooks/
      post-create.sh
      pre-delete.sh

Shared hook scripts are possible, but should be intentional project policy rather than the default:

scripts/
  wt/
    post-create.sh
    pre-delete.sh

Development

Run tests:

uv run pytest

Run a quick CLI smoke check:

uv run wt
uv run wt shell completion zsh