Skip to content
Project

nuthatch.

Create, jump between, and remove git worktrees. All with hop.

  • hop feat/x --create
  • hop
  • hop -
  • hop rm feat/x
  • hop clean
GitHubGitHubInstall ↓

What it does

No config files, no state files. It works in any repository the day you install it.

A terminal where hop feat/x --create prints the path of the new worktree

Create

hop feat/x --create makes the branch and its worktree on the spot. It always lands in <parent of root>/_worktree/<repo>/<branch>.

A list of worktrees and not-yet-created branches whose selection moves down

Jump

hop opens a picker and cds into your choice. hop <branch> goes straight there, hop - goes back, and hop root returns to the original clone.

hop clean finding worktrees marked merged, gone and prunable, and removing them after one confirmation

Remove

hop rm <branch> removes a worktree and keeps the branch. hop clean finds worktrees that are merged, whose upstream is gone, or whose directory has disappeared, lists them, and asks once before removing them.

Safe by default

  • Dirty worktrees are refused. Add --force only when you mean it.
  • Locked worktrees are left alone. Not even with --force. hop never removes a lock.
  • Worktrees outside _worktree get a prompt. Deleting one from the picker always asks y/N first.
  • hop clean only removes worktrees under _worktree. Others are included only with --ext.

For AI coding agents too

  • No prompts. Given a branch, every command runs without prompts, and --json works everywhere.
  • Path on stdout, logs on stderr. Capture the result straight into a variable. Errors tell you the next step.
  • A plugin teaches the agent. A using-hop skill ships for Claude Code and Codex.
p=$(hop feat/x --create)   # path on stdout
hop ls --json              # {"schemaVersion":1,"command":"ls","data":[...],"warnings":[]}

Install

Binary (recommended)

curl -fsSL https://raw.githubusercontent.com/n-seiji/nuthatch/main/install.sh | sh
# or, with mise
mise use github:n-seiji/nuthatch
  • •For macOS (arm64 / x64) and Linux (x64). No Node.js needed.
  • •hop goes to ~/.local/bin. Change it with HOP_INSTALL_DIR.
  • •Binaries from v0.2.1 on carry a build-provenance attestation.

npm

npm i -g @n-seiji/nuthatch
# or, with mise
mise use -g npm:@n-seiji/nuthatch
  • •Use this on Linux arm64, which has no prebuilt binary.
  • •It runs on Node, so it is slower (hop ls takes about 400ms against about 60ms for the binary, per the README).

Shell integration (zsh)

# ~/.zshrc
eval "$(hop init zsh)"
  • •With this, hop cds into the worktree you pick.

Agent plugin

# Claude Code
/plugin marketplace add n-seiji/nuthatch
/plugin install hop@nuthatch

# Codex
codex plugin marketplace add n-seiji/nuthatch
codex plugin install hop