configure-workbench

name	configure-workbench
description	Use when setting up workbench in a repo, configuring agent adapters (.workbench/agents.yaml), managing profiles (profile.yaml), or troubleshooting agent dispatch

Configuring Workbench

How to set up the wb CLI, configure agent adapters, and manage profiles for multi-agent orchestration.

When to Use

• Setting up workbench in a new repo (wb setup)
• Configuring which AI agents to use for each pipeline role
• Creating or editing .workbench/agents.yaml for custom agent adapters
• Creating or editing .workbench/profile.yaml to control agent behavior per role
• Troubleshooting agent dispatch, connection, or output parsing issues
• Switching between agent platforms (Claude, Antigravity, OpenCode, Codex, Cursor, Copilot)

Initial Setup

wb setup                           # auto-detect agent, install skills, create .workbench/
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 --profile                 # also create a profile.yaml
wb setup --global                  # install skills to user-level paths only

wb setup creates the .workbench/ directory, installs the bundled skill files for your agent platform, and optionally creates a starter profile.

Agent Adapters

Workbench dispatches work to AI coding agents via adapters. Each adapter knows how to invoke a CLI, pass the prompt, and parse the output.

Built-in Adapters

Name	CLI Command	Mode	Output
claude	claude -p <prompt>	Print mode, JSON output	Parses result and cost_usd from JSON
antigravity	agy -p <prompt>	Print mode, text output, dangerously-skip-permissions	Raw text
opencode	opencode run --auto <prompt>	Run mode, text output, auto-approved permissions	Raw text
codex	codex exec <prompt>	Full-auto, JSON events	Extracts last assistant message from NDJSON
cursor	agent -p <prompt>	Print mode, text output	Raw text
copilot	copilot -p <prompt>	Print mode, JSON output, no-ask-user	Extracts last assistant message from JSONL

Use --agent <name> on wb run or wb merge to select one:

wb run plan.md --agent antigravity
wb run plan.md --agent opencode
wb run plan.md --agent cursor

Initialize Agent Config

Generate .workbench/agents.yaml with all built-in adapter configs as a starting point:

wb agents init

This creates a YAML file you can customize. The file controls how each agent is invoked.

agents.yaml Format

agents:
  claude:
    command: claude
    args: ["-p", "{prompt}", "--output-format", "json", "--allowedTools", "Edit,Write,Read,Glob,Grep,Bash(git *),Bash(uv run *),Bash(cd *),Bash(ls *),Bash(npx *)"]
    output_format: json
    json_result_key: result
    json_cost_key: cost_usd
  my-custom-agent:
    command: my-cli
    args: ["--headless", "{prompt}"]
    output_format: text

Fields:

Field	Description	Default
command	CLI executable to run	(required)
args	Argument list. {prompt} is replaced with the agent prompt at runtime	["{prompt}"]
output_format	text or json	text
json_result_key	JSON key containing the agent's response	result
json_cost_key	JSON key containing cost/usage data	cost_usd

Managing Agents via CLI

wb agents init                    # create agents.yaml with built-in defaults
wb agents list                    # show built-in and custom agents
wb agents show claude             # show full config for an agent
wb agents add my-agent --command my-cli --args "--headless,{prompt}" --output-format json
wb agents add my-agent --command new-cli   # update an existing agent
wb agents remove my-agent         # remove a custom agent

Resolution Order

When wb run --agent <name> is used:

1. If .workbench/agents.yaml contains the name, use that config
2. If it's a built-in name (claude, antigravity, opencode, codex, cursor, copilot), use the built-in adapter
3. Otherwise, fall back to a generic adapter that passes the prompt as the sole argument

This means you can override a built-in adapter's behavior by adding an entry with the same name to agents.yaml.

Headroom (cost savings)

Route dispatched agents through a local headroom proxy to cut token costs (CLI -> localhost proxy -> provider API). Off by default.

Headroom is user-provided (not a workbench dependency). Install it yourself:

pipx install "headroom-ai[all]"    # requires Python 3.10+

Config

Add a top-level headroom: block (sibling of agents:) to .workbench/agents.yaml:

headroom:
  enabled: false        # off by default; set true to route agents through the proxy
  port: 8787            # local port the proxy listens on
  autostart: true       # start the proxy if nothing is listening on `port`
  command: headroom     # binary to invoke (default: `headroom`)

agents:
  # ... your agent adapters

CLI override

Override the config's enabled for a single run:

wb run plan.md --headroom         # force on
wb run plan.md --no-headroom      # force off
wb run plan.md                    # use the config value (default behavior)

How it runs

• One shared proxy per wb run — not one per agent.
• Auto-start if nothing is listening on port; reuse an existing listener if there is one.
• Teardown only what workbench started — an existing proxy keeps running.
• Wired today: claude (overlays ANTHROPIC_BASE_URL) and codex (overlays OPENAI_BASE_URL).
• Other adapters (gemini, cursor, copilot) are no-ops with a one-time warning until their base-URL overrides are verified.
• Missing binary? wb logs a warning with the install hint (pipx install "headroom-ai[all]") and continues — a run never fails over a cost optimization.

Profiles

Profiles control which agent and instructions are used for each pipeline role (implementor, tester, reviewer, fixer, merger).

Create a Profile

wb profile init                                        # create .workbench/profile.yaml
wb profile init --global                               # create ~/.workbench/profile.yaml
wb profile init --set reviewer.agent=antigravity       # with inline overrides
wb profile init --name fast --set reviewer.agent=antigravity  # named profile

profile.yaml Format

roles:
  reviewer:
    agent: antigravity
    directive: "Focus on security and correctness."
  tester:
    directive_extend: "Also check edge cases for null inputs."
  implementor:
    agent: codex

