DemoFlow for Codex

Turn a local web application into a live, explainable guided demo with a Codex prompt.

DemoFlow reads a local project to create a versioned demo.spec.json, then serves the running app through a loopback-only proxy that injects a temporary walkthrough overlay. It derives candidate routes and controls from React/Next.js source before the app starts, then verifies the chosen targets against the real running app. The original app remains interactive and its source code is not changed.

Every generated walkthrough can begin with a short, product-facing introduction: what changed or what the audience is about to see, before the first highlighted interaction.

Status

Build Week MVP. DemoFlow includes a packaged local MCP runtime, a loopback-only proxy, a live browser overlay, and a Vite/React sample application.

Install and use

Prerequisites

• Codex with plugin support.
• Node.js 20+ available as node in the environment that starts Codex.
• A local web app that can already run on the developer's machine. DemoFlow does not install the app's dependencies for it.

Install from GitHub

Run these commands once. They download and install the plugin; do not clone this repository or run pnpm install to use DemoFlow.

codex plugin marketplace add blacktomang/demoflow --ref main
codex plugin add demoflow@personal

Start a new Codex task after installation so its DemoFlow skill and MCP tools are available.

Create a guided demo

1. Open the local web-app project in Codex.
2. Ask, for example: Use DemoFlow to create a guided onboarding demo for this app.
3. Answer DemoFlow's compact Demo Brief: what you are showing (new feature, PR change, onboarding, or bug fix), who is watching, and what they should understand by the end. There is no duration estimate and no dashboard.
4. Choose a proposed product journey if the project has more than one viable starting flow. DemoFlow will not guess which capability you want to present.
5. Review the source-backed storyboard table—Step, User action, Why it matters, Evidence, and Confidence—and confirm or adjust it. Every real click is listed separately; typing plus its real submit button is the one compound action.
6. Review the generated editable flow at .demoflow/<demo-id>/demo.spec.json.
7. Approve Codex's native command prompt for the project's existing development script, or cancel/explain an adjustment there.
8. Open the returned Demo Mode localhost URL and click through the real application. The tooltips advance as the real app changes state.
9. Ask Codex to stop DemoFlow when you are finished.

DemoFlow never uploads project source code to a DemoFlow service, does not require an account or payment, and does not permanently modify application source. It writes only local .demoflow/ artifacts and injects the temporary overlay through a second loopback-only localhost URL. It never stages, commits, or pushes Git changes after generating or repairing a demo.

Repeated buttons

Codex chooses a repeated control while creating the saved demo spec. It prefers a test ID, then the visible title of the surrounding card. When the requested flow explicitly means the first (or another ordered) repeated control and no stable card title exists, the spec records a one-based occurrence; DemoFlow then attaches to that deterministic match rather than stopping the demo.

Walkthrough themes

DemoFlow defaults to presenter: a quiet, product-facing walkthrough intended for product reviews, stakeholder demos, and customers. A developer can ask Codex for minimal when the app should take almost all the visual attention, or debug for high-contrast selector repair. The selected theme is saved in demo.spec.json under presentation.theme; it changes only the injected overlay, never the host app.

Saved demos and freshness

Each saved demo contains an editable demo.spec.json and a small, shareable app-map.json snapshot. The snapshot contains framework hints, scripts, routes, test IDs, source-relative UI control summaries, labels, and a SHA-256 fingerprint—never raw source files, local paths, form data, or credentials.

Running a saved demo uses its existing spec and does not re-inspect the project. When a developer asks to validate freshness, DemoFlow rebuilds the compact map locally and compares fingerprints. A mismatch means the demo may be stale; it does not prove that the demo is broken. New-demo creation reuses its preceding inspection map when saving, avoiding a duplicate scan. DemoFlow never edits a target project's .gitignore: teams can ignore .demoflow/ locally or intentionally commit selected demo folders to share them.

DemoFlow runs its bundled runtime with the developer's own Node.js 20+ installation. It detects a missing or outdated Node.js version and prints a clear fix; it never depends on an internal ChatGPT/Codex Node runtime.

DemoFlow validates that the target app is reachable before it creates a preview. Use the exact Local: URL printed by the app's dev server; localhost and 127.0.0.1 are both loopback addresses but can be served differently by local tooling.

Full-stack and monorepo apps

DemoFlow can discover a local Demo Environment for a monorepo: the frontend package to scan, one existing root/package script to start, and loopback readiness URLs for required services such as an API. It does not start services itself; Codex shows its normal approval prompt for the single declared script, then DemoFlow waits for every declared service before it creates the browser preview. A project can make this deterministic with .demoflow/environment.json:

{
  "version": 1,
  "profiles": {
    "local-full-stack": {
      "label": "Local web and API",
      "appDirectory": "apps/web",
      "commandDirectory": ".",
      "start": { "script": "dev" },
      "appUrl": "http://localhost:5173",
      "readiness": [
        { "name": "Web app", "url": "http://localhost:5173" },
        { "name": "API", "url": "http://localhost:3001/health" }
      ]
    }
  }
}

All paths must stay inside the repository and every URL must be loopback HTTP. Profiles do not reset a database, manage credentials, modify .env, or execute arbitrary commands; real reset adapters remain a future feature.

