> PostHog: what your AI agent should know — from The Handover, the-handover.org/services/posthog
> © Captivated Ltd — free to use in your own work, not to redistribute as a collection. the-handover.org/licence

# PostHog

What we tell an AI agent working on a project that uses PostHog: 2 rules, 0 learned the hard way.

Build a full rootnote set for a PostHog project: https://the-handover.org/build?areas=working-agreement,analytics&analytics=posthog

The vendor's own file for agents (what PostHog is, where its documentation lives): https://posthog.com/llms.txt. This page covers where it catches agents out.

### PostHog: its npm SDKs were briefly malicious in November 2025; the script snippet was not

> Reported by Oliver Browne, PostHog, "Post-mortem of Shai-Hulud attack on November 24th, 2025" — posthog.com/blog/nov-24-shai-hulud-attack-post-mortem · distilled by Leon Mallett (captivated.online) with Claude Code · reviewed 2026-10-24

PostHog's own post-mortem: at 04:11 UTC on 24 November 2025, malicious versions
of its JavaScript SDKs were published to npm, including posthog-js 1.297.3 and
posthog-node 4.18.1, 5.11.3 and 5.13.3. A preinstall script searched the machine
running the install for credentials, published them to a public GitHub
repository, and used any npm tokens it found to spread to other packages. PostHog
removed the versions by 09:30 UTC. Sites using the script-tag snippet were not
affected, because the worm ran during dependency installation. The attacker got
PostHog's publishing token through a GitHub Actions workflow that ran code from
pull requests submitted by outside contributors.

For an agent, the exposure is the install. "Add PostHog" usually means installing
the latest SDK, and an install that ran during those five hours would have run
the payload with the agent's environment.

- **Pin PostHog's SDKs to a known version** and update deliberately, not by
  default.
- **Set a minimum release age.** PostHog's own advice is to use the
  `minimumReleaseAge` setting in pnpm or yarn, at something like three days, so
  a malicious release is usually withdrawn before you can install it.
- **Do not let install scripts run by default.** PostHog moved to pnpm 10 to
  disable them.
- **Where the browser snippet is enough, it avoids the install entirely.**

### PostHog: decide what it captures, and whether consent comes first

> General guidance · Leon Mallett (captivated.online) with Claude Code · reviewed 2026-10-18

- **Decide what is captured before it ships.** Autocapture records far more than
  page views; mask inputs, and never put personal data in event properties.
- **If it stores anything on the device, consent comes first** under UK and EU
  rules. Either configure it not to, or load it only after consent.
- **Name its origin in both `script-src` and `connect-src`.** With only the first,
  the script loads and every event is blocked — a dashboard reading zero looks
  exactly like no traffic.
- **Update the privacy notice to match what it actually does.**

Also applies to every analytics choice, so not repeated here: A third-party script tag in Astro needs is:inline or the build rewrites it.