workbranch

English | 한국어

Manage Git worktree task spaces without memorizing git worktree commands.

workbranch creates one task folder per feature, works with one repo or many repos, and keeps branch refresh commands short and safe.

The CLI creates workspaces and runs the Git flow. Companion shows task status, Plan progress, and notifications from the macOS menu bar. They read the same workbranch project state, so you can work from the CLI and check everything at a glance in Companion.

At a glance

When you need to	Use	Role	Install
Create, refresh, land, or push task workspaces	workbranch CLI	Runs the actual Git/worktree workflow	brew install tkhwang/tap/workbranch
Check task status, Plan progress, and notifications	Workbranch Companion	Shows CLI state from the menu bar	brew install --cask tkhwang/tap/workbranch-companion

Quick start

brew install tkhwang/tap/workbranch
workbranch init                 # register a project and repos; can create the first task
workbranch add login            # create another task whenever you need one
cd feat-login                   # task root: run your AI agent here
workbranch status               # check every repo in the task

On macOS, install Companion too:

brew install --cask tkhwang/tap/workbranch-companion

Install

Homebrew

brew install tkhwang/tap/workbranch

If you prefer to add the tap first:

brew tap tkhwang/tap
brew install workbranch

curl installer

curl -fsSL https://raw.githubusercontent.com/tkhwang/workbranch/main/install.sh | bash

Homebrew installs published releases. The curl installer tracks main.

Create your first project

workbranch init walks you through setup and can create your first task on the spot.

workbranch init
# Project name, then register one repo (name + Git URL + base branch)
# "Add another repo?"    -> N       # one repo is enough to start
# "Add your first task?" -> login   # creates the feat-login workspace

Need another task later? Create one anytime with workbranch add.

workbranch add login # (branch) feat/login
                     # (folder) feat-login/<repo>

These quick-start examples assume a main/master base. If every repo is based on the same parent feature branch, such as feature/cpq, workbranch add login asks only for the task name and creates folder feature-cpq-login/<repo> with branch feature/cpq-login.

What the CLI creates

For every task, the CLI creates linked worktrees under one shared task directory:

my-app-workspace
├── .workbranch.config
├── _base
│   ├── frontend
│   └── backend
└── feat-login          // task root: not git-managed; run your AI agent here
    ├── frontend        // Git repo worktree
    └── backend         // Git repo worktree

For multi-repo products, workbranch gathers every repo an agent needs into one task folder. That makes AI-agent sessions easier to start, inspect, and clean up than juggling separate clones or unrelated worktrees.

Before an agent starts, workbranch refresh <task> brings every repo in the task up to the latest base in one command — no per-repo pulling or rebasing.

See AI agent workflows for the multi-repo benefits.

Companion reads this structure through workbranch list --global --json and shows each task's Plan, progress, and notifications. Task creation, refresh, land, and push remain CLI actions.

Working on a task

Now work inside the task workspace. The task root (<task>) is a non-git workbranch metadata/agent workspace; the actual Git repos live under <task>/<repo>. Before editing a repo, read and follow repo-local agent instructions such as <task>/<repo>/AGENTS.md, <task>/<repo>/CLAUDE.md, or <task>/<repo>/.claude/ when present.

# macOS: open code repos in the IDE, and the task root in the terminal
workbranch ide feat-login        # opens feat-login/<repo> worktrees
workbranch terminal feat-login   # opens feat-login task root

# or anywhere
cd feat-login/<repo>
# edit code and run git commands in the repo

Need the latest base while you work? See Staying up to date. When the work is done, ship it.

Staying up to date

To bring a single task up to the latest base, pull the base from its remote and update <task> to apply it to the task.

workbranch pull               # pull every base from its remote
workbranch update feat-login  # apply local base updates to every repo in the task

# combined: pull + update in one step
workbranch refresh feat-login

Working in several tasks at once? Run them without a task name to refresh every task in one go.

workbranch pull      # update local bases
workbranch update    # apply local bases to every task

# combined
workbranch refresh   # pull bases, then update every task

To refresh the base, apply it to a task, and land in one step, use finalize.

workbranch finalize feat-login   # base pull → feat-login update → land

Two ways to ship

What push publishes depends on your base branch.

	Feature flow	Stacked flow
Base branch	main / master	a feature branch, e.g. feat/login
Task branch (folder)	feat/login (feat-login)	feat/login-part1 (feat-login-part1)
Ship	push the task branch, open a PR	land into base, then push the base
Command	workbranch push feat-login	workbranch land feat-login-part1 workbranch push
Pushes	task branch	base branch

Feature flow

# edit code in feat-login/<repo>

workbranch push feat-login # local feat/login -> origin/feat/login

Stacked flow

# edit code in feat-login-part1/<repo>

workbranch land feat-login-part1 # fast-forward feat/login-part1 into local base (feat/login)
workbranch push                  # local feat/login -> origin/feat/login

Commands

Command	Use it to
workbranch init	Create or clone base worktrees from config
workbranch add [<task>]	Create a task workspace
workbranch list [--json]	Show repos and task workspaces; --json is machine-readable output
workbranch memo [task]	Show, write, or clear the task brief in TASK-WORKBRANCH.md
workbranch noti ...	Add, list, or clear task notifications
workbranch status	Show base remote diff, task diff, and dirty state
workbranch update [task]	Update every repo in the task from local base (no pull)
workbranch land <task>	Fast-forward task work into local base branches
workbranch done <task>	Mark the current Plan done and archive it
workbranch push [task]	Push base or task branches
workbranch doctor [--fix]	Diagnose project health; safe fixes include stale worktree pruning and brief H1 repair

Combined flow shortcuts:

Command	Use it to
workbranch refresh [task]	Pull base branches, then update task workspaces
workbranch finalize <task>	Pull base branches, update one task, then land it
workbranch prune	Remove clean task workspaces already merged into local base branches

View with Companion

Workbranch Companion is a macOS menu bar app that shows the project/task state created by the CLI.

• Companion: check and navigate task status, Plan/Step progress, notifications, memo, Finder/IDE/terminal launch actions
• Shared state: the task root's TASK-WORKBRANCH.md, .workbranch/notifications.jsonl, and workbranch list --global --json output

Install:

brew install --cask tkhwang/tap/workbranch-companion

More docs

• Task identity and branch names
• Usage details
• AI agent workflows
• Architecture
• Git operations
• MVP spec