posthog-debugger

What this skill does

# PostHog Debugger

Inspect and debug PostHog implementations on any website using browser automation tools. This skill helps developers and product teams understand exactly how PostHog is configured and what data is being captured.

## Critical Rules

1. **Always ask for the URL first** if not provided.
2. **Always ask if the page requires login.** If yes, guide the user to log in via Chrome first.
3. **Use browser tools to navigate and inspect.** Prefer Chrome DevTools MCP (`mcp__chrome-devtools__*`) or Playwright MCP (`mcp__playwright__*`) tools.
4. **Check multiple signals.** PostHog can be implemented in various ways - check scripts, network requests, and the window object.
5. **Report findings clearly.** Summarize what you find in a structured format.
6. **Never modify anything.** This is read-only inspection.

## Initial Flow

When a user asks to inspect a PostHog implementation:

1. **Get the URL** (if not provided)
2. **Navigate to the URL** with `?__posthog_debug=true` appended
3. **Check if login is required** by taking a snapshot and looking for login indicators
4. **If login required**, ask the user to authenticate in the browser
5. **Once authenticated**, proceed with inspection

## Detecting Login Pages

After navigating, take a snapshot and look for login indicators:
- Page title contains "login", "sign in", "authenticate"
- URL contains "login", "signin", "auth", "sso"
- Page has username/password fields
- Page shows "Sign in with Google/GitHub/etc." buttons

## Authenticated Pages Workflow

If you detect a login page or the user mentions the page requires auth:

1. **Keep the browser open** - you've already navigated there
2. **Ask the user to log in:**
   ```
   "This page requires authentication. Please log in using the Chrome browser I just opened. Let me know when you're logged in and on the page you want to inspect."
   ```

3. **Once the user confirms**, take a new snapshot to verify they're authenticated

4. **Add the debug parameter** if not already present and reload if needed

5. **Proceed with inspection**

## Available Browser Tools

### Chrome DevTools MCP
- `mcp__chrome-devtools__navigate_page` - Navigate to URL
- `mcp__chrome-devtools__take_snapshot` - Get page accessibility tree
- `mcp__chrome-devtools__evaluate_script` - Run JavaScript to inspect PostHog
- `mcp__chrome-devtools__list_network_requests` - See network traffic
- `mcp__chrome-devtools__get_network_request` - Get request details
- `mcp__chrome-devtools__list_console_messages` - Check for errors

### Playwright MCP
- `mcp__playwright__browser_navigate` - Navigate to URL
- `mcp__playwright__browser_snapshot` - Get page snapshot
- `mcp__playwright__browser_evaluate` - Run JavaScript
- `mcp__playwright__browser_network_requests` - See network traffic
- `mcp__playwright__browser_console_messages` - Check console

## Inspection Workflow

### Step 1: Navigate to the Page with Debug Mode

**Always add `?__posthog_debug=true`** to the URL to enable PostHog's debug mode. This outputs detailed logs to the console.

- If URL has no query string: `https://example.com?__posthog_debug=true`
- If URL already has query string: `https://example.com?foo=bar&__posthog_debug=true`

**Workflow:**

1. **Navigate to the URL** with the debug parameter
2. **Take a snapshot** to see what loaded
3. **Check for login page indicators:**
   - URL redirected to `/login`, `/signin`, `/auth`, `/sso`
   - Page title contains "log in", "sign in"
   - Page has login form fields
4. **If login detected:**
   - Tell the user: "I've opened the page but it requires login. Please log in using Chrome, then let me know when you're ready."
   - Wait for user confirmation
   - Take a new snapshot to verify authentication
   - Add debug parameter to the new URL if needed
5. **If no login needed:** Proceed with inspection

### Step 2: Check PostHog Global Object

Execute JavaScript to inspect the `posthog` object on the window:

