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 - high-level directory structure (products, services, common, tools)
• Products README - how to create and structure products
• Products architecture - DTOs, facades, isolated testing

Commands

• Environment:
  • This is a full dev environment, not a restricted patch-editing sandbox — it has node, pnpm, a package mirror, and apt, so tools and dependencies that aren't present yet can be installed, and tests, Storybook, and the app can actually be run. A missing node_modules, browser binary, or flox usually just means setup hasn't run yet (pnpm install, npx playwright install --with-deps chromium, or building the nested @posthog/quill workspace that global.scss imports), rather than that running things is impossible.
  • So the absence of a tool isn't evidence that a task can't be done — installing it is the first step. The honest signal that something genuinely can't run is an attempt that fails for a specific, nameable reason (no network access, apt unavailable, out of memory), which is worth reporting alongside whatever fallback you take.
  • This matters most for visual and UX work, where reading the code isn't the same as seeing the result. Rendering the affected surface (for example in Storybook via a headless browser) and comparing before and after is what actually confirms such a change, and is usually worth the setup cost.
  • 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
    • Cloud task VMs (prebaked dev-stack image): run bootstrap-dev-stack first (restores compose host aliases, starts dockerd), then uv sync, source .venv/bin/activate, hogli start -y -d, and hogli wait (the detached start returns while the stack is still booting; hogli wait blocks until every process is ready) — always detached: the sandbox has no TTY, and phrocs under a pseudo-TTY balloons in memory until OOM-killed
    • Cloud task VMs: on user-created runs the backend usually starts the stack itself. While it does, hogli start exits without starting anything. Poll /tmp/posthog-preview/status.json until state is ready or failed. On ready, run hogli wait; it reports not reachable until the backend reaches the phrocs step, so retry it rather than forcing a second start. On failed (the backend does not retry), start the stack yourself with hogli start -y -d
    • Cloud task VMs, frontend work: pnpm install --frozen-lockfile --prefer-offline links from the prebaked pnpm store, and Playwright Chromium is preinstalled; product/Storybook builds still run from source
    • Cloud task VMs, tests: scope every run to what you changed, with hogli test --changed or the test files that cover the touched code. Run a whole module, package, or repo-wide suite at most once, right before you push, and only for a cross-cutting change. CI runs the full matrix; repeating it in the sandbox costs minutes per run and floods the context with output. In a sandbox hogli test runs pytest with -q (set HOGLI_TEST_VERBOSE=1 to stream prints). pytest.ini already enables --reuse-db, and the prebaked dev-stack image seeds test_posthog; do not pass --create-db or override pytest addopts, because either discards the prewarmed schema. If pytest starts the full migration history, the VM image predates the database seed or the test database was replaced. Let that migration finish before retrying; interrupting it leaves a partial database that the next run must continue migrating.
• OpenAPI/types: hogli build:openapi (regenerate after changing serializers/viewsets)
• LSP: Pyright is configured against the flox venv. Prefer LSP (goToDefinition, findReferences, hover) over grep when navigating or refactoring Python code.
• 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.