WoZ architecture

Classical WoZ and WoZ architecture: the backstage operator becomes a general-purpose coding agent. Arrows show the application sending the prompt through tmux into the Claude Code harness. Conceptual illustration.

WoZ architecture is an application architecture in which an AI assistant's front end is powered by a regular, general-purpose coding agent harness, such as Claude Code, Codex, or pi agent. The application supplies the user-facing experience; the coding agent behind it does the work.

A WoZ system is an application built this way. A WoZ agent is the assistant exposed through that application.

The core idea is simple: put an existing coding agent behind the assistant interface. Its tasks need not be programming tasks. The application gives the agent context and access to the relevant workspace, files, tools, or application operations, then presents its responses and results through its own interface.

Behind the curtain

The side-by-side comparison shows the classical wizard facade with a human operator on the left, and the same facade powered by Claude Code inside tmux on the right. In this example, the application sends the message into the agent harness through tmux; the green bottom banner identifies the tmux session.

The prompt shown is:

You are the green, scary wizard of oz. Greet the user with your fierce and powerful voice.

How it works

User ↔ Application's assistant interface ↔ General-purpose coding agent harness
                                                       ↕
                                          Workspace, tools, application state

The harness supplies the agent loop: receiving instructions, working with context, invoking tools, and continuing until it can return a result. The application connects that loop to its own interface and domain. Much of the apparent specialization can come from instructions, available tools, and the environment the agent inhabits.

The agent is often headful: a normal interactive agent session, with its terminal or other interface available inside the application or to an operator. That interface may sit behind the application's assistant panel while the agent works in the background. A visible agent session is common in this conception, but the defining feature is the general-purpose harness powering the assistant.

Example

An illustrative example is a browser application with an assistant panel and a coding agent running in a background execution environment. A user asks the assistant to change something in the application; the application passes the request and relevant context to the agent; the agent uses its tools to do the work; and the application displays the result.

The motivating sketch is a browser application running Claude Code in a background webcontainer. This describes the intended arrangement, rather than a verified compatibility claim about that specific harness and runtime. The same architecture can place the harness in a local process, a container, or a remote execution environment.

What makes it WoZ

The architectural choice is to use a ready-made, general-purpose coding agent as the engine of an application's assistant. Merely calling a language model API does not establish that arrangement: the existing agent harness, including its execution loop and tooling, is the component being reused.

This can let an application inherit broad agent capabilities with relatively little application-specific orchestration. It also makes the integration responsible for connecting sessions, permissions, state changes, and results to the application's user experience. The assistant's practical capabilities depend on the tools and environment it is given.

Terminology

This entry records the term as defined for this wiki. WoZ architecture, WoZ system, and WoZ agent emphasize the arrangement, the application, and the assistant respectively; they describe the same underlying idea.