posthog/ai-plugin

investigating-replay

Investigates a session recording by gathering metadata, person profile, same-session events, and linked error tracking issues in one pass.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/posthog/ai-plugin --skill investigating-replay

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Investigating a session recording

When a user asks "what happened in this session?" or provides a recording/session ID to investigate, gather all relevant context in parallel rather than making them ask for each piece.

Available tools

ToolPurpose
posthog:session-recording-getRecording metadata (duration, counts, status)
posthog:persons-retrievePerson profile (properties, distinct IDs)
posthog:execute-sqlQuery events, errors, and page views in session
posthog:query-error-tracking-issues-listFind error tracking issues linked to the session
posthog:vision-observations-listCheck for an existing Replay Vision AI summary
posthog:vision-observations-getRead one observation in full (scanner_result)
posthog:vision-scanners-inline-scanGenerate an AI summary of the session (slow, optional)
posthog:vision-scanners-listFind saved summarizer scanners (scanner_type=summarizer)
posthog:vision-scanners-scan-sessionRun a saved summarizer scanner on the session (slow)

Workflow

Step 1 — Get recording metadata and person profile

Start with the recording to get metadata and the person's distinct ID:

json
posthog:session-recording-get
{
  "id": "<session_id>"
}

The recording id and the event $session_id are the same value. It selects the recording here and the same-session events in Step 2. The response includes distinct_id, person, start_time, end_time, duration, interaction counts, console error counts, and viewing status. Use the distinct_id to fetch the full person profile:

json
posthog:persons-retrieve
{
  "id": "<person_uuid_from_recording>"
}

Step 2 — Query same-session events

Use the recording id from Step 1 as the $session_id value. Get the timeline of what the user did during the session:

sql
posthog:execute-sql
SELECT
    timestamp,
    event,
    properties.$current_url AS url,
    properties.$browser AS browser,
    properties.$os AS os,
    properties.$device_type AS device_type,
    properties.$screen_width AS screen_width
FROM events
WHERE $session_id = '<session_id>'
ORDER BY timestamp ASC
LIMIT 200

For sessions with many events, focus on the most informative ones:

sql
posthog:execute-sql
SELECT
    timestamp,
    event,
    properties.$current_url AS url,
    if(event = '$exception', properties.$exception_values[1], null) AS exception_message,
    if(event = '$exception', properties.$exception_types[1], null) AS exception_type
FROM events
WHERE $session_id = '<session_id>'
    AND event IN ('$pageview', '$pageleave', '$autocapture', '$exception', '$rageclick')
ORDER BY timestamp ASC
LIMIT 100

No rows? Recover the event session ID

The recording id is the session ID. No rows means the session's events were ingested without it. Find candidates from the person's events in the recording window, padded by 100 seconds like the replay events query. person_id covers all of the person's distinct IDs:

sql
posthog:execute-sql
SELECT
    properties.$session_id AS session_id,
    count() AS event_count,
    min(timestamp) AS first_seen,
    max(timestamp) AS last_seen
FROM events
WHERE person_id = '<person_uuid>'
    AND timestamp >= toDateTime('<start_time>') - INTERVAL 100 SECOND
    AND timestamp <= toDateTime('<end_time>') + INTERVAL 100 SECOND
    AND properties.$session_id IS NOT NULL
GROUP BY session_id
ORDER BY event_count DESC
LIMIT 10

Continue only when one session ID clearly matches. Use it for the Step 2 and Step 3 queries only. The replay URL and all Replay Vision calls take the recording id.

Step 3 — Check for linked error tracking issues

If the recording has console errors or exceptions, find related error tracking issues:

sql
posthog:execute-sql
SELECT DISTINCT
    properties.$exception_fingerprint AS fingerprint,
    properties.$exception_types[1] AS type,
    properties.$exception_values[1] AS message,
    count() AS occurrences
FROM events
WHERE $session_id = '<session_id>'
    AND event = '$exception'
GROUP BY fingerprint, type, message
ORDER BY occurrences DESC
LIMIT 10

If fingerprints are found, search for the corresponding error tracking issues to provide links and status:

json
posthog:query-error-tracking-issues-list
{
  "searchQuery": "<exception_type or message>"
}

Step 4 — Synthesize the investigation

Present the findings as a coherent narrative:

  1. Who — person properties (name, email, country, plan, etc.)
  2. What — sequence of pages visited and key actions taken
  3. Problems — exceptions, console errors, rage clicks, and their frequency
  4. Related issues — linked error tracking issues with their status (active/resolved)
  5. Context — session duration, device/browser, activity score

Optional: AI summary via Replay Vision

