/posthog

World-class PostHog integration. Audit, fix, verify—every time.

What This Does

Examines your PostHog integration, identifies every gap, implements fixes, and verifies event tracking works end-to-end. No partial modes. Every run does the full cycle.

Branching

Assumes you start on master /main . Before making code changes:

git checkout -b fix/posthog-$(date +%Y%m%d)

Configuration-only changes (env vars, dashboard settings) don't require a branch. Code changes do.

Process

0. Environment Check

Verify PostHog is reachable and configured:

~/.claude/skills/posthog/scripts/detect-environment.sh

This checks:

• NEXT_PUBLIC_POSTHOG_KEY is set

• NEXT_PUBLIC_POSTHOG_HOST is set (or defaults correctly)

• PostHog API is reachable

• MCP connection is active

1. Audit

Spawn the auditor. Use the posthog-auditor subagent for deep parallel analysis. It examines:

• Configuration — Env vars on all deployments, cross-platform parity

• SDK Setup — Initialization, provider placement, privacy settings

• Event Quality — Events defined, consistent naming, not too noisy

• Privacy Compliance — PII masking, consent handling, GDPR readiness

• Feature Flags — Active flags, stale flags, evaluation patterns

• Integration Health — Events flowing, no ingestion warnings

Use MCP tools for live data:

mcp__posthog__event-definitions-list — See what events are tracked mcp__posthog__feature-flag-get-all — Audit active feature flags mcp__posthog__list-errors — Check for error tracking issues mcp__posthog__logs-query — Search for SDK/ingestion errors

Research first. Before assuming current patterns are correct, check PostHog docs:

mcp__posthog__docs-search query="[topic]"

2. Plan

From audit findings, build a complete remediation plan:

Finding Type Action

Missing env vars Fix directly with Vercel/Convex CLI

SDK misconfiguration Delegate to Codex with clear specs

Missing events Define event schema, implement tracking

Privacy gaps Apply references/privacy-checklist.md

Feature flag cleanup Archive stale flags via MCP

Prioritize:

• Critical — Events not sending, SDK not initialized

• High — Privacy issues, PII leakage, missing masking

• Medium — Suboptimal patterns, missing events

• Low — Cleanup, organization, dashboards

3. Execute

Fix everything. Don't stop at a report.

Configuration fixes (do directly):

Missing env var on Vercel

printf '%s' 'phc_xxx' | vercel env add NEXT_PUBLIC_POSTHOG_KEY production

Missing env var on Convex (for server-side tracking)

npx convex env set --prod POSTHOG_API_KEY "phc_xxx"

SDK setup fixes (delegate to Codex):

codex exec --full-auto "Fix PostHog initialization.
File: lib/analytics/posthog.ts.
Problem: [what's wrong].
Solution: [what it should do].
Reference: ~/.claude/skills/posthog/references/sdk-patterns.md.
Verify: pnpm typecheck && pnpm test"
--output-last-message /tmp/codex-fix.md 2>/dev/null

Event schema updates: Use mcp__posthog__action-create to define composite events.

Feature flag cleanup: Use mcp__posthog__delete-feature-flag to remove stale flags.

4. Verify

Prove it works. Not "looks right"—actually works.

Configuration verification:

Check env vars exist

vercel env ls --environment=production | grep POSTHOG npx convex env list --prod | grep POSTHOG

Event flow verification using MCP:

Check recent events are flowing

mcp__posthog__query-run with TrendsQuery for last 24h

Check for ingestion warnings

mcp__posthog__list-errors

Verify event definitions exist

mcp__posthog__event-definitions-list

SDK initialization verification:

• Open browser DevTools → Network tab

• Filter for posthog or i.posthog.com

• Trigger an action → verify event sent

• Check PostHog Live Events → verify event received

Privacy verification:

• Session Replay shows masked inputs (*** )

• Person profiles show only user ID, not email/name

• Autocapture text is masked

If any verification fails, go back and fix it.

Common Issues & Fixes

Events Not Sending

Symptoms: No events in PostHog, network requests failing

Debug steps:

• Check if PostHog initialized: posthog.__loaded in console

• Check network tab for blocked requests (ad blockers)

• Enable debug mode: posthog.debug() in console

• Test with webhook.site to isolate SDK vs network issues

Fixes:

• Set up reverse proxy (/ingest → PostHog) to bypass ad blockers

• Ensure initPostHog() called in provider

• Check NEXT_PUBLIC_POSTHOG_KEY is actually public (has NEXT_PUBLIC_ prefix)

Bot Detection Blocking Dev Events

Symptoms: Events work in production but not local dev

Cause: Chrome launched from debugger triggers bot detection

Fix:

posthog.init(key, { opt_out_capturing_by_default: false, // For development only: bootstrap: { isIdentifiedAnonymous: true }, });

Identify Called Before Init

Symptoms: User not linked to events, anonymous users everywhere

Fix:

// WRONG posthog.identify(userId); // Called before init completes

// RIGHT posthog.init(key, { loaded: (ph) => { if (userId) ph.identify(userId); }, });

Missing Reverse Proxy

Symptoms: Events blocked by ad blockers in production

Fix (Next.js):

// next.config.js module.exports = { async rewrites() { return [ { source: '/ingest/:path*', destination: 'https://us.i.posthog.com/:path*', }, ]; }, };

Then update init:

posthog.init(key, { api_host: '/ingest', });

MCP Tool Reference

Tool Purpose

mcp__posthog__event-definitions-list

List all tracked events

mcp__posthog__query-run

Run trends/funnels queries

mcp__posthog__feature-flag-get-all

List feature flags

mcp__posthog__create-feature-flag

Create new flag

mcp__posthog__list-errors

Check error tracking

mcp__posthog__logs-query

Search logs for issues

mcp__posthog__docs-search

Search PostHog docs

mcp__posthog__entity-search

Find insights/dashboards/flags

mcp__posthog__projects-get

List available projects

mcp__posthog__switch-project

Change active project

Default Stack

Assumes Next.js + TypeScript + Convex + Vercel + Clerk. Adapts gracefully to other stacks.

What You Get

When complete:

• Working event tracking (events visible in PostHog Live Events)

• Proper SDK initialization with privacy settings

• Reverse proxy configured for ad blocker bypass

• User identification linked to auth (Clerk/etc)

• Feature flags ready to use

• Standard events defined and tracking

• All configuration in place (dev and prod)

• Deep verification passing

Sources

• PostHog MCP Documentation

• PostHog Troubleshooting Guide

• Official PostHog MCP Server