Labsco
PostHog logo

simulate-returning-user

★ 35,336

by posthog · part of posthog/posthog

Send synthetic single-session multi-page traffic to a URL and confirm PostHog $pageview events fire across page views. Use when verifying that cookies persist correctly, that the same distinct_id is reused across navigations, or when debugging session-stitching issues.

🧰 Not standalone. This skill ships with posthog/posthog and only works together with that tool — install the tool first, then add this skill.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

Simulate returning-user traffic

Drives a single browser context across N page views (cookies and localStorage persist), navigating between pages and reporting which PostHog events fired. This matches the behavior of a single visitor browsing multiple pages on the same site.

When to use

  • Confirm that PostHog reuses the same distinct_id across page views in a session (no fresh anonymous IDs per page).
  • Confirm $pageview fires on every page view, not just the first.
  • Reproduce "session not stitching" or "events split across multiple users" reports.

How to invoke

Call the simulate_returning_user MCP tool with:

  • url (required) — the page to visit each iteration.
  • page_views (default 3) — number of page views in the session.
  • interval (default 5.0) — seconds between page views.
  • posthog_host (default https://us.i.posthog.com).

To exercise multi-page navigation, call the tool once per URL — the cookies won't carry across calls (each call is a separate Playwright context). For true multi-page browsing within one session, edit the URL list passed to the underlying CLI: traffic-sim returning-user --url A --url B --url C.

Interpreting the result

The structured response shape matches simulate_new_user. Key signals:

  • verified: true and pageviews >= page_views — the session works.
  • Same distinct_id across all pageviews (visible in PostHog UI under the run_id query param) — session stitching works.
  • Different distinct_id per visit — likely a cookie domain or storage-permissions issue. Inspect the raw posthog_requests for $session_id values to diagnose.