workbranch · Open source · CLI + macOS Companion

One task folder per feature. Every repo in one place.

Manage Git worktree task spaces without memorizing git worktree commands. Create a task folder across one repo or many, keep base branches fresh with short, safe commands, and see which AI agent is waiting on you from the menu bar.

$brew install tkhwang/tap/workbranch
GitHub →

macOS · Linux · MIT · Companion for macOS

workbranch creates one task folder across multiple repositories, and Companion shows each task's AI agent sessions in waiting-on-you, running, and turn-ended columns.
The CLI creates one task folder per feature with a linked worktree per repo. Companion reads hook observations and shows which agent is waiting on you.
github stars
1
latest cli release
v2.40.0
companion release
v2.40.0
agents · claude · codex · grok
3

What it does

Create with the CLI. Watch with Companion.

The CLI runs the Git and worktree flow. Companion reads what the agents report and shows it in the menu bar. Nothing else changes about how you work.

  1. 01

    One task folder, every repo

    workbranch add login creates feat-login/ with a linked worktree for each configured repo, while _base/ keeps the shared base checkouts. The task root is where your AI agent runs; the repos live underneath it.

    • Works with one repo or many, so an agent can touch frontend and backend in one session
    • workbranch init registers the project and can create the first task on the spot
    • Stacked on a feature base? add asks only for the task name and derives feature-cpq-login/
  2. 02

    Refresh every repo in one command

    pull brings the bases from their remotes, update applies them to a task, and refresh does both. Before an agent starts, one command puts every repo in the task on the latest base.

    • update and refresh stop on a dirty worktree instead of merging over your changes
    • workbranch stash keeps changes under the current branch, not the stash list every worktree shares
    • finalize runs pull → update → land in one go
  3. 03

    Two ways to ship

    What push publishes depends on your base. On main, push the task branch and open a PR. On a feature branch, land the stacked task into it and push the base.

    • Feature flow: workbranch push feat-login
    • Stacked flow: workbranch land feat-login-part1, then workbranch push
    • prune removes clean task workspaces already merged into local bases
  4. 04

    See which agent is waiting on you

    Workbranch Companion is a macOS menu bar app. It reads hook observations from Claude Code, Codex, and Grok Build and places each task on a board: waiting on you, running, or turn ended and ready for review.

    • Task cards show IDE, Terminal, and Finder launchers plus each repo's branch and Git facts without expanding
    • Click a card for recent commits and session details; double-click opens the task in your IDE
    • Base repositories show branch, dirty state, and ahead/behind counts with PULL, PUSH, or CHECK guidance
  5. 05

    Token usage, read locally

    A usage summary above the board shows Claude Code and Codex side by side: plan limits with time to reset, today's tokens, and the last seven days. Companion reads only local files and never signs in.

    • Pick what shows beside the menu bar icon, as used or remaining percent
    • Usage view adds a shared 14-day daily chart and a last-7-days table
    • Opt in to Live Claude Limits to refresh while a Claude Code session is open
  6. 06

    Works with the agents you already run

    Install hooks for Claude Code or Codex with one command and review the provider's hook trust. Grok Build needs explicit trust: inspect the plugin source first, then install with --trust.

    • No TASK-WORKBRANCH.md reporting required; runtime snapshots come from hooks
    • Companion onboarding can install the CLI with Homebrew and connect agents for you
    • One update action upgrades the CLI before Companion

Commands

A small, predictable set covers the whole task lifecycle.

Workspace lifecycle

Set up the project, create tasks, and check on them.

  • $ workbranch initCreate or clone base worktrees from config; can create the first task.
  • $ workbranch add [<task>]Create a task workspace with a linked worktree for every repo.
  • $ workbranch list [--json]Show repos and task workspaces; --json is machine-readable.
  • $ workbranch statusShow base remote diff, task diff, and dirty state.
  • $ workbranch doctor [--fix]Diagnose project health; safe fixes prune stale worktrees.

Each task is a small mono-repo workspace, so an AI agent can use frontend and backend in the same session.

Branch workflow

Pull fresh bases, update task branches, push work, and land finished changes.

  • $ workbranch pullPull every base from its remote into the local _base repos.
  • $ workbranch update [task]Apply local base updates to one task or every task (no pull).
  • $ workbranch land <task>Fast-forward task work into local base branches.
  • $ workbranch push [task]Push base branches or a specific task branch to origin.
  • $ workbranch stash / stash popSet changes aside under the current branch and restore only those.

Combined flow

The common multi-step flows in one command.

  • $ workbranch refresh [task]Pull base branches, then update one task or every task.
  • $ workbranch finalize <task>Pull base branches, update one task, then land it.
  • $ workbranch pruneRemove clean task workspaces already merged into local bases.

Tools and Companion

Open a task where you work, and connect the agents Companion watches.

  • $ workbranch ide <task>Open the task's repo worktrees in the configured IDE.
  • $ workbranch terminal <task>Open the task root in the configured terminal.
  • $ workbranch noti ...Add, list, or clear task notifications.
  • $ workbranch hooks install --provider claude|codexInstall the hooks Companion reads runtime state from.
  • $ workbranch hooks describe --provider grokInspect the Grok Build plugin source before installing with --trust.

install

Install

Homebrew installs published releases. The curl installer tracks main.

Recommended · Homebrew release

$brew install tkhwang/tap/workbranch

Stop fighting git worktree

Spin up clean, isolated task spaces, keep them on the latest base, and know which agent needs you next.

Get startedView on GitHub ↗