```javascript
(() => {
  if (typeof posthog === 'undefined') {
    return { installed: false };
  }

  const ph = posthog;
  return {
    installed: true,
    version: ph.version || ph.LIB_VERSION || 'unknown',
    config: {
      token: ph.config?.token || ph.get_config?.('token') || 'not accessible',
      apiHost: ph.config?.api_host || ph.get_config?.('api_host') || 'not accessible',
      autocapture: ph.config?.autocapture ?? ph.get_config?.('autocapture') ?? 'not accessible',
      capturePageview: ph.config?.capture_pageview ?? ph.get_config?.('capture_pageview') ?? 'not accessible',
      capturePageleave: ph.config?.capture_pageleave ?? ph.get_config?.('capture_pageleave') ?? 'not accessible',
      sessionRecording: ph.config?.enable_recording_console_log !== undefined ||
                        ph.sessionRecording?.started ||
                        'check network',
      persistence: ph.config?.persistence || ph.get_config?.('persistence') || 'not accessible',
      debug: ph.config?.debug ?? ph.get_config?.('debug') ?? false
    },
    distinctId: ph.get_distinct_id?.() || 'not accessible',
    sessionId: ph.get_session_id?.() || 'not accessible',
    featureFlags: ph.getFeatureFlag ? Object.keys(ph.featureFlags?.flags || {}) : [],
    activeFeatureFlags: ph.getFeatureFlag ?
      Object.entries(ph.featureFlags?.flags || {})
        .filter(([_, v]) => v)
        .map(([k]) => k) : []
  };
})()
```

### Step 2b: Check for Bundled PostHog (Remote Config)

If `posthog` is not on `window`, check for bundled implementations that use `_POSTHOG_REMOTE_CONFIG`:

```javascript
(() => {
  const remoteConfig = window._POSTHOG_REMOTE_CONFIG;
  if (!remoteConfig) {
    return { found: false };
  }

  const tokens = Object.keys(remoteConfig);
  const configs = tokens.map(token => {
    const cfg = remoteConfig[token]?.config || {};
    return {
      token,
      hasFeatureFlags: cfg.hasFeatureFlags || false,
      autocapture: !cfg.autocapture_opt_out,
      sessionRecording: cfg.sessionRecording || false,
      heatmaps: cfg.heatmaps || false,
      surveys: cfg.surveys || false,
      capturePerformance: cfg.capturePerformance || {},
      defaultIdentifiedOnly: cfg.defaultIdentifiedOnly || false
    };
  });

  return {
    found: true,
    bundled: true,
    configs
  };
})()
```

### Step 2c: Check Console for PostHog Debug Messages

With `?__posthog_debug=true`, PostHog outputs detailed logs. Use `list_console_messages` and look for `[PostHog.js]` entries:

**Key messages to look for:**
- `[PostHog.js] Persistence loaded` - Shows persistence type (localStorage, sessionStorage, cookie)
- `[PostHog.js] [Surveys] Surveys loaded successfully` - Surveys module loaded
- `[PostHog.js] [Surveys] flags response received, isSurveysEnabled: X` - Whether surveys are enabled
- `[PostHog.js] [SessionRecording]` - Session recording status
- `[PostHog.js] [WebExperiments]` - Web experiments/feature flags
- `[PostHog.js] set_config` - Configuration changes

**Important distinction:**
- **Module loaded** = The JavaScript file loaded successfully
- **Feature enabled** = The feature is turned on in PostHog settings

A module can load but still be disabled. For example:
```
[PostHog.js] [Surveys] Surveys loaded successfully  <- Module loaded
[PostHog.js] [Surveys] flags response received, isSurveysEnabled: false  <- Feature disabled
```

### Step 3: Check for PostHog Script

Look for PostHog scripts in the page:

```javascript
(() => {
  const scripts = Array.from(document.querySelectorAll('script'));
  const posthogScripts = scripts.filter(s =>
    (s.src && (s.src.includes('posthog') || s.src.includes('ph.js'))) ||
    (s.textContent && (s.textContent.includes('posthog.init') || s.textContent.includes('!function(t,e)')))
  );

  return {
    found: posthogScripts.length > 0,
    scripts: posthogScripts.map(s => ({
      src: s.src || 'inline',
      async: s.async,
      defer: s.defer,
      type: s.type || 'text/javascript'
    }))
  };
})()
```

### Step 4: Check Network Requests

Fi