Menu
Set up Python test environment in Claude Code for web where flox is unavailable. Use when you need to run backend tests and `uv sync` fails due to Python version mismatch.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Required reading before writing any HogQL/SQL or calling execute-sql against PostHog. Use whenever the user wants to search, find, or do complex aggregations PostHog entities (insights, dashboards, cohorts, feature flags, experiments, surveys, hog flows, data warehouse, persons, etc.) and query analytics data (trends, funnels, retention, lifecycle, paths, stickiness, web analytics, error tracking, logs, sessions, LLM traces). Also the first stop for a governed business number (MRR, activation, revenue): check the semantic layer (canonical metrics in system.information_schema.metrics) for an approved definition before deriving from raw events. Covers HogQL syntax differences from ClickHouse SQL, system table schemas (system.*), available functions, query examples, and the schema-discovery workflow.
Debug, support, and build PostHog MCP Analytics — product analytics for MCP servers (the `@posthog/mcp` and `posthog.mcp` SDKs plus the mcp_analytics product). Use when MCP analytics data looks wrong or missing ("events aren't showing", "intent clusters are empty", "sessions are missing", "per-tool numbers look wrong"), when writing queries over `$mcp_*` events by hand, or when doing feature work on the SDKs, the dashboard and its query runners, the self-instrumented MCP server, the `wizard mcp-analytics` install command, or the in-app onboarding. Covers the repo map, the `$mcp_*` vocabulary and where each property comes from, the rules that silently corrupt metrics when ignored, the end-to-end pipeline and where each stage breaks, and which repo to change. For reading the data rather than fixing it, prefer the `exploring-mcp-*` and `improving-mcp-tools` skills.
Edit the @posthog/quill design system locally and consume the change in products/desktop before it is published to npm. Use when changing quill components/primitives/tokens, when a quill change must be tested inside the Code app, or when the user mentions quill, the design system, the .local-quill tarball, or the @posthog/quill pnpm override.
How to add a new ingestion warning type to the event ingestion pipeline. Use when emitting a new warning from nodejs ingestion code (emitIngestionWarning, captureIngestionWarning, pipeline `warnings` arrays, `drop()` with warnings), when adding a warning type, category, or severity, or when a typecheck error says a string is not assignable to IngestionWarningType. Covers the INGESTION_WARNING_TYPES registry (the single source of truth for type, category, and severity), the details-key conventions that ClickHouse v2 materializes into columns, debouncing, and the downstream surfaces to keep in sync (v1 UI map, resolving-ingestion-warnings skill, docs, v2 API).
Diagnoses and resolves PostHog ingestion warnings — problems recorded while ingesting events (dropped events, rejected person merges, oversized payloads, invalid data). Use when a user asks why events are missing, dropped, or undercounted, why identify/alias calls don't work or accounts stay duplicated, why person or group properties aren't updating or profiles look inflated, why recordings have gaps, heatmaps are empty, LLM token counts are missing, why cookieless events vanish, or whenever the `ingestion_warning` health check fires. Explains severity triage (error = dropped, warning = modified, info = intentional) and routes all warning types — size limits and enrichment, merges and distinct IDs, `$process_person_profile`, timestamps, cookieless, heatmaps, transformations, session replay — to per-issue reference files with code-level causes and per-SDK fixes.
Create or edit a PostHog canvas — a sandboxed browser application (data board, document, form, small tool, graphics experiment) stored in PostHog and rendered by the desktop/web app. Use when a task asks to build, generate, update, or fix a canvas, or when a canvas id is given as the publish target. Covers resolving or creating the target canvas, choosing an implementation approach (React + Quill vs plain HTML/browser APIs), the read → edit → validate → publish → build loop, and which companion canvas skills to load for the details.
| name | setup-web-tests |
| description | Set up Python test environment in Claude Code for web where flox is unavailable. Use when you need to run backend tests and `uv sync` fails due to Python version mismatch. |
This document describes how to set up and run Python tests in a Claude Code for web environment, where flox is not available.
If you get stuck following these instructions, please bail out to the user and seek their guidance. Please suggest that they update this guide.
The project requires a specific Python version pinned in pyproject.toml (check requires-python), but:
uv python install <version> may fail if the version isn't yet indexed by uvuv sync enforces the exact version constraint and will fail with the wrong Python versionDownload the exact version from python-build-standalone GitHub releases. The script below auto-detects the required version from pyproject.toml:
# Auto-detect the required version from pyproject.toml
REQUIRED_VERSION=$(grep requires-python pyproject.toml | grep -oP '[\d.]+')
echo "Required Python: $REQUIRED_VERSION"
# Get the latest release tag from python-build-standalone
RELEASE_TAG=$(curl -sL "https://api.github.com/repos/astral-sh/python-build-standalone/releases/latest" | grep '"tag_name"' | cut -d'"' -f4)
# Find and download the matching build
DOWNLOAD_URL=$(curl -sL "https://api.github.com/repos/astral-sh/python-build-standalone/releases/latest" | \
grep "browser_download_url" | grep "$REQUIRED_VERSION" | grep "x86_64-unknown-linux-gnu-install_only.tar.gz" | head -1 | cut -d'"' -f4)
mkdir -p /tmp/python-install && cd /tmp/python-install
curl -L -o python.tar.gz "$DOWNLOAD_URL"
tar -xzf python.tar.gz
# Verify
/tmp/python-install/python/bin/python3 --version
If the auto-detection doesn't find a URL (e.g., the version is too new), browse the releases page manually and look for a cpython-<version>+<tag>-x86_64-unknown-linux-gnu-install_only.tar.gz asset.
cd /home/user/posthog
uv sync --python /tmp/python-install/python/bin/python3
source .venv/bin/activate
# Run a specific test (if hogli is available)
hogli test path/to/test.py::TestClass::test_method -v
# Or use pytest directly
pytest path/to/test.py::TestClass::test_method -v
# Run all tests in a directory
hogli test posthog/hogql/test/ -v
Most tests require backend services running. If Docker is available, start them with:
docker compose -f docker-compose.dev.yml up -d
See docker-compose.dev.yml for the full list of services and ports. Some test directories have specific service requirements documented in their own configuration files.
Tests expect certain hostnames to resolve to localhost:
echo "127.0.0.1 kafka clickhouse clickhouse-coordinator objectstorage" | sudo tee -a /etc/hosts
Tests require environment variables defined in .github/workflows/ci-backend.yml (see the env: section at the top of the file). You can also copy .env.example to .env for local development defaults.
Some tests require frontend build artifacts to exist (even if empty):
mkdir -p frontend/dist
touch frontend/dist/index.html
touch frontend/dist/layout.html
touch frontend/dist/exporter.html
For SAML-related functionality:
sudo apt-get update
sudo apt-get install libxml2-dev libxmlsec1-dev libxmlsec1-openssl
The pytest.ini sets:
pythonpath = . commonDJANGO_SETTINGS_MODULE = posthog.settingsDEBUG=1, TEST=1Default ignores: --ignore=posthog/user_scripts --ignore=services/llm-gateway --ignore=common/ingestion/acceptance_tests
If you encounter issues with the test setup, refer to .github/workflows/ci-backend.yml for the authoritative CI configuration. This file shows: