Wizard architecture

Contents

The wizard is built in layers for composability. The context and skills, the agent, the program, and the TUI and CLI are each useful on their own, and composed together for the end experience.

  1. The CLI layer reads the command and starts a host.
  2. The host layer shows a run. The TUI draws it in the terminal, and the headless runner logs it.
  3. The program layer decides what to run, how many agents to spawn, and what each one gets. Its services, such as the session store and detection, do the work programs share.
  4. The agent layer runs AI work against the user's code. It has no opinion about what runs, and never sees the UI or the store.
src/clirunClisrc/tui · src/headlessrunTuirunHeadlessscreens · logsWizardAsksrc/programssrc/servicesrunProgramSessionStoredetection · scansframeworkssrc/programs/program-contractsrc/agentrunAgentAgentProgressinteraction.askswitchboardPi harnessAnthropic harnessgateway · MCP · skillssrc/shared · src/envoptionaloptional

The two left lanes are the calls going down, one per host. The third lane is progress coming back up into the store, and the right lane is a question for the user coming back up. Both are optional, so they're dotted: runAgent only sends progress through onProgress and questions through interaction.ask when the host passes them in. Each colour is one owner: grey for the CLI, purple for the hosts, green for the program layer, and blue for the agent. The program layer's three bands are the programs, the services they consume, and the program contract below both, which they import. The dashed box is outside the wizard repo: the AI gateway, the PostHog MCP server, and context mill skills. The bottom band is shared code every layer imports.

The CLI layer

The CLI reads the command and starts the right host. See the CLI README.

The host layer

A host starts a program and shows the run. You can build a new host without changing any program.

TUI

The TUI draws the run in the terminal. The screen is derived from the store's state, there's no manual navigation. This TUI is built with the Ink.js library.

See the TUI README for details.

Headless runner

The headless runner logs the run instead of drawing it. CI, the workbench, benchmarks, and cloud runs use it.

See the headless README for details.

The program layer

A program is a job with a purpose, like "set up error tracking". The program decides everything the agent doesn't:

  • How many agents to spawn, and in what order.
  • What each agent does, and when it's done.
  • What each agent gets to succeed: extra tools, extra MCP tools, and skills.

Programs can't import each other, so a product team can own its program without touching anyone else's. You can also run a program from code. See the programs README.

The program layer has three parts, which import in one direction:

  • The program contract defines what a program is: ProgramConfig, ProgramSession, RunnerContext and FrameworkConfig. It imports no service. It lives in src/programs/program-contract/.
  • Services are what programs consume: the session store, detection, the framework configs, the codebase scan and the warehouse tool catalog. They live in src/services/.
  • Programs are the jobs themselves, one folder each in src/programs/. The program runner, runProgram, runs them.

A service knows what a program, a session or an agent run is. Code that doesn't goes in src/shared. Each part is its own TypeScript project, so an import in the wrong direction fails the type check. See the services README.

Session store

The session store is a service. It holds the state of one run. Programs write to it, and hosts read from it. It also streams that state into the PostHog app. See the services README.

Login

The user logs in once with OAuth, or CI uses an API key. A user with no PostHog account can sign up from the wizard. See the programs README.

The agent layer

The agent runs one job and has no opinion about what runs. You can run it on its own from code. See the agent README.

  • Switchboard. Picks the route.
  • Sequence. Linear runs one conversation. Orchestrator runs a planner and then a queue of tasks.
  • Harness. Pi or Anthropic. It calls the model through the PostHog AI gateway.
  • Tools. The harness calls tools on the PostHog MCP server and on the wizard's own tools server.
  • Warlock. Scans every command the harness runs, and everything it writes and reads.

Switchboard

The switchboard decides what model runs each task at what effort on which SDK. A developer, a feature flag, a skill, or a program can set it. See the switchboard README.

Tools

The agent uses the hosted PostHog MCP server, and the wizard's own tools for the jobs a generic agent gets wrong. See the agent README.

Skills

Skills come from the latest context mill release, and the wizard installs them into the user's project. See the shared README.

Cloud runs

The wizard can run in a cloud sandbox from the PostHog app, through the headless runner, with its progress streamed back into PostHog. See the headless README.

Audits

An audit reads the user's code and their PostHog project. wizard audit runs the comprehensive all audit by default. Run wizard audit events for the events-only audit. Each audit subcommand is a context mill skill, for example wizard audit events is the audit-events skill.

The agent audits the code in place, where the wizard runs. It does not upload or copy the repository. It finds PostHog calls with Grep, and subagents Read only the files that it needs. The model sees the prompt, the content that the agent reads, and the results of its tool calls, through the PostHog AI gateway.

The events audit uses two sources:

  • The code. Capture call sites, event names, and properties. Each finding has a file:line.
  • The PostHog project. SQL through the PostHog MCP server, for example which events saved insights use, and how much of the volume is pageviews. These findings come from the project, not from a line of code. If MCP is not available, these checks become suggestions and the audit continues.

The events audit is read-only:

  • The skill tells the agent not to edit project files or change PostHog. It writes only a Markdown report at the project root, and a checks ledger that it deletes at the end.
  • The wizard blocks Read and Grep on .env files.
  • Warlock scans the content that the agent reads for prompt injection, and the content that it writes for secrets.

When notebook tools are available, the comprehensive audit can create a PostHog notebook and add its Markdown report to it. This writes the report to the PostHog project.

The audit also accepts the headless flag, so it can run as a cloud run on a copy of the repository instead of on the user's machine.

Go deeper

Was this page useful?