Skip to content
  1. Wiki
  2. How pstack works
  3. Worktrees

Worktrees

A worktree is a second working folder for the same repo. When several AIs edit code at once, each uses its own.

An analogy

Like several cooks making one meal. They share a fridge, but each has their own cutting board.

In pstack

The "open a PR" playbook already works in a worktree, so you usually don't mention it. Only say something to pick the starting branch, like "start a new worktree from main".

Worktrees take disk space; on a laptop, a few at once is about the limit. When disk is tight, say "see what's eating my disk and delete the worktrees that can go". For any with uncommitted changes, it stops and asks you.

Common misconceptions

  • "Worktrees are a pstack feature": they're built into Git (git worktree). pstack just uses them by default.
  • "My project doesn't need Git": most playbooks assume a Git repo. If you're not using Git yet, run git init and make one commit.

Related: Subagents, PRs, commits and merging

An unofficial beginner's guide to pstack, not its official docs. pstack is made by poteto; the official repo is the source of truth for commands and behavior. The original guide source is on GitHub.

Hosted by airali. Adapted from Xiaoxiaodong's MIT-licensed guide.