Open source · MIT License

Guided tours for your WordPress clients.

Drop a JSON file in the plugin folder. The right user sees the right tour, once. No support docs. No screen recordings. No hand-holding.

↗ View on GitHub Quick Install ↓

Latest release v1.2.0

PHP 7.4+ · WordPress 6.0+ · Zero JS dependencies

A multi-page tour: steps 1–2 on the Orders page, then the tour navigates and resumes on a new page at step 3

localhost/wp-admin/admin.php?page=wc-orders localhost/wp-admin/post-new.php?post_type=bh_event

My WordPress Site + New

Howdy, admin

Orders + Add order

#	Customer	Date	Total	Status
#1042	Sarah Marchetti	May 2, 2026	$89.00	Processing
#1041	James Hoffmann	May 1, 2026	$45.50	Completed
#1040	Priya Krishnamurthy	Apr 30, 2026	$120.00	Pending payment

Add New Event

Start writing or type / to choose a block

Why it exists

Built for one specific problem.

WordPress developers hand off sites to clients who don't know where anything is. The usual solutions are a screen-recorded video nobody watches, a Google Doc nobody opens, or a recurring support call you don't charge for. WP Client Tour is a different answer: a guided overlay that fires once, inside wp-admin, exactly when the client needs it.

There are good general-purpose tour libraries like Shepherd.js and Intro.js, and SaaS products like Appcues and Intercom Product Tours. They're well-built tools for product teams building onboarding flows in their own apps. WP Client Tour isn't trying to compete with them on features. It's a narrower tool that solves a narrower problem: getting a client oriented in someone else's WordPress admin, with zero configuration overhead and no monthly fee.

	WP Client Tour	Shepherd / Intro.js	Appcues / SaaS
Cost	Free, MIT	Free, open source	$200–2,000+/mo
WordPress-native	Yes — role-aware, WP meta, REST	Needs custom integration	JS snippet, no WP context
Setup	Drop a JSON file	Code per tour	Visual editor v2.0 roadmap
Multi-page tours	Yes	No (page-bound)	Yes
Manual triggers / replay	Admin bar, shortcode, PHP helper, dashboard widget	No	Yes
Works offline / no CDN	Yes	Depends on setup	No
Version-controllable tours	Yes (flat JSON files)	Yes (code)	Database / SaaS only
AI authoring	Built-in skill (Claude Code, ChatGPT, Cursor…)	No	Some products, extra cost
Target audience	WordPress developers	Any web developer	Product/marketing teams

How it works

JSON in. Guided tour out.

The plugin and the AI authoring skill never communicate directly. The bridge is a flat JSON file on disk — version-controllable, portable, hand-editable.

01 — Author (optional)

Describe the workflow. Get the JSON.

The bundled AI authoring skill screenshots a real wp-admin page, identifies the UI elements your client needs to understand, and produces a ready-to-deploy tour.json with selectors, copy, and confidence flags. Works with Claude Code, ChatGPT, Cursor, or any LLM. Or write it yourself in 15 minutes — the schema is documented and small.

02 — Deploy

Drop the file. Done.

Save the JSON into tours/ inside the plugin folder. No database import, no admin UI step, no server restart. The plugin scans that directory on every admin page load — if the file validates, it is live.

03 — Deliver

The right person sees the right tour.

Each tour targets a page and a set of user roles. auto_once fires on the first matching visit and marks it complete. The client never sees it again. You never get the call.

Features

Built for real client sites.

No frameworks, no external services, no build step. Works on any WordPress 6.0+ install out of the box.

Role-aware delivery

Each tour targets specific WordPress roles. A tour for shop_manager won't fire for administrators. One JSON file per workflow, not per user.

Set and forget

auto_once fires the tour on first visit and never again. Completion lives in user meta. Test Mode lets you re-watch tours without resetting data.

Zero JS dependencies

The renderer is vanilla ES6. No jQuery, no Shepherd.js, no CDN calls. The entire JS file is under 15 kB, unminified and readable. Nothing conflicts with other plugins.

Multi-page tours

Steps can span multiple admin pages. A step on the Posts list can navigate to the block editor, where the tour resumes at the exact right step. Global step counter throughout.

AI authoring

A bundled authoring skill screenshots any wp-admin page and produces tour JSON from a real browser view. Works with Claude Code, ChatGPT, Cursor, and others. Each step gets a confidence flag so you know which selectors to verify.

Version-controllable tours

Tours are flat JSON files. Commit them to git, diff them, copy them between sites. No database import involved. Rollback a bad tour by reverting a file.

Dashboard tour launcher

Enable the Dashboard Widget in settings to give clients a central panel listing all their tours, with completion checkmarks and one-click Start and Replay buttons.

Manual triggers

