Getting Started

Install workbench and run your first multi-agent plan in under five minutes.

Prerequisites

Before installing workbench, make sure you have the following:

  • Python 3.11+ — verify with python3 --version
  • Git — workbench uses git worktrees for task isolation
  • tmux — used for live monitoring of agent sessions (brew install tmux on macOS, apt install tmux on Linux, or via WSL on Windows)
  • At least one supported agent CLI:

Your agent CLI must be installed and authenticated separately. Workbench dispatches work to these agents — it does not bundle them.

Installation

Install workbench from PyPI:

pip install wbcli

This installs the wb command globally.

Project Setup

Navigate to any git repository and run:

wb setup

If you have multiple agent platforms installed, workbench will ask you to choose:

$ wb setup
Multiple agent platforms found. Choose one (claude, gemini): claude
Created /path/to/your/project/.workbench/
Installing 1 command(s) for claude...

  Copied /use-workbench → /path/to/your/project/.claude/skills/use-workbench

  Use in Claude Code: /use-workbench
  Also installed to /path/to/your/project/.agents/skills for cross-client discoverability.

Done. Installed 1 command(s) for claude.

Repo is ready for workbench.

Your First Plan

Create a plan file (e.g. plan.md or .workbench/plan.md) with these sections:

# Plan Title
 
## Context
 
Describe what the project is, what you're building, and why.
This is injected into every agent's prompt so they understand
the codebase.
 
## Conventions
 
List the coding standards agents should follow:
- Language and framework versions
- Naming conventions, import style
- Test framework and test command
- Any project-specific patterns
 
## Task: Short Title
Files: path/to/file1, path/to/file2
 
Detailed description of what to implement. Be specific —
the agent only sees its own task, not the rest of the plan.
Include function signatures, expected behavior, and edge cases.
 
## Task: Another Task
Files: path/to/other/files
Depends: short-title
 
Another task description. The Depends line means this task
waits until "Short Title" completes before starting.
Tasks without dependencies run in parallel.

Tasks with no shared files and no Depends: line run in parallel. Tasks that depend on earlier work wait until those tasks complete.

Previewing the Plan

Before running, preview the plan to verify tasks and waves:

wb preview plan.md

This parses the plan and shows the task graph without executing anything:

$ wb preview plan.md

Wave 1 (1 tasks, run in parallel)
  • Short Title
    Files: path/to/file1, path/to/file2
    Detailed description of what to implement...

Wave 2 (1 tasks, run in parallel)
  • Another Task
    Files: path/to/other/files
    After: short-title
    Another task description...

Use this to check that dependencies are correct and tasks are grouped into the right waves before dispatching agents.

Running the Plan

Execute the plan:

wb run plan.md

Workbench parses the tasks, creates isolated git worktrees, and dispatches agents in parallel. Each task goes through a pipeline of roles — implement, test, review — with automatic fixing if anything fails:

$ wb run plan.md
Parsed 2 task(s) from plan.md

Tasks: 2 across 2 wave(s)
Concurrency: 4

—— Wave 1/2 (1 task) ——

                    Workbench
 Task            Status   Time    Pipeline
 Short Title     done     3m42s   impl:ok → test:pass → review:pass

Merging 1 branch(es) into workbench-1...
  ✓ wb/short-title — Merged cleanly.

—— Wave 2/2 (1 task) ——

                    Workbench
 Task            Status   Time    Pipeline
 Another Task    done     4m18s   impl:ok → test:fail → fix → test:pass → review:pass

Merging 1 branch(es) into workbench-1...
  ✓ wb/another-task — Merged cleanly.

Merging the Results

When the plan completes, all changes are on a session branch (e.g. workbench-1). This branch contains the merged results of every task across all waves. To integrate the work:

# Merge into your current branch
git merge workbench-1
 
# Or merge into main
git checkout main
git merge workbench-1

Review the diff before merging — workbench agents do the implementation, but you own the final review.

Cleanup

Workbench creates isolated git worktrees for each task. These are usually cleaned up automatically, but if any remain after completion you can remove them:

wb clean

This removes all workbench-created worktrees. To also stop any running agent sessions and remove their branches:

wb stop --cleanup

What's Next

  • Plan Format — learn about dependencies, waves, and advanced plan structure
  • CLI Reference — explore all commands and flags
  • Agents — configure multi-provider setups with Claude, Gemini, and Codex