{"owner":"PostHog","repo":"posthog","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md",".cursorrules"],"files":{"AGENTS.md":"# PostHog Development Guide\n\n## Codebase Structure\n\n- Key entry points: `posthog/api/__init__.py` (API URL routing skeleton; products register their own routes in `products//backend/routes.py` via `register_routes(routers)`), `posthog/settings/web.py` (Django settings, INSTALLED_APPS), `products/` (product apps)\n- [Monorepo layout](docs/internal/monorepo-layout.md) - high-level directory structure (products, services, common, tools)\n- [Products README](products/README.md) - how to create and structure products\n- [Products architecture](products/architecture.md) - DTOs, facades, isolated testing\n\n## Commands\n\n- Environment:\n - 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.\n - 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.\n - 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.\n - Use flox when available — prefer `flox activate -- bash -c \"\"` if commands fail\n - Never use `flox activate` in interactive sessions (it hangs if you try)\n- Tests:\n - Universal: `hogli test ` — auto-detects test type (Python, Jest, Playwright, Rust, Go)\n - Single test: `hogli test path/to/test.py::TestClass::test_method`\n - Watch mode: `hogli test path/to/test.py --watch`\n - Changed files only: `hogli test --changed`\n- Lint:\n - Python:\n - `ruff check . --fix` and `ruff format .`\n - 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.\n - TypeScript check: `pnpm --filter=@posthog/frontend typescript:check`\n- Build:\n - Frontend: `pnpm --filter=@posthog/frontend build`\n - Start dev: `./bin/start` or `hogli start` (interactive TUI). Detached mode: `hogli up -d` paired with `hogli wait` / `hogli down`\n - 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\n - 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\n- OpenAPI/types: `hogli build:openapi` (regenerate after changing serializers/viewsets)\n- New product: `bin/hogli product:bootstrap `\n- LSP: Pyright is configured against the flox venv. Prefer LSP (`goToDefinition`, `findReferences`, `hover`) over grep when navigating or refactoring Python code.\n- Dev experience feedback: `hogli devex:feedback \"\"` 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`).\n **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 \"`. Do not run it from cloud tasks or agent-server sandboxes; the command is a no-op there.\n\n## Commits and Pull Requests\n\n- Use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for all commit messages and PR titles.\n- When a change touches user-facing behavior, an API, a config/setting, or a documented workflow, update the matching doc under `docs/` **in the same PR** — treat a stale doc as part of the breakage, not a follow-up.\n\n### Commit types\n\n- `feat`: New feature or functionality (touches production code)\n- `fix`: Bug fix (touches production code)\n- `chore`: Non-production changes (docs, tests, config, CI, refactoring agents instructions, etc.)\n- Scope convention: use `aio` for AI observability changes (for example, `feat(aio): ...`)\n\n### Format\n\n```text\n(): \n```\n\nExamples:\n\n- `feat(insights): add retention graph export`\n- `fix(cohorts): handle empty cohort in query builder`\n- `chore(ci): update GitHub Actions workflow`\n- `chore: update AGENTS.md instructions`\n\n### PR descriptions\n\n**Required:** Before creating any PR, read `.github/pull_request_template.md` and use its exact section structure.\nDo not invent a different format.\n**Shape:** invoke `/writing-pr-descriptions` before writing the body. Lead with the effect a person sees rather than the code path behind it, make the body stand alone for a reader who opens no files, and let its size track the change. Then one fact per bullet, sentences under 25 words, active voice, no idioms. A description that got longer as bullets was not cut.\nAlways fill the `## 🤖 Agent context` section when creating PRs.\nNEVER share sensitive information in a PR description. Users may share sensitive data in an agent session, but those should never surface to a PR description, or comments.\n\n**Screenshots:** Upload frontend/visual changes with `hogli pr:upload-image ` and embed the printed markdown. The first run only warns and uploads nothing; re-run with `--yes` to confirm. Only PostHog employees can upload, but the public can permanently view these assets, so only upload the image if you're certain it doesn't contain customer data (including customer names), secrets, or sensitive internal info.\n\n### Rules\n\n- Scope is optional but encouraged when the change is specific to a feature area\n- Description should be lowercase and not end with a period\n- Keep the first line under 72 characters\n\n### Pushing to remote\n\nOnce a branch already has an open PR, push incremental changes and fixes to it without waiting for human guidance — keeping the PR current is part of the work.\nPushes still trigger CI, which burns runner credits, so batch related commits and push once the increment is ready rather than after every change.\n\nA push to this repository cannot be taken back.\nForks, clones, mirrors, and notification emails carry it within seconds, and a later fix commit does not retract what is already in the branch's history — recovering means abandoning the branch and respinning the PR.\nThat makes the first push of a branch the decision point, not a step you correct afterwards.\nSo if any part of the work drew on something from your session rather than from this repository — a customer conversation, a support ticket, a log, an internal thread — check what is actually in the diff before that first push.\nSee [Public open source repo guidance](#public-open-source-repo-guidance) for what has to clear the bar.\n\n#### Forcing the full CI matrix on a draft\n\nDraft PRs run a narrowed matrix.\nThe `run-ci-backend` and `run-ci-frontend` labels force the full one, but a label alone starts nothing: it takes effect on the next push, or when the PR is marked ready for review.\nAn empty commit is enough.\n\n```bash\ngit commit --allow-empty -m \"chore(ci): run the full matrix\" && git push\n```\n\nDo not add `labeled`/`unlabeled` back to a merge gate's `on.pull_request.types` to avoid that push.\nGitHub cannot filter a label trigger by name, so every unrelated label re-runs the full matrices against a commit CI has already covered.\nGuarding it inside the workflow is worse: skipping the gate job cascades to the `if: always()` aggregator, which counts a skipped dependency as success and posts a green required check with no tests behind it.\n\n#### Stacked PRs\n\nGitHub's native stacked PRs are enabled on this repo — use the `gh stack` CLI and the `/stacking-prs` skill instead of hand-managing branch chains.\nA stack lands bottom-first: merge the layer based on `master` the usual way (see \"Merging PRs\" below), then `gh stack sync --prune` and repeat.\nNever `gh stack merge` — it merges the whole chain straight through GitHub's API, so the bottom layer reaches `master` outside that path.\n\nRestacking force-pushes every branch, and each push triggers a full CI fan-out.\nNever restack while any branch in the stack is sitting in the merge queue — the force-push removes it from the queue.\nPushing a deep stack at once can exceed GitHub's per-repo dispatch cap (500 workflow runs / 10s).\nThe overflow fails as `startup_failure` and takes unrelated runs in the same window down too.\nDraft status doesn't help, since runs are dispatched before draft/skip logic applies.\n\n- Keep stacks shallow; merge the base before extending.\n- Restack only when you need to, rather than rebasing the whole stack on master repeatedly.\n- When a restack must push many branches, stagger them instead of force-pushing all at once.\n\n#### Pre-push checks — ci:preflight\n\nA pre-push hook runs `hogli ci:preflight --strict`, failing the push on deterministic CI breakage reachable from your diff (lint, lockfiles, migration conflicts). Never bypass it (`--no-verify`).\nIf it blocks the push, run `hogli ci:preflight --fix`, resolve the remaining `✗ fail` lines, act on the `→ advisory` ones (regenerate OpenAPI types, merge master in), and push again.\nIn environments without hooks (no `node_modules`), run `hogli ci:preflight --fix` yourself before pushing or reporting a task done. If the command reports it is disabled, that's intentional — proceed.\n\n### Merging PRs\n\nAll merges into `master` go through the Trunk merge queue.\nNever run `gh pr merge` or click the GitHub merge button — both are blocked by branch ruleset.\n\n- Enqueue: `gh pr comment --body \"/trunk merge\"`. Cancel: `gh pr comment --body \"/trunk cancel\"`.\n- After enqueueing, babysit the PR until it merges or fails — follow [`.agents/skills/merging-prs/SKILL.md`](./.agents/skills/merging-prs/SKILL.md) for the preflight, watch, and failure-handling loop.\n- Queue progress is the `Trunk Merge Queue (master)` check run on the PR's head commit. The PR's own checks don't reflect the queue's testing — it runs CI on a `trunk-merge/**` branch.\n- On failure the Trunk bot comments with links to the failing workflows; fix, push, and re-enqueue.\n- Never force-push a branch while it is in the queue — it removes the PR from the queue.\n\n### Public open source repo guidance\n\nThis repository is public, and everything you push is public with it: source, tests, fixtures and sample data, comments and docstrings, branch names, commit messages, PR titles, descriptions, and comments, and uploaded screenshots.\nAnything you were given as context that is not already in this repository — a customer conversation, a support ticket, a log, an internal thread — has to clear that bar before any of it reaches a file, a message, or a description.\n\n- Never mention internal-only systems, private incidents, customer data, Slack thread contents, unreleased roadmap details, or security-sensitive implementation details. Slack thread links and channel references are fine to include — they sit behind PostHog auth and are useful as origin context — but do not quote or paraphrase what was said in the thread.\n- **Derived is not synthetic.** Swapping out names, domains, and identifiers does not make real customer material publishable. The prose, the typos, the error IDs, and the order of events are still theirs, and still disclose what they told us. If you started from real material and edited it, it is derived, however much you changed.\n- **Sample data that has to read like the real thing gets invented, not transcribed.** List the properties a case must exercise, then write the case from that list with the real material closed. Use reserved domains (`example.com`), invented identifiers, and obviously fake tokens — customers paste credentials and cookies into support chats, and those must not survive the trip even in fragments.\n- **Do not claim a provenance you have not checked.** \"Written fresh\" in a commit message is a factual claim a reviewer will rely on. If you are unsure, compare your text against the source: any shared run of ~40 characters or more means derived, not fresh.\n- Use product-facing and code-facing context that a public OSS contributor could understand from this repository alone.\n- If context is sensitive, summarize it at a high level without naming internal tools, accounts, or people.\n- Avoid citing private operational scale or incident metrics (for example, exact affected team counts, internal row-volume anecdotes, or customer-specific performance numbers) unless that data is already public and linkable.\n\nExamples:\n\n- ✅ `fix(insights): handle missing series color in trend export`\n- ✅ A PR description that links to the originating Slack thread for context\n- ✅ A test fixture written from a list of the properties it has to exercise, with the real conversation closed\n- ❌ `fix: patch issue found in acme-co prod workspace after sales escalation` — references internal customer\n- ❌ `fix: will run fine on our 12 million rows there now` — leaks private operational scale\n- ❌ A PR description that quotes verbatim what a coworker said in a Slack thread\n- ❌ A test fixture adapted from a real support conversation with the names and domains replaced\n\n## CI / GitHub Actions\n\n- `.nvmrc` controls the Node.js version for all CI workflows (via `actions/setup-node`) — changing it affects every CI job that runs Node\n- Every job in `.github/workflows/` must declare `timeout-minutes` — prevents stuck runners from burning credits indefinitely\n- **CI workflow changes must stay backwards compatible with open PRs that haven't rebased.** A workflow edit hits every in-flight PR immediately (it runs against the PR merged with master), but companion changes — a new dependency, file, or config — only reach a branch once it rebases. If the workflow starts requiring something an unrebased branch lacks, every such PR fails before its tests run. Make the new behavior degrade gracefully when the prerequisite is absent, or gate it so unrebased branches are unaffected. This has broken CI repeatedly.\n\n## Security\n\nSee [.agents/security.md](.agents/security.md) for security guidelines — least privilege, secrets & service-to-service auth (don't add new `INTERNAL_API_SECRET` callers), SQL, HogQL, and semgrep.\n\n## Architecture guidelines\n\n- API views should declare request/response schemas — prefer `@validated_request` from `posthog.api.mixins` or `@extend_schema` from drf-spectacular. Plain `ViewSet` methods that validate manually need `@extend_schema(request=YourSerializer)` — without it, drf-spectacular can't discover the request body and generated code gets empty schemas\n- Django serializers are the source of truth for frontend API types — `hogli build:openapi` generates TypeScript via drf-spectacular + Orval. Generated files (`api.schemas.ts`, `api.ts`, `api.zod.ts`) live in `frontend/src/generated/core/` and `products/{product}/frontend/generated/` — don't edit them manually, change serializers and rerun. See [type system guide](docs/published/handbook/engineering/type-system.md) for the full pipeline\n- MCP tools are generated from the same OpenAPI spec — see [implementing MCP tools](docs/published/handbook/engineering/ai/implementing-mcp-tools.md) for the YAML config and codegen workflow\n- MCP UI apps (interactive visualizations for tool results) are defined in `products/*/mcp/tools.yaml` under `ui_apps` and auto-generated — see [services/mcp/CONTRIBUTING.md](services/mcp/CONTRIBUTING.md) or use the `implementing-mcp-ui-apps` skill\n- When touching a viewset or serializer, ensure schema annotations are present (`@extend_schema` or `@validated_request` on viewset methods, `help_text` on serializer fields) — these flow into generated frontend types and MCP tool schemas\n- New features should live in `products/` — read [products/README.md](products/README.md) for layout and setup. When _creating a new_ product, follow [products/architecture.md](products/architecture.md) (DTOs, facades, isolation). Code a single product owns — not just backend/frontend, but scripts, CLIs, services, packages, MCP tools, skills — belongs under `products//`; reserve top-level `tools/`/`services/`/`packages/`/`cli/` for cross-product things\n- **Every tenant-data model must have `team_id`** — either as a FK (`models.ForeignKey(\"posthog.Team\", ...)`) or a plain `BigIntegerField` (for multi-DB products). This is the primary tenant isolation boundary. Models without `team_id` must be org-scoped, user-scoped, or instance-global — never silently unscoped. New models should inherit from `TeamScopedRootMixin` (main DB) or `ProductTeamModel` (separate DB) so they start fail-closed — see `posthog/models/scoping/README.md`. CI enforces this via `posthog/models/scoping/baseline_unmigrated.txt`: any new team-scoped model not on a fail-closed manager fails the IDOR coverage check. In serializers, access the team via `self.context[\"get_team\"]()`. When querying a fail-closed model for one team outside request context (Temporal activities, Celery tasks, management commands), use `Model.objects.for_team(team_id)` — not `Model.all_teams.filter(team_id=...)` or `objects.unscoped().filter(...)`; reserve `all_teams`/`unscoped()` for genuinely cross-team access and Django framework internals. Caveat: `for_team(...).get_or_create(...)`/`.create(...)` still need `team_id` passed explicitly — queryset filters don't propagate into row creation\n- **Do not add domain-specific fields to the `Team` model.** Use a Team Extension model instead — see `posthog/models/team/README.md` for the pattern and helpers\n- **PostHog event capture in Celery tasks:** Do not use `posthoganalytics.capture()` in Celery tasks — events are silently lost. Use `ph_scoped_capture` from `posthog.ph_client` instead (see its docstring for why and usage).\n- **Django admin `ForeignKey` fields need explicit widget config.** When adding a `ForeignKey`/`OneToOneField` to a model that's exposed in Django admin (including via inlines attached to a _related_ admin), list the new field in `autocomplete_fields`, `raw_id_fields`, or `readonly_fields` on **every** admin class that renders the model — otherwise the default `