the workflow

From one idea to a merged stack.

People keep asking what Monkeypuzzle actually does. So here's the whole loop, one piece at a time, from the first branch to the cleanup after the merge. Scroll, and watch it play out.

follow along
1cut a piece

Start one small idea.

Every unit of work is a piece: a branch in its own git worktree. Cut one and Monkeypuzzle creates the branch and the worktree, then runs your create hook inside it.

  • mp create --name auth-schema, or leave the name off and get one generated.
  • on-piece-create.sh can install dependencies or copy your .env.
  • Your other work never moves: no stashing, no dirty tree.
acme — zsh
~/acme mp create --name auth-schema✓ Created piece: auth-schema at ~/acme/.monkeypuzzle/pieces/auth-schema~/acme/.monkeypuzzle/pieces/auth-schema→ next: mp pr create --draft~/acme mp
2stack it

Build features in layers.

Real features are more than one idea. Stack the next piece on top of the last with mp stack append: schema, then API, then UI, each a clean, reviewable layer built on the one below.

mp stack status draws the whole tree, so you always know what sits on what.

auth-ui +62 −4 draft
auth-api +210 −18 draft
auth-schema +88 −2 draft
main trunk
3switch

Switch without losing your place.

Every piece stays checked out, so moving between them is a cd. mp switch takes a piece or branch name and prints its worktree; mp open hands the worktree to your editor or a new terminal.

  • Add eval "$(mp shell-init zsh)" to your shell config and your shell follows mp switch, mp create and mp done.
  • No wrapper? cd "$(mp switch auth-api)" works anywhere.
  • Set open_command once, e.g. code {path} or zed {path}, and mp open uses it.
  • Live in tmux or herdr? Give each piece a session.
acme — zsh
~/acme mp switch auth-api~/acme/.monkeypuzzle/pieces/auth-api~/acme mp open auth-ui --with code~/acme mp
4restack

Change one piece, fix the whole tree.

Edit a piece low in the stack and everything above it is now stale. mp stack sync merges each parent down into its children, in order, and stops cleanly the moment a conflict needs you.

  • It previews the sync first and asks before it changes anything.
  • On a conflict, resolve it in the named worktree, commit, and run mp stack sync again.
  • Prefer rebase? --strategy rebase, then mp stack continue after a conflict.
  • mp stack undo restores every branch to the pre-sync snapshot.
acme/auth-schema
~/acme mp stack sync --from origin/main --yes[dry-run] Would sync "auth-schema" (merge "main" into "auth-schema")[dry-run] Would sync "auth-api" (merge "auth-schema" into "auth-api")[dry-run] Would sync "auth-ui" (merge "auth-api" into "auth-ui")✗ Stack sync stopped: merging auth-api into "auth-ui" hit conflicts. Open ~/acme/.monkeypuzzle/pieces/auth-ui, resolve the conflicts, run 'git commit', then run 'mp stack sync' again. Nothing else in the stack was changed.~/acme mp
5submit

One idea per pull request.

Ship the stack. mp pr create pushes the piece and opens a PR based on the piece below it, so each PR is a single idea and reviewers never wade through the whole feature at once.

  • The base is the piece's parent, picked for you. --base overrides it.
  • --draft opens it as a draft; mp pr ready flips it when it's time for eyes.
  • before-pr-create.sh runs first: lint, test, or write the PR body.
acme/auth-ui
~/acme mp pr create --draftPushing branch auth-ui to origin...Creating PR...✓ Created PR #483: https://github.com/you/acme/pull/483→ next: mp pr ready (when it's ready for review)~/acme mp
6merge down

Land it, clean up after.

When the bottom piece is approved, mp merge squash-merges it into main and re-homes the pieces above it onto main. mp done then removes the finished piece's worktree, and with shell-init your shell lands back in the main checkout.

  • Refuses to merge when main has moved on. Run mp update first; no surprise overwrites.
  • Merged on GitHub or GitLab instead? mp done cleans up the same way.
acme/auth-schema
~/acme mp merge --reparent-childrenRe-homed auth-api onto main (force-push it if it has an open PR)✓ Squash merged auth-schema into main→ next: mp done~/acme mp done✓ Done with piece: auth-schema~/acme mp
that's the loop

Cut. Stack. Restack. Submit. Merge.

Each step is one command, and each one runs your hooks.

Get started Read the docs