If the user wants a deeper analysis without reading through events manually, offer a Replay Vision summary. Follow "check-then-scan" — don't scan blindly, a scanner can only observe a given session once.

  1. Check for an existing summary. A scheduled scanner may already have one:
json
   posthog:vision-observations-list
   {
     "session_id": "<session_id>"
   }

The rows come back narrowed to id, session_id, status, summary_line and scanner_id. Look for one whose status is succeeded, then read it in full with vision-observations-get for that id: its scanner_snapshot.scanner_type tells you whether it is a summarizer, and scanner_result.model_output carries title, summary, intent, outcome, friction_points and keywords. If you find one, you are done — no new scan needed.

  1. Generate one with an inline scan of the built-in summary. It runs the same scan as

the player's Summarize button, so a summary either of you started is shared, while a prompt of your own mints a separate scanner and a separate summary.

json
   posthog:vision-scanners-inline-scan
   {
     "session_ids": ["<session_id>"],
     "built_in": "summarize_recording"
   }

Leave model out so the server default applies. Warn the user this is async and takes several minutes (rasterize + LLM). Nothing is scheduled and there is nothing to clean up: the scanner an inline scan mints never sweeps on its own. A 400 here usually means the organization has not approved AI data processing yet.

  1. Read `results[0].scan_outcome` before polling. started means poll

vision-observations-list (step 1) until the new observation reaches succeeded. already_scanned means a terminal observation already exists — read it via step 1, and if its status is failed or ineligible say so rather than polling. A null scan_id or skipped_quota means nothing ran: report the quota, do not poll.

The project already has a summarizer scanner

Use an inline scan for a one-off summary even then. Only reach for a saved scanner when the user wants that scanner's own prompt rather than the built-in one:

json
posthog:vision-scanners-list
{
  "scanner_type": "summarizer"
}

Show the user the scanners (name + prompt), ask which to use, then run it against the session and poll vision-observations-list until the observation reaches succeeded:

json
posthog:vision-scanners-scan-session
{
  "id": "<scanner_id>",
  "session_id": "<session_id>"
}

Never create a scanner to answer a single question — vision-scanners-create leaves a scheduled sweep behind that the inline scan does not.

Tips

  • Run steps 1-3 in parallel when possible — they're independent queries.
  • If the recording has very few events, the session was likely very short.

Note this rather than suggesting something is broken.

  • Console error count from the recording metadata is a good signal for whether

to dig into exceptions. If it's 0, skip step 3.

  • The start_url from the recording tells you where the user's journey began —

use this to frame the narrative.

  • If person is null on the recording, the user was anonymous.

Person properties won't be available, but events still are.

Related skills

  • `finding-sessions-to-watch` — choose which sessions are worth investigating in the first place
  • `finding-replay-for-issue` — start from an error tracking issue and find its linked recordings
  • `diagnosing-missing-recordings` — when a recording that should exist doesn't
  • `creating-replay-vision-scanners` — automate this kind of watching as a scheduled scanner
from this repository

More skills

All skills
posthog
Official

exploring-llm-costs

Investigate LLM spend in PostHog — total cost over time, cost by model, provider, user, trace, or custom dimension, token and cache-hit economics, and cost regressions. Use when the user asks "how much are we spending on LLMs?", "which model / user / feature is most expensive?", "why did cost spike?", wants to build a cost dashboard or alert, or pastes a trace URL and asks about its cost.

1h installs
2
GitHub stars
98
Updated
Nov 6
posthog
Official

exploring-llm-traces

Debug and inspect LLM/AI agent traces using PostHog's MCP tools. Use when the user pastes a trace or session URL (e.g. /ai-observability/traces/ or /ai-observability/sessions/ ), asks to debug a trace, figure out what went wrong, check if an agent used a tool correctly, verify context/files were surfaced, inspect subagent behavior, investigate LLM decisions, or analyze token usage and costs. Also use when raw SQL/HogQL against events.properties.$aiinput / $aioutputchoices returns empty — message

1h installs
2
GitHub stars
98
Updated
Nov 6
posthog
Official

instrument-integration

Add PostHog SDK integration to your application. Use when setting up PostHog for the first time or reviewing PRs that need PostHog initialization. Covers SDK installation, provider setup, and basic configuration for any framework.

1h installs
2
GitHub stars
98
Updated
Nov 6
posthog
Official

investigating-error-issue

Investigates a single PostHog error tracking issue end-to-end. Use when the user provides an issue ID or pastes an issue URL (/error-tracking/ ) and wants to understand the error — who it affects, what triggers it, when it started, whether it correlates with a release, browser, OS, or feature flag, and what the next step should be. Pulls aggregated metrics, sample exception events, segment breakdowns, linked replays, and synthesizes a hypothesis-grade summary in one pass.

1h installs
2
GitHub stars
98
Updated
Nov 6