PostHog AI plugin

Official PostHog plugin for AI clients. Access PostHog products directly from your AI coding tool.

Installation

Claude Code

1. Install the plugin:

   claude plugin install posthog
   

   Or install from this repo as a marketplace:

   claude plugin marketplace add PostHog/ai-plugin
   claude plugin install posthog@posthog
   

2. Authenticate via OAuth:

   # Just enter Claude Code anywhere
   claude
   # Then, use the /mcp command within Claude, select plugin:posthog:posthog, and press Enter
   /mcp
   

   Then follow the browser prompts to log into PostHog.

3. (Optional) Send Claude Code sessions to PostHog LLM Analytics.

   Add to ~/.claude/settings.json (global) or .claude/settings.local.json (per-project):

   {
     "env": {
       "POSTHOG_LLMA_CC_ENABLED": "true",
       "POSTHOG_API_KEY": "phc_...",
       "POSTHOG_HOST": "https://eu.i.posthog.com"
     }
   }
   

   Both POSTHOG_LLMA_CC_ENABLED=true and POSTHOG_API_KEY are required. Sessions are sent when Claude Code exits. Set POSTHOG_LLMA_PRIVACY_MODE=true to redact prompt/output content. Add custom properties to all events with POSTHOG_LLMA_CUSTOM_PROPERTIES (JSON string, e.g. '{"ai_product": "my-app"}'). Set POSTHOG_AI_PURPOSE to declare what the session is doing relative to the repo — documented values are authoring and review, emitted as $ai_purpose. Useful when a harness wraps an agent it can't modify (e.g. a CI job running Claude Code as a reviewer); left unset the property is omitted.

Session capture without the rest of the plugin

To send Claude Code sessions to PostHog LLM analytics without the skills, the slash commands, or the MCP server, install the capture plugin on its own:

claude plugin marketplace add PostHog/ai-plugin
claude plugin install posthog-telemetry@posthog

It registers one SessionEnd hook and nothing else, so it adds nothing to the context of a session. It needs only the Python standard library, and it reads the same environment variables as step 3 above.

Install it instead of the posthog plugin, not alongside it. Both register the same hook, so running both parses and uploads every session twice. PostHog dedupes the events themselves, because their UUIDs are derived from the session, but the two hooks race on the status file.

Cursor

Install from the Cursor Marketplace or add manually in Cursor Settings > Plugins.

Codex

1. Add the marketplace:

   codex plugin marketplace add PostHog/ai-plugin
   

2. Install the plugin from inside Codex:

   codex
   # Then run /plugins, select PostHog, and install
   /plugins
   

Gemini CLI

gemini extensions install https://github.com/PostHog/ai-plugin

Grok

1. Install the plugin:

   grok plugin install PostHog/ai-plugin --trust
   

2. Authenticate via OAuth:

   On first use of a PostHog tool, Grok prompts you to authorize in your browser. Log into PostHog to connect.

Claude Cowork

1. Add the marketplace: open Settings > Plugins, click Add > Add marketplace, enter PostHog/ai-plugin, and click Sync.

2. Install the plugin: click Browse, select PostHog, and install. The plugin stays in sync with this repo automatically.