wb (workbranch)

Agent- and human-friendly Git multitasking, powered by worktrees.

Install

npm i -g workbranch

What is a workbranch?

A workbranch is a new concept that I made up. It combines two Git concepts:

1. git worktree — An isolated copy of your repository on disk. Think of it like a separate clone of your repo, except it shares a Git history (commits, branches, tags, etc.) with your

2. git branch — The classic approach to compartmentalizing changes in git. But a purely branch-based workflow doesn't work well for multitasking, because only one branch can be checked out at a time across your whole repo.

Together, these tools are incredibly powerful. But the native git CLI doesn't provide an ergonomic experience for someone who wished to use them together.

The wb CLI unifies them into a single ergonomic experience that

• feels like regular branching
• leverages the power of worktrees under the hood
• is perfect for parallelizing development work locally

Get started

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

First, install wb.

$ npm i -g workbranch

The clone a repo (any repo works):

$ git clone https://github.com/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:

$ wb new feat-1

✓ feat-1 (from main)
Created new workbranch at .git/workbranch/worktrees/feat-1/zod
Subshell started. Type 'exit' to return.

You're now in an isolated workbranch. Check where you are:

$ pwd
/Users/you/zod/.git/workbranch/worktrees/feat-1/zod
$ git branch
* 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  # or open workspace in Cursor, Claude, VS Code, etc
$ git add -A 
$ git commit -m "Add a.txt"

Type exit to quit the subshell and return to the root repo.

$ exit
✓ Exited 'feat-1' workbranch
✓ Back in main workbranch
$ wb status
name:      root
worktree:  /path/to/zod
branch:    main
status:    clean

Now we can merge our feature into main.

$ git merge feat-1
Updating abc1234..def5678
Fast-forward
 a.txt | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 a.txt

List your workbranches with wb ls:

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

We can re-open it to do more work.

$ wb checkout feat-1

✓ feat-1 (feat-1)
Subshell started. Type 'exit' to return.
# do stuff...
$ exit

Or we can delete the workbranch if we're done with it.

$ wb rm feat-1

Delete feat-1?
  path:   .git/workbranch/worktrees/feat-1/zod
  branch: feat-1

Continue? (y/N) y

✓ Deleted feat-1

Features

🌳 Isolated branches — Creating a workbranch creates an isolated copy of your repo, so you don't need to stash or commit the changes on your current branch.

🖥️ Tab-local checkouts — Unlike git checkout, workbranches are scoped to your terminal tab. Open a new tab, run wb new, and you have a fully isolated environment—without affecting your other tabs or editors.

🤖 Agent-ready — Spin up isolated workspaces for AI coding agents. Each agent gets its own sandbox without stepping on your work.

CLI

wb <command> [options]

Commands:
  new [name] [--from <branch>]   Create a workbranch (default name: "wb-[hash]")
  checkout <name>                Checkout a workbranch or existing branch
  ls                             List all workbranches
  status                         Show current workbranch
  rm <name>                      Remove a workbranch

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