PostHog Handbook Library / Wizard And Docs

1,976 words. Estimated reading time: 9 min.

Wizard architecture

Auto TL;DR

At a Glance

This long page covers these main areas. The list is generated from the article headings, so it updates with every handbook rebuild.

  1. The CLI layer
  2. The host layer
  3. TUI
  4. Headless runner
  5. The program layer
  6. Session store
  7. Login
  8. The agent layer

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.

<defs><marker id="wizard-arch-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="currentColor" fillOpacity="0.7" /></marker></defs>

<text x="342.0" y="13.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12">src/cli</text>

<text x="164.0" y="74.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12" fontFamily="ui-monospace, monospace">runCli</text>

<text x="342.0" y="135.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12">src/tui · src/headless</text>

<text x="75.0" y="196.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12" fontFamily="ui-monospace, monospace">runTui</text>

<text x="253.0" y="196.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12" fontFamily="ui-monospace, monospace">runHeadless</text>

<text x="431.0" y="196.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12" fontFamily="ui-monospace, monospace">screens · logs</text>

<text x="609.0" y="196.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12" fontFamily="ui-monospace, monospace">WizardAsk</text>

<text x="215.0" y="257.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12">src/programs</text>

<text x="520.0" y="257.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12">src/services</text>

<text x="164.0" y="318.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12" fontFamily="ui-monospace, monospace">runProgram</text>

<text x="431.0" y="318.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12" fontFamily="ui-monospace, monospace">SessionStore</text>

<text x="609.0" y="311.5" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="11" fontFamily="ui-monospace, monospace">detection · scans</text> <text x="609.0" y="324.5" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="11" fontFamily="ui-monospace, monospace">frameworks</text>

<text x="297.0" y="379.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12">src/programs/program-contract</text>

<text x="342.0" y="435.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12">src/agent</text>

<text x="164.0" y="496.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12" fontFamily="ui-monospace, monospace">runAgent</text>

<text x="431.0" y="496.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12" fontFamily="ui-monospace, monospace">AgentProgress</text>

<text x="609.0" y="496.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12" fontFamily="ui-monospace, monospace">interaction.ask</text>

<text x="164.0" y="562.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12" fontFamily="ui-monospace, monospace">switchboard</text>

<text x="75.0" y="628.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12" fontFamily="ui-monospace, monospace">Pi harness</text>

<text x="253.0" y="628.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12" fontFamily="ui-monospace, monospace">Anthropic harness</text>

<text x="164.0" y="694.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12" fontFamily="ui-monospace, monospace">gateway · MCP · skills</text>

<text x="342.0" y="755.0" textAnchor="middle" dominantBaseline="central" fill="currentColor" fontSize="12">src/shared · src/env</text>

<text x="437.0" y="351.0" dominantBaseline="central" fill="currentColor" fillOpacity="0.7" fontSize="10" fontStyle="italic">optional</text>

<text x="698.0" y="351.0" textAnchor="end" dominantBaseline="central" fill="currentColor" fillOpacity="0.7" fontSize="10" fontStyle="italic">optional</text>

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:

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:

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.

%%{init: {"block": {"padding": 32}}}%%
block-beta
  columns 3
  space run["runAgent"] space
  space sb["switchboard"] space
  space seq["linear · orchestrator"] space
  w["Warlock"] h["Pi · Anthropic"] mcp["MCP tools"]
  space gw["AI gateway"] space

  run --> sb
  sb --> seq
  seq --> h
  h --> gw
  w --> h
  h --> mcp

  classDef agent fill:#3b82f626,stroke:#3b82f6,stroke-width:2px
  classDef ext fill:none,stroke:#9ca3af,stroke-dasharray:4 3
  class run,sb,seq,h,w agent
  class gw,mcp ext

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 events audit is read-only:

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

Canonical URL: https://posthog.com/handbook/wizard-and-docs/wizard-architecture

GitHub source: contents/handbook/wizard-and-docs/wizard-architecture.mdx

Content hash: 7bf3a23b943e38fc