Getting Started

Prerequisites

A multiplexer (tmux, zellij, cmux, herdr) is optional; see Integrations.

Installation

Homebrew

brew install jewell-lgtm/tap/monkeypuzzle

Via go install

go install github.com/jewell-lgtm/monkeypuzzle/apps/mp@latest

From source

git clone https://github.com/jewell-lgtm/monkeypuzzle.git
cd monkeypuzzle
make build                  # → bin/mp
sudo mv bin/mp /usr/local/bin/   # or add bin/ to PATH

Set up your shell

Load the shell wrapper, so that mp create and mp switch move your shell into the piece’s worktree instead of only printing its path:

echo 'eval "$(mp shell-init zsh)"' >> ~/.zshrc   # bash: ~/.bashrc
exec zsh

For fish, add mp shell-init fish | source to ~/.config/fish/config.fish.

Check the result:

mp doctor

mp doctor reports the config, multiplexer, shell wrapper, opener and, inside a repo, whether it’s an mp project and whether gh/glab is authenticated.

Initialize a project

In your repo:

cd path/to/your/repo
mp init

On first use mp asks which multiplexer you use; the default, none, is the plain-terminal setup this guide uses (mp config set multiplexer … changes it later). Then the wizard asks for a project name (defaults to the directory name) and a PR provider (github or gitlab). It creates .monkeypuzzle/ with the project config and a .gitignore for the piece worktrees, and registers the project so mp go and mp inbox can find it.

For scripts or CI, skip the wizards:

mp config set multiplexer none   # the first-run choice, once per machine
mp init --name myproject --pr-provider github
echo '{"name":"myproject","pr_provider":"github"}' | mp init
mp init --schema | jq '.name = "custom-name"' | mp init

Your first piece

mp create --name my-feature   # branch + worktree off main; your shell moves into it

# ... make your changes, commit ...

mp pr create --draft          # push the branch, open a draft PR/MR
mp pr ready                   # flip it to ready for review
mp merge                      # merge into main (or merge the PR on the forge)
mp done                       # remove the worktree now it's merged

mp done refuses a piece that isn’t merged; mp done --force removes the worktree anyway and keeps the branch. When the worktree you’re standing in is removed, the shell wrapper takes you back to the main repo.

Each step fires the matching lifecycle hook if you’ve dropped one in .monkeypuzzle/hooks/; see Hooks.

Getting around

mp                            # picker over this repo's pieces and branches
mp go                         # picker across every registered project
mp switch my-feature          # straight to a piece or branch by name
mp open my-feature            # open the worktree in your editor

mp open needs an opener. Set one once:

mp config set open_command 'code {path}'   # or cursor, zed, idea, …

Without the shell wrapper, cd "$(mp switch my-feature)" does the same as mp switch my-feature.

Next steps