Menu
Use when installing workbench (wbcli), checking prerequisites (Python, git, tmux), or setting up the wb CLI in a local or global environment
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when writing or editing a workbench plan (.workbench/<name>/plan.md) — plan structure, frontmatter, breaking directives into independent tasks tied to specific files, conventions handling, and testing directives
Use when running, resuming, or troubleshooting `wb` execution of a workbench plan — pipeline stages, failure recovery, wave control, branching strategy, profiles, and TDD mode. For writing or editing the plan file itself, use the plan-workbench skill.
Use when setting up workbench in a repo, configuring agent adapters (.workbench/agents.yaml), managing profiles (profile.yaml), or troubleshooting agent dispatch
Use when generating a project conventions file at .workbench/conventions.md by scanning the codebase. Invoked by `wb conventions init --generate`.
| name | install-workbench |
| description | Use when installing workbench (wbcli), checking prerequisites (Python, git, tmux), or setting up the wb CLI in a local or global environment |
Step-by-step guide to install the wb CLI and verify all prerequisites.
Before installing, verify each prerequisite. Run these checks and address any failures.
uname -s # Darwin (macOS), Linux, or MINGW/MSYS (Windows)
python3 --version
If missing or below 3.11:
| Platform | Install |
|---|---|
| macOS | brew install python or download from python.org |
| Linux (Debian/Ubuntu) | sudo apt install python3 |
| Linux (Fedora/RHEL) | sudo dnf install python3 |
| Windows | Download from python.org or winget install Python.Python.3.13 |
python3 -m pip --version
If missing:
python3 -m ensurepip --upgrade
git --version
If missing:
| Platform | Install |
|---|---|
| macOS | xcode-select --install or brew install git |
| Linux (Debian/Ubuntu) | sudo apt install git |
| Linux (Fedora/RHEL) | sudo dnf install git |
| Windows | Download from git-scm.com or winget install Git.Git |
tmux -V
tmux enables live monitoring of agent sessions. Without it, use --no-tmux to run agents as raw subprocesses.
If missing:
| Platform | Install |
|---|---|
| macOS | brew install tmux |
| Linux (Debian/Ubuntu) | sudo apt install tmux |
| Linux (Fedora/RHEL) | sudo dnf install tmux |
| Windows | Available via WSL |
At least one of:
| Agent | Check | Install |
|---|---|---|
| Claude Code | claude --version | docs.anthropic.com |
| Antigravity CLI | agy --version | github.com/google/agy |
| OpenCode CLI | opencode --version | opencode.ai |
| Codex | codex --version | github.com/openai/codex |
| Cursor CLI | agent --version | cursor.com/docs/cli |
| Copilot CLI | copilot --version | github.com/features/copilot/cli |
You can also use a custom agent CLI via .workbench/agents.yaml — see wb agents add.
Optional local proxy that routes supported agents (claude, codex) through a local endpoint to cut token costs. Install with pipx install "headroom-ai[all]" (Python 3.10+). See the configure-workbench skill for the headroom: config block and the --headroom / --no-headroom flag.
pip install wbcli
wb --version
wb --help
python3 -m venv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows
pip install wbcli
git clone https://github.com/duncankmckinnon/workbench.git
cd workbench
pip install -e ".[dev]"
After installing, set up workbench in your project:
cd your-project
wb setup
This creates .workbench/, installs bundled skill files for your agent platform, and prepares the repo for wb run.
wb setup # auto-detect agent, install skills locally
wb setup --agent claude # install skills for Claude Code
wb setup --agent antigravity # install skills for Antigravity CLI
wb setup --agent opencode # install skills for OpenCode CLI
wb setup --agent cursor # install skills for Cursor CLI
wb setup --profile # also create a profile.yaml
wb setup --global # install skills to user-level paths only
wb setup --symlink # symlink instead of copy (stays in sync)
wb setup --update # force-update skills to latest version
Generate .workbench/agents.yaml with all built-in adapter configs:
wb agents init
This is optional — built-in adapters work without a config file. Use this if you want to customize agent invocation flags or add custom agents.
wb profile init # defaults
wb profile init --set reviewer.agent=antigravity # customize
wb profile init --name fast --set implementor.agent=codex
Run a quick end-to-end check:
# 1. Confirm wb is on PATH
wb --version
# 2. Confirm git repo
git rev-parse --show-toplevel
# 3. Confirm .workbench/ exists
ls .workbench/
# 4. Preview a plan (dry run, no agents needed)
wb preview your-plan.md
# 5. Run a plan (requires an agent CLI)
wb run your-plan.md --no-tmux
wb: command not foundpip installed to a directory not on PATH. Common fixes:
# Check where pip installed it
python3 -m pip show wbcli | grep Location
# Add to PATH (add to ~/.bashrc or ~/.zshrc for persistence)
export PATH="$HOME/.local/bin:$PATH"
# Or use pipx for isolated installs
pipx install wbcli
tmux is required but not foundEither install tmux (see above) or run with --no-tmux:
wb run plan.md --no-tmux
Not in a git repositoryworkbench requires a git repo. Initialize one:
git init
git add .
git commit -m "initial commit"
pip install --user wbcli # install to user site-packages
# or
sudo pip install wbcli # system-wide (not recommended)
pip install --upgrade wbcli # upgrade the package
wb setup --update # update project-level skills
wb setup --global --update # update user-level skills