DemoFlow supports React and Next.js UI that mounts conditionally after an action. When the next target is not in the DOM yet, the overlay waits and retries for up to five seconds before it reports a failed step. A label-based form target resolves to the associated input or textarea, so the walkthrough highlights the control that receives typing and can advance after its real submit action. The tooltip prefers above the real control and uses collision-aware fallback placement, keeping the active button or input visible and clickable. The last real action leads to a clear Demo complete panel with Restart and Close controls. Before writing a new flow, Codex ranks up to three likely customer-facing starting actions from the source map. It favors actions such as Preview or Start, deprioritizes Restore/Reset/Seed/Debug controls, and asks the developer to choose when the request has not named a start action. After a choice, review_storyboard returns a human-readable, source-backed table before demo.spec.json is written; unclear, ambiguous, or unsupported actions must be repaired in the storyboard rather than silently omitted from the demo.

Before saving a new spec, DemoFlow shows a human-readable storyboard with Step, User action, Why it matters, Evidence, and Confidence. When the source suggests more than one main customer flow, it presents the choices and waits for the developer to select one. Each independently clickable control becomes its own ordered demo step; only typing in a field followed by that field's real submit button is modeled as one input-and-click action. There is no maximum step count, so the complete selected flow remains in one demo.

For React and Next.js, the app map also records bounded JSX render prerequisites and nearby local state effects. A control such as Save my protocol can therefore be marked as requiring an active challenge rather than proposed as a clean-start demo. DemoFlow does not simulate APIs or databases: when source cannot prove how a required state is reached, Codex must offer a fixture-state choice instead of inventing a path.

Restart hard-reloads the configured start page when it is already open. This resets ordinary in-memory React state, such as TeachBack's current lesson step. It intentionally does not clear accounts, server state, or browser-persisted data; an app that needs those must provide a clearly identified local fixture/reset action.

Demo this branch

In a locally checked-out Git branch, ask: Use DemoFlow to demo what changed in this branch. DemoFlow compares the checked-out HEAD to the detected base branch (origin/HEAD, then main, master, or develop), returns the changed files and commits to Codex, and lets the developer choose a proposed flow or type their own focus. It never fetches a pull request, changes branches, or contacts GitHub. The saved spec records the compared branches and commit SHAs as provenance.

For a text or select field that takes effect immediately, Codex saves advance: { "type": "input-target", "minLength": 1 }. When a field must be filled and then submitted, it saves input-and-click with the real submit-button target, so the whole form action advances together. Older specs that use manual remain manual until regenerated or edited.

Repairing a browser failure

If Demo Mode says a target is unavailable or ambiguous, select Copy repair request in the browser and paste it into Codex—or simply tell Codex: Repair this DemoFlow preview. The browser has already saved a local report containing the failed step, target, route, and reason, plus bounded diagnostics from app error banners, browser errors, and unhandled rejections. Codex reads that report and updates only the broken step. It cannot repair silently while you are in the browser because an MCP server cannot wake a completed Codex task; this avoids hidden retries and unwanted restarts.

Install and test from a local checkout

The repository now includes a local Codex marketplace manifest at .agents/plugins/marketplace.json.

codex plugin marketplace add /absolute/path/to/demoflow
codex plugin add demoflow@personal

Restart Codex or start a new Codex task in a supported project after installing. For the included sample app, use the following prompt:

Use DemoFlow to inspect this project and create the onboarding guided demo.
Use the dev package script and the existing .demoflow/onboarding/demo.spec.json fixture.

DemoFlow will ask for approval before starting the project dev script. It should return a local Demo Mode URL; open that URL and click through the real onboarding flow. Node.js 20+ must be available as node in the environment that starts Codex; no DemoFlow package-manager install is required.

Contributor checks

cd plugins/demoflow/mcp-server
pnpm test
pnpm package-plugin

cd ../sample-app
pnpm build

For contributors

Repository cloning and pnpm install are contributor-only steps. They are used to change or verify DemoFlow itself, not to use a released plugin.

plugins/demoflow/mcp-server     # MCP source and tests
plugins/demoflow/overlay        # Browser overlay injected by the local proxy
plugins/demoflow/runtime        # Committed bundled runtime included in a plugin release
plugins/demoflow/sample-app     # Local verification app

Documents

• Product requirements
• Technical specification
• Build checklist
• Build Week video script

Intended experience

1. Open a supported app repository in Codex.
2. Ask DemoFlow for a short user journey.
3. Approve Codex's native command prompt for the local development script.
4. Open Demo Mode at a second localhost URL.
5. Click through the real application while tooltips explain each feature.

How it works

flowchart LR
  A["Project source code"] --> B["Codex + DemoFlow app map"]
  B --> C["demo.spec.json"]
  D["Local app: localhost:3000"] --> E["DemoFlow loopback proxy"]
  C --> F["Temporary browser overlay"]
  E --> F
  F --> G["Interactive Demo Mode"]

Loading

The proxy only serves the app through a second loopback URL and injects the overlay at runtime. It does not alter application source files. The transparent highlight ignores pointer events, so the user continues clicking the real UI.

Build Week / judge path

1. Install the DemoFlow plugin bundle in Codex.
2. Open plugins/demoflow/sample-app or another supported local React/Vite project.
3. Ask Codex to use the DemoFlow skill to create an onboarding flow.
4. Approve the project dev script.
5. Open the returned Demo Mode URL and complete the real four-step onboarding flow.

Codex was used to define the product flow, generate the structured demo specification, and operate the local MCP tools. The project keeps the model-facing context compact by using a deterministic app map rather than repeated browser screenshots or DOM dumps.

Local verification

The current first target is macOS + Node.js 20+ + a Vite/React sample app. The MCP server source is at plugins/demoflow/mcp-server.

No application source files are changed to enable Demo Mode. Generated specs live in .demoflow/; DemoFlow does not alter the target repository's Git-ignore rules.