tak

Git worktree manager with pinning, tmux integration, and lifecycle tools.

tak makes git worktrees easy to create, navigate, and clean up. Pin long-lived worktrees, jump between them with tmux, and garbage-collect stale ones.

Why tak?

Git worktrees let you work on multiple branches simultaneously without stashing or switching. But managing them by hand is tedious — you have to remember paths, manually clean up, and set up your dev environment every time.

tak handles all of that:

Without tak	With tak
git worktree add ../web--feature--auth -b feature/auth	tak add feature/auth
Remember the path, cd manually	tak cd feature/auth
Forget to clean up merged branches	tak gc --merged
Manually open tmux, split panes, run commands	tak open (uses your layout config)
Accidentally delete pinned worktrees	tak pin protects them

Install

Homebrew (macOS/Linux)

brew install mzner/tap/tak

Download binary

Download the archive for your platform from the releases page, then:

tar xzf tak_0.1.0_darwin_arm64.tar.gz
sudo mv tak /usr/local/bin/

Available archives follow the pattern tak_<version>_<os>_<arch>.tar.gz:

Platform	File
macOS ARM (Apple Silicon)	tak_0.1.0_darwin_arm64.tar.gz
macOS Intel	tak_0.1.0_darwin_amd64.tar.gz
Linux x86_64	tak_0.1.0_linux_amd64.tar.gz
Linux ARM	tak_0.1.0_linux_arm64.tar.gz

From source (requires Go)

go install github.com/mzner/tak@latest

Quick Start

# 1. Initialize tak in your repo
tak init

# 2. Set up shell integration (for tak cd)
eval "$(tak shell-init zsh)"   # add to ~/.zshrc

# 3. Create a worktree and open it in tmux
tak add feature/auth -o

# 4. Pin it so gc won't clean it up
tak pin

# 5. List all worktrees
tak ls

# 6. Jump between worktrees
tak cd feature/auth

# 7. Health check
tak doctor

# 8. Clean up merged branches
tak gc --merged

Shell Integration

Required for tak cd to change your directory. Add to your shell rc file:

# .zshrc or .bashrc
eval "$(tak shell-init zsh)"

# config.fish
tak shell-init fish | source

Without this, tak cd prints the path but can't change your shell's working directory.

Commands

Command	Description
tak add <branch> [-o] [-p] [-f base]	Create a worktree (new branch from -f or default; checks out existing branches)
tak rm [branch...] [-F]	Remove worktree(s) and branch — interactive if no arg
tak ls [-s] [--json]	List all worktrees (-s dirty/clean, --json for scripting)
tak info [branch]	Show worktree details (base, ahead/behind, age)
tak exec <branch> -- <cmd>	Run a command in a worktree without cd'ing
tak cd [branch]	Change to a worktree directory — interactive if no arg
tak open [branch]	Open/switch to tmux window — interactive if no arg
tak rename <old> <new>	Rename a worktree's branch
tak pin [branch]	Pin a worktree (no arg = current)
tak unpin [branch]	Unpin a worktree
tak doctor	Health check all worktrees
tak gc [-m] [-n]	Clean up broken worktrees (-m includes merged, -n dry run)
tak layout	Configure tmux pane layout (interactive wizard)
tak config	Show config file paths and contents
tak init	Initialize tak in a repo
tak repo add [path...]	Register repo(s) for cross-repo access
tak repo rm [name...]	Unregister repo(s) — interactive if no arg
tak repo ls	List registered repos
tak completion <shell>	Generate shell completion script
tak shell-init <shell>	Print shell hook for zsh/bash/fish

Configuration

tak uses two config files. Per-repo settings override global settings.

Per-repo: .tak.yml

Created by tak init. Lives in your repo root.

worktree_base: ""         # empty = sibling dirs (default)
branch_prefix: ""         # auto-prepend to branch names (e.g. "feature/")

pins:
  - feature/auth

# Optional: tmux pane layout for tak open (configure with tak layout)
tmux:
  layout: main-vertical
  panes:
    - name: editor
      command: $EDITOR
    - name: dev
      command: pnpm dev
    - name: shell
      command: ""

# Optional: lifecycle hooks around worktree creation and removal
hooks:
  pre_create:                  # before worktree is created (non-zero aborts)
    - type: command
      command: docker compose stop
  post_create:                 # after worktree is created
    - type: copy
      from: .env
      to: .env
    - type: symlink
      from: node_modules
      to: node_modules
    - type: command
      command: npm ci
  pre_remove:                  # before worktree is removed (non-zero aborts)
    - type: command
      command: chmod -R u+w .
  post_remove:                 # after worktree is removed
    - type: command
      command: docker volume rm "vol-$TAK_WORKTREE_NAME" || true

Hook types:

Type	Description	Fields
copy	Copy file/directory from main worktree to new	from, to (defaults to from)
symlink	Create symlink from new worktree pointing to main	from, to (defaults to from)
command	Run a shell command in the worktree	command, env (optional), work_dir (optional)

All command hooks receive TAK_WORKTREE_NAME, TAK_SOURCE_DIR, TAK_TARGET_DIR, TAK_BRANCH, and TAK_HOOK as environment variables. Commands are interactive (stdin connected). See docs/configuration.md for full details.

Global: ~/.config/tak/config.yml

Optional. Sets defaults for all repos. Per-repo .tak.yml overrides these.

worktree_base: ~/worktrees   # override default for all repos
repos:
  web: ~/projects/web
  ocis: ~/projects/ocis

Register repos with tak repo add:

tak repo add                              # register current directory
tak repo add ~/projects/web ~/projects/api  # register multiple at once
tak repo ls                               # list registered repos
tak repo rm web                           # unregister

Cross-repo access

Once repos are registered, access them from anywhere:

tak ls web                     # list web's worktrees
tak cd web:feature/auth        # cd to web's feature/auth worktree
tak exec web:main -- git pull  # run command in web's main worktree

Tab completion shows repo names and their branches.

How It Works

• tak add creates a new branch from the default branch (or --from). If the branch already exists locally or remotely, it checks it out without creating a new one
• Worktrees are created as sibling directories by default: ~/projects/web → ~/projects/web--feature--auth
• tak rm removes the worktree and deletes the branch (keeps it if there are unpushed/unmerged commits, unless -F)
• tak open uses the tmux config from .tak.yml to create pane layouts, or a plain window if unconfigured
• Pins are stored in .tak.yml — recoverable config, not ephemeral state
• State cache (.tak/state.json) is rebuilt automatically if deleted
• Per-repo .tak.yml overrides global ~/.config/tak/config.yml for any key present in both
• All git/tmux interaction is via shell commands — no heavy dependencies

Editor Integration

tak.nvim adds Neovim pickers for switching, creating, and removing worktrees without leaving the editor.

Contributing

See docs/contributing.md.

License

MIT