PostHog

Debug, support, and build PostHog MCP Analytics — product analytics for MCP servers (the `@posthog/mcp` and `posthog.mcp` SDKs plus the mcp_analytics product). Use when MCP analytics data looks wrong or missing ("events aren't showing", "intent clusters are…

Required reading before writing any HogQL/SQL or calling execute-sql against PostHog. Use whenever the user wants to search, find, or do complex aggregations PostHog entities (insights, dashboards, cohorts, feature flags, experiments, surveys, hog flows, data…

Synthesizes recent organizational activity into a durable context wiki. Use when running a nightly or incremental context-layer dream, or when updating sourced organizational context from completed work.

Guide for adding a product setup empty state — the skippable first-run screen a product scene shows until real data arrives, built on the shared ProductEmptyState component. Use when adding an empty state or first-run/setup screen to a product scene,…

Populates and maintains a project's data catalog (semantic layer): canonical metrics, trust marks (certifications) on warehouse tables/views, and reviewed table relationships. Use when asked to set up / seed / bootstrap the data catalog or semantic layer, to…

Debugs failing GitHub Actions CI runs for PostHog PRs, commits, and branches, and answers broad CI-health questions ("is CI red?", "is master green today?", "what's broken right now?"). Use when the user asks why CI is red, asks for the current CI or master…

Operating procedure for the conflict-autoresolver agent: sweep open PostHog/posthog PRs that conflict with master, resolve the trivial conflicts (generated artifacts deterministically, source conflicts with judgment), land one merge commit on the PR head, and…

Debug, support, and build PostHog Surveys across the backend and all five SDKs (web/posthog-js, iOS, Android, Flutter, React Native). Use whenever a Surveys support ticket is pasted ("survey not showing", "fewer responses than expected", "responses…

Use before emailing a PostHog customer, replying to one, or joining a call, and for any request to research a PostHog account. Fires on "/posthog-customer-deep-dive" and on natural language like "deep dive on X", "look up this customer", "help me reply to Y",…

Audit a PostHog A/B experiment for a customer — verify config, exposure, attribution, and metrics. Trigger phrases include "audit [customer]'s experiment", "audit the [name] experiment", "check experiment setup for [customer]", "validate this A/B test", or…

Assesses what a page's heatmap is telling you and recommends concrete changes. Pulls click / rageclick / scroll-depth data for a URL, names the hot elements by cross-referencing autocapture events on the same page, and can create a saved heatmap the user…

How to author, edit, and adapt PostHog Signals scouts — the scheduled agents that scan a project and emit findings into the Signals inbox. Use when a user wants to customize a canonical scout for their own setup (narrow its scope, retune its thresholds, add…

Configures the analytics side of a PostHog experiment — exposure criteria (default `$feature_flag_called` vs custom exposure events), primary and secondary metrics, the supported metric types (count, sum, ratio with `math` and `math_property`, retention with…

Wire a PostHog endpoint into a client app or SDK. Covers fetching the OpenAPI spec, generating a typed client with openapi-generator or @hey-api/openapi-ts, sending the right auth header, shaping the variables payload (HogQL code_name vs insight breakdown…

Guides agents through creating and safely sizing a Replay Vision scanner: choosing the scanner type (monitor/classifier/scorer/summarizer), shaping the RecordingsQuery that selects sessions, and — crucially — estimating observation volume and checking the…

Debug the signals pipeline locally end-to-end. Covers emitting test signals from fixtures, monitoring Temporal workflows via the REST API, reading sandbox agent logs from object storage, inspecting Docker sandbox containers, and diagnosing common failures…

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.

Add PostHog product analytics events to track user behavior. Use after implementing new features or reviewing PRs to ensure meaningful user actions are captured. Also handles initial PostHog SDK setup if not yet installed.

Add PostHog error tracking to capture and monitor exceptions. Use after implementing features or reviewing PRs to ensure errors are tracked with stack traces and source maps. Also handles initial PostHog SDK setup if not yet installed.

Add PostHog feature flags to gate new functionality. Use after implementing features or reviewing PRs to ensure safe rollouts with feature flag controls. Also handles initial PostHog SDK setup if not yet installed.

Add PostHog LLM analytics to trace AI model usage. Use after implementing LLM features or reviewing PRs to ensure all generations are captured with token counts, latency, and costs. Also handles initial PostHog SDK setup if not yet installed.

Add PostHog log capture to track application logs. Use after implementing features or reviewing PRs to ensure meaningful log events are captured with structured properties. Also handles initial OTLP exporter setup if not yet configured.

How to author, edit, and adapt PostHog Signals scouts — the scheduled agents that scan a project and write reports into the Signals inbox. Use when a user wants to customize a canonical scout for their own setup (narrow its scope, retune its thresholds, add…

Build, edit, test, enable, and monitor PostHog workflows over MCP. Author the action/edge graph so it runs and opens cleanly in the visual editor, then change drafts surgically with patch operations. Use when asked to build, set up, automate, change, fix, or…

Rank a PostHog user's first-touch acquisition channels by retained Stripe revenue and CAC payback, using ad spend from Google/Meta, saved as a reusable PostHog insight. Use this whenever someone asks which marketing channels or sources bring customers who…

Measure whether a specific feature rollout moved revenue: split users on feature-flag or experiment exposure and compare downstream Stripe revenue and retention between the exposed cohort and control, saved as a reusable PostHog insight. Use this whenever…

Rank a PostHog user's product features by the revenue of the customers who use them (joins Stripe MRR/invoices to feature-usage events) and save it as a reusable PostHog insight. Use this whenever someone asks which features their highest-revenue or best…

Score CRM leads (HubSpot/Salesforce) by recent product usage and surface the warmest leads sales hasn't contacted yet, a product-qualified-lead list saved as a reusable PostHog insight. Use this whenever someone wants product-qualified leads (PQLs), a lead…

Rank the onboarding and activation steps that best predict a trial becomes a paying customer: build the onboarding funnel, flag who reached a first Stripe payment, and compare payers versus non-payers, saved as a reusable PostHog insight. Use this whenever…

Find the shared product-usage warning pattern before churn: pull cancellation dates from Stripe or Chargebee and examine the roughly 30 days of activity before each one, saved as a reusable PostHog insight. Use this whenever someone wants an early-warning…

Test whether support tickets predict churn with a three-way join of PostHog engagement, Zendesk/Intercom tickets and topics, and Stripe churn, ranking the support issues that precede the most lost revenue, saved as a reusable PostHog insight. Use this…

Find expansion-ready accounts by comparing each account's real product usage against its current Stripe plan limits and flagging accounts consistently near or over their limits while still on a lower plan, saved as a reusable PostHog insight. Use this…

Sync this fork of @anthropic-ai/claude-agent-acp (packages/agent/src/adapters/claude) with a newer upstream release: bump the claude-agent-sdk / @agentclientprotocol/sdk, port upstream bug fixes and new SDK message handling, preserve the fork's divergences,…

Merge a PR into main through the Trunk merge queue and babysit it until it lands. Enqueue with a "/trunk merge" comment, then poll the "Trunk Merge Queue" check run and the PR state until it is MERGED or FAILED, reporting the Trunk bot's failure reason if the…

Write Storybook stories for PostHog UI components. Covers the provider stack stories run inside, the key gotcha that tRPC/useHostTRPC queries never resolve in Storybook (so data-fetching components render empty), and the pure-presentational split that makes a…

Drive the real running PostHog Electron app (live tRPC, workspace-server, real data) over CDP with agent-browser. Connect to the running app on port 9222, snapshot the accessibility tree to verify changes, click/type/navigate, and screenshot the actual…

Edit the @posthog/quill design system locally and consume the change in this repo (posthog-code) before it is published to npm. Use when changing quill components/primitives/tokens, when a quill change must be tested inside the Code app, or when the user…

Add, replace, and optimize the looping demo videos in the onboarding "welcome" bento grid (packages/ui/src/features/onboarding). Covers the ffmpeg compression workflow (the scripts/optimize-onboarding-videos.mjs wrapper), the faststart + right-size best…

How PostHog "canvas" dashboards work end-to-end — the two rendering tiers (json-render vs freeform React-in-iframe), the agent system prompts that steer each, and the RIGHT way to fetch PostHog data (typed query nodes through ph.query, not hand-rolled HogQL).…

Run, drive, and explore the PostHog wizard headlessly against an app — boot it on the app and decide each screen yourself over the wizard-ci MCP tools (open_app / read_state / perform_action / run_agent), snapshotting the TUI to see what happened. Use to test…

Design philosophy and architectural principles for the PostHog wizard. Read this before making any structural change — adding features, extending the runner, modifying the TUI, or introducing new abstractions. Covers why the architecture is shaped this way,…

Build terminal user interfaces (TUIs) using Ink (React for CLIs) and @inkjs/ui with a reactive, session-driven wizard pattern. Use when creating interactive CLI installation wizards, setup flows, or multi-step terminal applications in Node.js/TypeScript.…

Create a new skill-based program for the PostHog wizard. Use when adding a program type (like revenue analytics, audit, error tracking) that installs a context-mill skill and runs an agent against it. Covers the createSkillProgram factory for the common case,…

Add a new framework integration to the PostHog wizard. Use when adding support for a new language or framework (e.g. Ruby on Rails, Go, Angular). Covers creating the agent config, detection logic, registry entry, and enum/label additions.

Build, deploy, and port-forward the multi-tenant control plane on local Kubernetes. Use when you need to test duckgres in multi-tenant mode with per-team worker pools.

Promote the duckgres control-plane image to prod from the CLI — resolve the built image ref from the charts state file, fire the charts Promote-to-Prod workflow, and watch it through the approval gate. Use when the user says "promote duckgres", "ship the CP…

Tear down the multi-tenant K8s stack, kill port-forwards, and clean up worker pods. Use when done testing multi-tenant mode.

Start duckgres with DuckLake (S3-backed storage with PostgreSQL metadata) for local testing. Use when testing duckgres against DuckLake or reproducing Fivetran sync issues.

Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.

Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.

Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.

Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.

Author a new PostHog browser extension, or port a posthog-js v1 extension, against the @posthog/browser-common Client/Extension contract. Use when adding or porting an extension (autocapture, pageview, surveys, replay, exceptions, web-vitals, campaign-params,…

Cross-reference a posthog-js or rrweb change against past incident patterns before writing, reviewing, or merging it. Use when a diff touches session recording, the recorder or any lazy-loaded extension bundle (entrypoints/), session rotation or idle…

Quickly compare the posthog-js array.js bundle size in the current working tree against a git baseline using the repository's esbuild proxy. Use when asked about array.js size, bundle-size percentage changes, whether browser SDK changes increased the bundle,…

Add support for a new PostHog resource type (feature flag, cohort, action, survey, annotation, alert, …) to posthog-definitions. Walks through the eight files that must change, the tag-based identity convention, the load/diff/execute pipeline wiring, and the…

Add support for a PostHog resource that exists exactly once per project (project settings, organization billing config, plugin enablement flags, …). Singletons do not fit the tag-based identity model — they have no collection to filter, no key to…

Code review guide for choosing between Result types and thrown exceptions. Recoverable, expected failures should be returned as Result values; only unrecoverable bugs and broken invariants should throw. Use when reviewing code that introduces a new error…

Rigorously verify suspected bugs before filing issues. Determines provenance (upstream vs DuckHog), severity, and whether a bug is real. Use whenever a test failure, unexpected behavior, or suspected regression needs to be classified before opening an issue…

SQL injection and input validation audit for the DuckHog SQL proxy pipeline. Systematically tests all paths where user-supplied identifiers or values flow into rewritten SQL strings. Use as a routine security check after modifying any rewriter, serializer, or…

Enforce GitHub issue preflight before starting implementation work. Use when beginning a new task to match it against open issues, claim an unstarted match, create a new issue when none matches, and abort only when matching is ambiguous or in-progress work…

Summarize what needs attention in one GitHub repository: open pull requests, the review queue, failing checks, stale work, and what merged recently. Use at the start of a work session to decide what to pick up next.

Create a GitHub pull request for the current branch using the gh CLI. Use when a user wants to open a PR and have the title, body, template, and assignee handled for them, following the repo's conventions and keeping public PRs free of PII.

Investigate a sudden change in web traffic. Use when a user reports a spike or drop in pageviews, sessions, or conversion and wants to find the likely cause (channel, device, referrer, or release) before escalating.