Simulate Returning User
Testing & Qualitysimulate-returning-userSimulate Returning User is an Agent Skill for testing & quality published in the PostHog/posthog repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/PostHog/posthog/blob/HEAD/tools/traffic-sim/skills/simulate-returning-user/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/simulate-returning-user, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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_idacross page views in a session (no fresh anonymous IDs per page). - Confirm
$pageviewfires 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(default3) — number of page views in the session.interval(default5.0) — seconds between page views.posthog_host(defaulthttps://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: trueandpageviews >= page_views— the session works.- Same
distinct_idacross all pageviews (visible in PostHog UI under the run_id query param) — session stitching works. - Different
distinct_idper visit — likely a cookie domain or storage-permissions issue. Inspect the rawposthog_requestsfor$session_idvalues to diagnose.