Only include roles and fields you want to override. Everything else uses built-in defaults.

Role Fields

Field	Description
agent	CLI command for this role (default: claude)
directive	Full replacement for the role's default instructions
directive_extend	Text appended to default instructions (cannot combine with directive)

Named Profiles

Store multiple configurations as profile.<name>.yaml:

wb profile init --name security --set reviewer.directive="Focus only on security vulnerabilities."
wb run plan.md --profile-name security

Profile Merge Order

Profiles merge in order (later overrides earlier):

1. Built-in defaults
2. ~/.workbench/profile.yaml (user-level)
3. .workbench/profile.yaml (project-level)
4. --profile <path> flag
5. CLI directive flags (--reviewer-directive, etc.)

Profile Commands

wb profile show                    # print resolved profile
wb profile show --name fast        # show a named profile
wb profile set reviewer.agent antigravity  # update a field
wb profile diff                    # show differences from defaults

Multi-Agent Configurations

Different Agents Per Role

Use profiles to assign different agents to different roles:

roles:
  implementor:
    agent: claude
  tester:
    agent: claude
  reviewer:
    agent: antigravity
  fixer:
    agent: claude

Or via CLI:

wb profile init --set implementor.agent=claude --set reviewer.agent=antigravity

Custom Instructions Per Role

Tailor agent behavior without changing the plan:

roles:
  tester:
    directive_extend: "Run pytest with -x flag. Focus on edge cases."
  reviewer:
    directive: "Review only for security vulnerabilities and data validation. Ignore style."

Or one-off via CLI flags:

wb run plan.md --reviewer-directive "Focus only on security issues."
wb run plan.md --tester-directive "Run pytest with -x flag, fail fast."

Customizing directives

A directive is the role-specific instruction text inserted at the top of every agent prompt. Each role and mode variant has a built-in default; the profile lets you replace or extend it.

Override precedence

Highest wins:

Layer	YAML field	Behavior
CLI flag	--implementor-directive, --tester-directive, --reviewer-directive, --fixer-directive	Full replace, one-shot. Wins over profile. Only available for these four roles.
Profile override	directive: "..."	Full replace. Persistent.
Profile extend	directive_extend: "..."	Appended to the built-in default with a blank line. Persistent.
Class default	(built-in)	The bundled text in workbench. Always used when nothing above applies.

The full directive map

Workbench uses 9 directive variants. Each has a YAML path that configures it:

Directive	YAML path	When used
Implementor	implementor.directive	Standard implement stage
Tester	tester.directive	Standard test stage
Reviewer (first pass)	reviewer.directive	First review of a task
Reviewer follow-up	reviewer.followup.directive	Re-review after a fix (attempts > 1)
Fixer	fixer.directive	After test or review failure
Merger	merger.directive	When merging branches produces conflicts
TDD Tester	tester.tdd.directive	wb run --tdd — writing failing tests first
TDD Implementor	implementor.tdd.directive	wb run --tdd — making failing tests pass
Planner	planner.directive	wb plan <prompt>

All 9 support both directive (full replace) and directive_extend (append) at their respective YAML paths.

Examples

Adding repo conventions to every implementation:

implementor:
  directive_extend: |
    All new modules must include a docstring with a one-line summary
    and a short example. Tests go in tests/ mirroring the source layout.

Note: for project-wide conventions that should apply across every plan (not just the implementor), prefer the dedicated file at .workbench/conventions.md — it's seen by implementor, tester, reviewer, fixer, summarizer, branch reviewer, and PR writer. Create it with wb conventions init (template) or wb conventions init --generate (agent-drafted). The directive_extend pattern above is appropriate when you want guidance scoped to a specific role.

Tighter tester verdict for a strict project:

tester:
  directive: |
    You are a strict testing agent. PASS only if every public function
    has at least one test, and all tests pass with zero warnings.
    [...]
    VERDICT: PASS
    VERDICT: FAIL

Per-project TDD style for the tester:

tester:
  tdd:
    directive_extend: |
      Use pytest fixtures for shared setup. Prefer parametrized tests
      over multiple near-duplicate tests.

Customizing the planner with project-specific conventions:

planner:
  directive_extend: |
    For this repo, every plan must include a "Manual verification" subsection
    in each task that lists steps to verify the change in a browser.

Validation errors

Sub-mode keys are only valid under specific roles. If you misplace one:

$ wb run plan.md
Error: merger does not support a 'tdd' sub-mode

tdd is only valid under implementor and tester. followup is only valid under reviewer.

CLI vs YAML

CLI flags are intentionally limited to the four most common roles (implementor, tester, reviewer, fixer). Other directives — reviewer follow-up, merger, TDD variants, and planner — are persistent overrides best set via the profile.

Troubleshooting

Agent not found

Error: Agent error: [Errno 2] No such file or directory: 'my-agent'

The command in agents.yaml or the --agent flag doesn't match an executable on PATH. Verify with which <command>.

Wrong output parsing

If agent output shows raw JSON or garbled text, check:

• output_format matches what the CLI actually produces
• json_result_key matches the key in the CLI's JSON output
• For custom agents, test the command manually: my-cli --headless "hello" and inspect output

Agent crashes in pipeline

Tasks that crash (agent timeout, connection error) show as failed with no fix attempts. Use --retry-failed to automatically re-run these:

wb run plan.md --retry-failed

For persistent failures, re-run specific tasks with adjusted settings:

wb run plan.md -b workbench-1 --task task-2 --implementor-directive "Try a simpler approach."

Viewing agent sessions

With tmux (default), attach to watch any agent work in real time:

tmux attach -t wb-task-1-implementor

Sessions are named wb-task-<N>-<role>. Use wb stop to kill all sessions.