posthog-foss: Instructions file for Claude Code

PostHog Development Guide

Codebase Structure

• Key entry points: posthog/api/__init__.py (API URL routing skeleton; products register their own routes in products/<name>/backend/routes.py via register_routes(routers)), posthog/settings/web.py (Django settings, INSTALLED_APPS), products/ (product apps)
• Monorepo layout — read when you need to place a new directory, or to work out which tree owns something (products, services, common, tools)
• Products README — read before creating a product or changing one's structure; covers the isolation rules product:lint enforces
• Products architecture — read when designing a product's DTOs, facade, or contract with the rest of the repo
• A directory may carry its own AGENTS.md that wins locally (posthog/temporal/, rust/, frontend/src/, most of products/). Check for one before working in an unfamiliar tree.

Commands

• Environment:
  • This is a full dev environment with node, pnpm, a package mirror and apt. A missing node_modules, browser binary or flox means setup has not run yet (pnpm install, npx playwright install --with-deps chromium), not that running things is impossible — install it and continue. Report "can't run" only for a specific, nameable failure (no network, no apt, out of memory), alongside whatever fallback you took.
  • Visual and UX work is not confirmed by reading the code. Render the affected surface (the running app, or Storybook via a headless browser) and compare before and after. Worth the setup cost. A story written only for this check is scratch: keep it out of the commit.
  • Use flox when available — prefer flox activate -- bash -c "<command>" if commands fail
    • Never use flox activate in interactive sessions (it hangs if you try)
• Tests:
  • Universal: hogli test <file_or_directory> — auto-detects test type (Python, Jest, Playwright, Rust, Go)
  • Single test: hogli test path/to/test.py::TestClass::test_method
  • Watch mode: hogli test path/to/test.py --watch
  • Changed files only: hogli test --changed
• Lint:
  • Python:
    • ruff check . --fix and ruff format .
  • Frontend: pnpm --filter=@posthog/frontend fix (safe Oxlint fixes + Oxfmt; suggestion fixes are not applied). format runs Oxfmt only; lint and format:check only verify.
  • TypeScript check: pnpm --filter=@posthog/frontend typescript:check
• Build:
  • Frontend: pnpm --filter=@posthog/frontend build
  • Start dev: ./bin/start or hogli start (interactive TUI). Detached mode: hogli up -d paired with hogli wait / hogli down
    • In a PostHog Tasks cloud run (POSTHOG_TASK_RUN_ID set), the boot sequence, prewarmed test database and scoped-test rules differ — read Cloud task sandbox before starting the stack or running tests there
• OpenAPI/types: hogli build:openapi (regenerate after changing serializers/viewsets)
• Dev experience feedback: hogli devex:feedback "<message>" sends feedback about repo tooling — hogli, the dev stack, tests, CI, migrations, this setup — straight to the devex team as a hogli_feedback event (add -c bug|idea|praise|question). Local agents must use it too: when a hogli command or local dev workflow is broken, slow, or confusing, run it — e.g. hogli devex:feedback -c bug "migrations:run failed with <error>". Do not run it from cloud tasks or agent-server sandboxes; the command is a no-op there.