haacked/dotfiles/posthog-context

PostHog Context

posthog-cli

Use posthog-cli api for all PostHog-related data queries and operations. Prefer it over direct MCP tool calls whenever the CLI is available.

Before your first PostHog command in a session, run posthog-cli api --agent-help and load its full output into your context. It prints the complete agent guide — command reference, schema drill-down rules, data discovery workflow, and the tool index — for interacting with PostHog APIs. Treat that output as instructions to follow, not just documentation.

Before starting a PostHog task, run posthog-cli api skill list and check for a skill matching the task. If one matches, install it with posthog-cli api skill install <skill-id> (add --force to refresh an already-installed skill), then read .agents/skills/<skill-id>/SKILL.md and follow it. Skills contain task-specific workflows that individual tools do not.

posthog/posthog

• Read README.md and docs/FLOX_MULTI_INSTANCE_WORKFLOW.md.
• Prompt whether to create a new git worktree using the phw command.
• On task completion, run: mypy --version && mypy -p posthog | mypy-baseline filter || (echo "run 'pnpm run mypy-baseline-sync' to update the baseline" && exit 1)

HogQL Rewrites

Two mistakes recur when code moves a HogQL expression to a new place:

• A copied filter can name things the new scope lacks. An outer query's WHERE can name joined tables, aliases, and the joins HogQL adds while it resolves lazy joins. None of those exist in a subquery built from the outer FROM table. Copy the filter only when every field in it resolves on that table.
• Two tables read the same property differently. When events reads a property from a non-nullable mat_ column, HogQL wraps the read in nullIf(nullIf(col, ''), 'null'), so the JSON strings "" and "null" read as NULL. flag_evaluations has no materialized columns and extracts from the raw JSON, where those strings read back as '' and 'null'. So properties.$browser = '' and properties.$browser IS NULL can select different rows on each table. Nullable mat_ columns and the new events schema handle these values differently again. Code that relies on one predicate selecting the same rows on both tables needs a test that runs the predicate on both, over those values, with the property materialized and not.

Database Access

• `posthog-db` MCP is the local dev database. Use it for testing locally, inspecting schema, exploring relationships, and developing queries.
• Never use `posthog-db` to investigate production issues. It does not have prod data.
• For prod investigations, use the `metabase-prod-query` skill. It wraps hogli metabase:* with explicit per-query approval (required even in auto mode), region handling, and --save discipline. Never invoke the underlying hogli metabase:* commands directly. Go through the skill.

Production Architecture

PostHog runs behind load balancers and proxies. Always consider this for IP addresses, rate limiting, authentication, and geolocation.

• AWS NLB → Contour/Envoy Ingress → Application Pods
• Contour: num-trusted-hops: 1; NLB: preserve_client_ip.enabled=true

Never use socket IP addresses — they will be the load balancer's IP. Use X-Forwarded-For (primary), X-Real-IP (fallback), Forwarded (RFC 7239), socket IP (local dev only).

Infrastructure repos:

• ~/dev/posthog/posthog-cloud-infra — Terraform/AWS (NLB, VPC)
• ~/dev/posthog/charts — Helm/K8s (Contour config, ingress rules, header policies)

PostHog SDK Repositories

Client-side

Server-side