Introduction

Some workflows are easier to learn when someone shows you where to go and what to select. Use Codex to build a tour that guides users through your web app while they perform the actions themselves.

With WebMCP tools for your app’s controls, state, and documentation, Codex can choose the next instruction based on what the user sees. A user who hasn’t connected a service needs a different first step from someone who has already completed setup.

How to use

1. Open your app’s repository in Codex and choose one workflow to guide, such as connecting a service or adding a folder.
2. Provide the relevant documentation and describe the starting states the tour should handle.
3. Run the starter prompt on this page to add tour targets, UI-state tools, and access to the app’s instructions.
4. Test the flow in a browser environment where Codex can call your app’s WebMCP tools. Ask Codex to guide you, then complete each step yourself.

Keep the first tour narrow. Verify that it can guide a user from setup to completion before adding more workflows.

Example: Add a Google Drive folder in Runme

In Runme, users edit notebooks and use a file explorer to add Google Drive folders and navigate their files. The tour helps a new user find those controls and learn the flow.

To learn more about Runme, you can read Automating repetitive work at OpenAI with Codex.

Watch Codex highlight Runme’s controls and explain their purpose. The screenshots below show a separate, task-focused tour for adding a Google Drive folder.

The Google Drive tour starts with a request:

Connect Google Drive

Codex checks whether Google Drive is connected. If it isn’t, Codex highlights Connect Google Drive and asks the user to select it and complete the connection.

Open the file explorer

After the connection is complete, Codex guides the user to the file explorer. The next instruction follows the updated app state.

Add the folder

Once the user expands the toolbar, Codex highlights the control for adding a Google Drive folder. The user stays in control of the interaction and learns where to find it next time.

Give Codex the context to guide users

Runme’s implementation provides three kinds of context: tour targets, application state, and documentation. The tool names below come from Runme; adapt the same roles to your app.

Make controls discoverable

Give tour targets stable, semantic data-tour-id values, with a label and description for each. Runme exposes these controls through three WebMCP tools:

• listTargets lists the registered targets, IDs, labels, and descriptions.
• showTourStep({ target, title?, message, placement? }) highlights a target and displays an explanation.
• dismiss removes the highlight.

This gives Codex a way to identify and explain a control without performing its action for the user.

Read state and wait for the user

Runme keeps tour-related state outside React and exposes it through a controller. Its getUiSnapshot tool provides the current UI state, including sign-in status. waitForUiChange(...) lets Codex wait for a change, such as the user selecting the highlighted control.

Ask Codex to read the state again after each interaction. Advancing the tour should depend on what happened in the app, not on whether Codex has already shown an instruction.

Keep instructions with the app

Runme bundles Markdown documentation with the application and makes it available through WebMCP:

• readInstructionsForAIAgents explains how Codex should interact with the app and its tools.
• listDocumentation() lists the available pages and their descriptions.
• getDocumentation({ name }) returns a selected page as Markdown.

The tour instructions and tools can ship with the app, without a separate Codex plugin for the tour.

Review the tour

Try the same request from different starting states. Check that the tour skips completed setup, waits for the user, and updates its guidance when the UI changes.

Also test a canceled step and a control that isn’t visible yet. Codex should explain what is missing or choose a valid next step. It shouldn’t claim that an action succeeded just because it highlighted a button.

Keep authentication, permission checks, and user actions in the existing app flow. The tour should help users understand the interface without bypassing those controls.

Good follow-ups

Once the first flow works, continue in the same chat:

• “Test this tour when Google Drive is already connected and the file explorer is closed.”
• “Handle a user canceling a step, then asking to continue the tour.”
• “Add a tour for [next workflow], reusing the existing targets and state tools.”