pf

pf — Human- and agent-friendly Git multitasking

Install

npm i -g pf

How does it work

There have been many attempts to nail a DX for parallel work in the agentic coding era. Most are thin wrappers over git worktree. That's not what pf is (though worktrees are used internally).

Instead pf introduces a new paradigm: the workshell. A workshell is an ephemeral worktree whose lifecycle is bound to a subshell. Here's how it works (key points in bold).

• You open a Git branch with pf open <branch> or create a new one with pf new <branch>.
• An ephemeral worktree is created for this branch (in .git/pf/worktrees) and opened in a fresh subshell.
• You are now in an fresh checkout of your repo that is isolated on disk. Make changes with your agent/editor of choice and commit them.
• You close the subshell with pf close, which auto-prunes the associated worktree.
• Your changes still exist on the associated branch.

That's it. Ephemeral worktrees whose lifecycle is bound to a subshell. When the subshell exits, the worktree is destroyed—but your commits aren't.

This approach has some nice properties.

🙅‍♂️ Never stash again — You can pf open a branch even with uncommitted changes. When you exit the subshell, things will be exactly the same as they were. ☕️

🖥️ Tab-local checkouts — Normally a git checkout/git switch changes your active branch for all terminals. With workshells, you can functionality open branches in the current tab only.

🌳 Isolated workspaces — Each workshell is isolated on disk, so the changes you make don't affect anything else you're doing.

🪾 Maintains branch semantics — As with regular git checkout, pf close won't let you close the subshell if you have unstaged/uncommitted changes. Vanilla worktrees are too forgiving in this regard; it makes it far too easy to leave half-finished work in a forgotten corner of your file system.

🤖 Agent-ready — Spin up parallel workshells so multiple agents can work simultaneously without conflicts.

Quickstart

This section is entirely linear and self-contained. You can run all these commands in order to get a feel for how pf works.

First, install pf.

$ npm i -g pf

Then clone a repo (any repo works):

$ git clone [e-mail]:colinhacks/zod.git
$ cd zod

After cloning, the main branch is checked out. Let's say we want to start work on a new feature:

$ pf new feat-1

✓ feat-1 (from main)
Opened branch in ephemeral subshell at .git/pf/worktrees/zod@feat-1
Type 'pf close' to return.

You're now in a workshell. Check where you are:

$ pwd
/Users/colinmcd94/Documents/repos/zod/.git/pf/worktrees/zod@feat-1

$ git branch --show-current
feat-1

Now let's make some changes. (You can also open the repo in an IDE, start an agent run, etc.)

$ touch a.txt

Now let's try to close the workshell.

$ pf close
⚠ Uncommitted changes found. Commit, stash, or reset your changes first.
  Or use --force/-f to discard changes
    pf close -f

We aren't able to close because we have uncommitted changes. Let's commit them.

$ git add -A && git commit -am "Add a.txt"

Now we can close again. On a successful close, you'll be prompted to merge your changes into the base branch.

$ pf close
✓ Back in main
  Pruned worktree. Your changes are still in the 'feat-1' branch.
  To merge your changes:
    git merge feat-1

  Auto-merge? (y/n/never) y

✓ Merged 'feat-1' into 'main'

If you type n, you can manually handle your own merging logic. The changes you made are still available in the feat-1 branch.

If you type never, you can permanently disable the auto-merge prompt.

CLI

pf v0.x.y - Open branches in workshells

Usage: pf <command> [options]

Commands:
  new [branch]    Create a branch and open it [--from <branch>]
  open <branch>   Open a branch in a workshell
  close           Exit current workshell
  ls              List orphaned worktrees
  status          Show current branch
  rm <branch>     Delete a branch and its worktree

Options:
  --help, -h      Show help
  --version, -v   Show version

List orphaned worktrees

Normally the worktree will be auto-pruned when you close its associated workshell. If a worktree is left behind for some reason, you can list them with pf ls.

$ pf ls
┌──────────────────────┬────────┬─────────────────┐
│ branch               │ status │ created         │
├──────────────────────┼────────┼─────────────────┤
│ main                 │ clean  │ -               │
│ feat-1 *             │ clean  │ 5 minutes ago   │
└──────────────────────┴────────┴─────────────────┘

Open a branch

You can open any existing Git branch in a workshell.

$ pf open feat-1

✓ feat-1 (existing worktree)
Type 'pf close' to return.

Show current branch status

$ pf status
branch:    main (root)
worktree:  /path/to/zod
status:    clean

Remove a branch

$ pf rm feat-1

✓ Deleted feat-1

Closing a workshell

This closes the current workshell and auto-prunes the associated worktree. Your changes survive in your branch commits.

pf close

That command will fail if you have unstaged/uncommited changes. Use the --force/-f flag to force close the workshell; this will discard your changes.

pf close --force