Getting Started

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

Prefer to let your agent handle setup? Download the workbench skills and drop them into your project — your agent can install workbench, configure agents, and set up your environment automatically.

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
  • macOS: brew install tmux
  • Linux: apt install tmux
  • Windows: available via WSL
• At least one supported agent CLI:
  • Claude Code — claude command
  • Gemini CLI — gemini command
  • OpenAI Codex — codex command
  • Cursor CLI — agent command
  • GitHub Copilot CLI — copilot command
  • Any custom CLI that supports dispatch — see Agents

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

Installation

pip (all platforms):

pip install wbcli

Homebrew (macOS / Linux):

brew install duncankmckinnon/tap/workbench

This installs the wb command in your active Python environment.

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

Don't want to write the plan yourself? Run wb plan "describe what you want to build" to have a planner agent survey your codebase and produce a ready-to-run plan at .workbench/plan/plan.md. You can also convert an existing spec with wb plan --from spec.md. See CLI Reference for full options.

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.

Plan frontmatter (optional): Plans can declare run-time defaults in a YAML frontmatter block at the very top of the file, before # Title. CLI flags always override frontmatter values. See Plan Frontmatter for the full schema and examples.

---
session_branch: workbench-auth
base: feature-auth
tdd: true
max_concurrent: 6
---
# Auth refactor
 
## Context
...

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.

What's Next

When your plan completes, all changes land on a session branch (e.g. workbench-1) ready to merge. See Running Plans for details on merging results, handling failures, monitoring agents, and cleanup.

• 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, Codex, Cursor, and Copilot
• Running Plans — monitoring, failure handling, merging, and cleanup