Woz: How We Harness Background Coding Agents

Woz is a user-facing orchestrator for background coding agents. It routes work to coding agents, runs multi-agent experiments, analyzes output diffs, and helps evolve the harness that powers those agents.

This repo contains the Woz runtime (src/) and the skills that define its orchestration workflows (skills/).

What Woz Is

Woz sits between a human operator and one or more background coding agents.

• For product-repo work, Woz delegates implementation to coding-agent branches.
• For comparison work, Woz runs the same prompt across multiple agent variants/rollouts.
• For harness evolution, Woz can update the coding-agent harness setup itself.

Why We Built It

We started with a mostly manual workflow:

• Long planning loops to avoid missing details.
• Frequent implementation defects even with good plans: duplication, subtle bugs, missing paths, semantic mismatches.

Adding critique loops and specialized agents increased quality significantly. We found that:

• There is no one-size-fits-all setup.
• Teams care about different failure modes.
• The right set of agents only becomes obvious while doing real work.

How We Use Woz

Our current loop is:

1. Human-owned planning (often with OpenSpec).
2. Woz routes implementation to one or more coding agents.
3. Woz runs side-by-side experiments when needed.
4. Woz analyzes diffs across resulting filesystems.
5. Humans review, pick direction, and iterate.

Core Flows

1. Run one coding agent

Woz forwards a prompt to one coding-agent branch and returns task references for follow-up.

2. Run multiple coding agents / rollouts

Woz creates a multi-agent experiment, tracks per-variant tasks, and reports status.

3. Analyze outputs

Woz pulls task filesystems, computes diffs, and summarizes implementation differences.

4. Update coding-agent harness

Woz can implement changes in the harness repo and support branch-based deploy workflows.

Quickstart

Prerequisites

• Python 3.12+
• uv
• An API key from Terminal Use

Install dependencies

uv sync

Deploy Woz

Before deploying, update the agent namespace in config.yaml:

agent:
  name: woz-ns/woz

Replace woz-ns with your Terminal Use namespace slug (for example, acme/woz).

tu deploy --config config.yaml

Env Vars

• TERMINALUSE_API_KEY
• ANTHROPIC_API_KEY
• SLACK_BOT_TOKEN (for Slack-thread flows)

Repo Layout

• src/: Woz runtime and routing logic.
• skills/: orchestration skills and helper scripts.
• tests/: unit tests for routing, delegation, hooks, and skills.

Open Source and Hosted Access

Note: This repo contains the Woz agent only. The companion platform — environment variable management, coding agent template installation, Slack bridge, and the web UI — will be open-sourced separately soon.

We also operate a hosted version of Woz here. We're prioritizing users who would like to build evals for their codebase and create auto-improving background coding agents.