Set trigger: "manual" and launch tours on demand via the admin bar Tours menu, the [wct_launch] shortcode, or the wct_tour_launch_url() PHP helper. Ideal for help links and onboarding flows.

Tour JSON Schema

The whole API, in one file.

A tour is a single JSON file in wp-content/plugins/wp-client-tour/tours/. Here is everything you can put in it.

woocommerce-orders.json

{
  "id":           "woocommerce-orders",
  "label":        "WooCommerce Orders",
  "target_page":  "admin.php?page=wc-orders",
  "target_roles": ["editor", "shop_manager"],
  "trigger":       "auto_once",
  "created":       "2026-05-01",
  "steps": [
    {
      "id":               "step-1",
      "selector":         "#toplevel_page_woocommerce",
      "position":         "right",
      "title":            "Your WooCommerce Menu",
      "body":             "Everything for your store lives here.",
      // navigate to another page on Next click
      "navigate_on_next": "admin.php?page=wc-orders",
      "navigate_label":   "View Orders"
    },
    {
      "id":          "step-2",
      // which page this step lives on (multi-page tours)
      "target_page": "admin.php?page=wc-orders",
      "selector":    ".wc-orders-list-table",
      "position":    "top",
      "title":      "Your Order List",
      "body":       "Each row is one customer order."
    }
  ]
}

id required

Unique tour identifier. Lowercase letters, digits, hyphens only. Used as the filename and in per-user completion tracking.

target_page required

The wp-admin URL path after /wp-admin/. Query string matched against $_GET — extra params on the live page won't break the match.

target_roles required

Array of WordPress role slugs. Tour only fires for users with one of these roles. An empty array fails validation silently — the tour won't fire for anyone.

trigger required

auto_once fires once per user, then never again. auto_always fires on every matching page load. manual never fires automatically — launch via admin bar, [wct_launch] shortcode, or wct_tour_launch_url().

navigate_on_next v1.1 · optional

Relative admin path on a step. Clicking Next navigates there and resumes the tour at the following step. Absolute URLs and path traversal are rejected by the loader.

step.target_page v1.1 · optional

Which admin page this step belongs to. Steps on other pages are silently skipped on render. Used for the global step counter in multi-page tours.

confidence optional

high / medium / low. Authoring metadata only — not used at runtime. Tells you which AI-generated selectors need manual verification.

Installation

Two ways to get started.

The plugin installs like any other WordPress plugin. The AI authoring skill is optional — for generating tours from real screenshots using any LLM.

WordPress Plugin

Works on any WordPress 6.0+ site. No build step, no npm, no Composer.

Clone or download the repo. Copy plugin/wp-client-tour/ into your site’s wp-content/plugins/ directory.

Activate WP Client Tour from Plugins › Installed Plugins in wp-admin. The activation hook creates the tours/ directory automatically.

Drop a JSON tour file into tours/. Reload wp-admin as a user with the target role. The tour fires.

Go to Settings › WP Client Tour to see loaded tours, toggle Test Mode, or reset completion state for any user.

AI Authoring

Works with any LLM. Claude Code users get automated screenshots via Playwright MCP. Everyone else can use the standalone prompt.

Claude Code: copy the skill into your global skills directory (see README). Playwright MCP handles screenshots automatically.

Any other LLM: paste skill/prompt.md as a system prompt or at the top of a new conversation. Share a screenshot of the target page for best results.

macOS / Linux

mkdir -p ~/.claude/skills/wp-client-tour
cp skill/wp-client-tour.md \
  ~/.claude/skills/wp-client-tour/SKILL.md
cp -r skill/examples \
  ~/.claude/skills/wp-client-tour/

In any project, ask your AI: "Create a client tour for /wp-admin/admin.php?page=wc-orders". It screenshots the page, identifies elements, writes the steps.

Review the confidence flags on each generated step. low means the selector was inferred — verify it with DevTools before shipping.

Roadmap

Where things are headed.

All milestones and open issues are tracked on GitHub. Pull requests welcome — items labelled good first issue are good starting points.

Version	Theme	Status
1.0.0	Core delivery — JSON-driven tour engine, role-aware, REST API, admin settings, AI authoring skill	Released
1.1.0	Multi-page tours — cross-page navigation via URL params, global step counter, cross-page Back	Released
1.2.0	Manual triggers — admin bar Tours menu, `[wct_launch]` shortcode, `wct_tour_launch_url()` PHP helper, dashboard widget includes manual tours	Released
1.3.0	Admin UI simplification — show/hide wp-admin menu items per role, configured in JSON	Planned
1.4.0	Analytics — step-level funnel, completions, drop-off, CSV export. No external services.	Planned
2.0.0	Visual tour editor — click any element to capture its selector, write copy inline, export to JSON	Planned

View all open issues on GitHub →