Omnibus Instrument Integration

PostHogOfficialCreated by PostHog

Skill
Tool integration
Data and AI
MIT
Low risk

From the author

Add PostHog SDK integration to your application. Use when setting up PostHog for the first time or reviewing PRs that need PostHog initialization. Covers SDK installation, provider setup, and basic configuration for any framework.

— the description by PostHog

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured, multi-step procedure for integrating the PostHog SDK into a wide variety of software projects. It guides the agent through detecting the project's framework, installing the appropriate SDK, initializing the client, and configuring environment variables. By leveraging a library of framework-specific reference files, the skill ensures that PostHog is implemented according to best practices for each supported platform, including web, mobile, and backend environments.

What it does

Detects the project's framework and package manager automatically.
Installs the correct PostHog SDK for the identified platform.
Initializes the PostHog client using framework-specific patterns.
Configures environment variables for API keys and host settings.
Implements user identification logic for login and signup events.
Verifies the integration and performs necessary cleanup.

When to use it

When setting up PostHog in a project for the first time.
When reviewing pull requests that require PostHog initialization.
When migrating or adding analytics to an existing codebase.
When you need to ensure PostHog is configured consistently across different frameworks.

Advantages

Supports a broad range of frameworks and languages.
Ensures secure configuration by enforcing the use of environment variables.
Maintains consistency with existing codebase patterns.
Reduces manual effort by automating SDK installation and boilerplate setup.

Usage examples

“Add PostHog to my new Next.js project.”: The agent will detect the Next.js framework, install the PostHog SDK, and provide the necessary initialization code in the appropriate file, such as instrumentation-client.ts.
“Help me set up PostHog in our Android app.”: The agent will identify the Android environment, guide the setup in the Application class, and configure the PostHog instance with the required API keys.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/posthog/omnibus-instrument-integration/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip omnibus-instrument-integration.zip -d .agents/skills

Documentation by PostHog

Add PostHog SDK integration

Use this skill to add the PostHog SDK to an application. Use it when setting up PostHog for the first time, or reviewing PRs that need PostHog initialization. Covers SDK installation, provider setup, and basic configuration. Supports any framework or language.

Supported frameworks: Next.js, React, React Router, Vue, Nuxt, TanStack Start, SvelteKit, Astro, Angular, Django, Flask, FastAPI, Laravel, Ruby on Rails, Android, Swift, React Native, Expo, Node.js, and vanilla JavaScript.

Instructions

Follow these steps IN ORDER:

STEP 1: Analyze the codebase and detect the platform.

Look for dependency files (package.json, requirements.txt, Gemfile, composer.json, go.mod, etc.) to determine the framework and language.
Look for lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb) to determine the package manager.
Check for existing PostHog setup. If PostHog is already installed and initialized, do not modify its code. Inform the user and skip to verification.

STEP 2: Research integration. 2.1. Find the reference file below that matches the detected framework — it is the source of truth for SDK initialization, provider setup, and configuration patterns. Read it now. 2.2. If no reference matches, fall back to your general knowledge and web search. Use posthog.com/docs as the primary search source.

STEP 3: Install the PostHog SDK.

Add the PostHog SDK package for the detected platform. Do not manually edit package.json — use the package manager's install command.
Always install packages as a background task. Don't await completion; proceed with other work immediately after starting the installation.

STEP 4: Initialize PostHog.

Follow the framework reference for where and how to initialize. This varies significantly by framework (e.g., instrumentation-client.ts for Next.js 15.3+, AppConfig.ready() for Django, create_app() for Flask).
Set up the PostHog provider/wrapper component if the framework requires one.

STEP 5: Identify users.

Add PostHog identify() calls on the client side during login and signup events.
If both frontend and backend exist, pass the client-side session and distinct ID using X-POSTHOG-DISTINCT-ID and X-POSTHOG-SESSION-ID headers to the server-side code.

STEP 6: Set up environment variables.

Store the PostHog API key and host in environment variables (e.g. .env or framework-specific env files).
Reference these environment variables in code instead of hardcoding them.

STEP 7: Verify and clean up.

Check the project for errors. Look for type checking or build scripts in package.json.
Ensure any components created were actually used.
Run any linter or prettier-like scripts found in the package.json.

Reference files

references/EXAMPLE-next-app-router.md - next-app-router example project code
references/EXAMPLE-next-pages-router.md - next-pages-router example project code
references/EXAMPLE-react-react-router-6.md - react-react-router-6 example project code
references/EXAMPLE-react-react-router-7-framework.md - react-react-router-7-framework example project code
references/EXAMPLE-react-react-router-7-data.md - react-react-router-7-data example project code
references/EXAMPLE-react-react-router-7-declarative.md - react-react-router-7-declarative example project code
references/EXAMPLE-react-vite.md - react-vite example project code
references/EXAMPLE-nuxt-3.6.md - nuxt-3.6 example project code
references/EXAMPLE-nuxt-4.md - nuxt-4 example project code
references/EXAMPLE-vue-3.md - vue-3 example project code
references/EXAMPLE-react-tanstack-router-file-based.md - react-tanstack-router-file-based example project code
references/EXAMPLE-react-tanstack-router-code-based.md - react-tanstack-router-code-based example project code
references/EXAMPLE-tanstack-start.md - tanstack-start example project code
references/EXAMPLE-sveltekit.md - sveltekit example project code
references/EXAMPLE-astro-static.md - astro-static example project code
references/EXAMPLE-astro-view-transitions.md - astro-view-transitions example project code
references/EXAMPLE-astro-ssr.md - astro-ssr example project code
references/EXAMPLE-astro-hybrid.md - astro-hybrid example project code
references/EXAMPLE-angular.md - angular example project code
references/EXAMPLE-javascript-node.md - javascript-node example project code
references/EXAMPLE-javascript-web.md - javascript-web example project code
references/EXAMPLE-django.md - django example project code
references/EXAMPLE-flask.md - flask example project code
references/EXAMPLE-fastapi.md - fastapi example project code
references/EXAMPLE-python.md - python example project code
references/EXAMPLE-laravel.md - laravel example project code
references/EXAMPLE-ruby-on-rails.md - ruby-on-rails example project code
references/EXAMPLE-ruby.md - ruby example project code
references/EXAMPLE-android.md - android example project code
references/EXAMPLE-swift.md - swift example project code
references/EXAMPLE-react-native.md - react-native example project code
references/EXAMPLE-expo.md - expo example project code
references/next-js.md - Next.js - docs
references/react.md - React - docs
references/react-router-v6.md - React router v6 - docs
references/react-router-v7-framework-mode.md - React router v7 framework mode (remix v3) - docs
references/react-router-v7-data-mode.md - React router v7 data mode - docs
references/react-router-v7-declarative-mode.md - React router v7 declarative mode - docs
references/nuxt-js-3-6.md - Nuxt.js (v3.0 to v3.6) - docs
references/nuxt-js.md - Nuxt.js - docs
references/vue-js.md - Vue.js - docs
references/tanstack-start.md - Tanstack start - docs
references/svelte.md - Svelte - docs
references/astro.md - Astro - docs
references/angular.md - Angular - docs
references/js.md - JavaScript web - docs
references/posthog-js.md - PostHog JavaScript web SDK
references/node.md - Node.js - docs
references/posthog-node.md - PostHog Node.js SDK
references/django.md - Django - docs
references/flask.md - Flask - docs
references/python.md - Python - docs
references/posthog-python.md - PostHog python SDK
references/laravel.md - Laravel - docs
references/ruby-on-rails.md - Ruby on rails - docs
references/ruby.md - Ruby - docs
references/android.md - Android - docs
references/ios.md - Ios - docs
references/react-native.md - React native - docs
references/identify-users.md - Identify users - docs

Each framework reference contains SDK-specific installation, initialization, and usage patterns. Find the one matching the user's stack.

Key principles

Environment variables: Always use environment variables for PostHog keys. Never hardcode them.
Minimal changes: Add PostHog code alongside existing integrations. Don't replace or restructure existing code.
Match the example: Your implementation should follow the example project's patterns as closely as possible.
Analytics contract: Treat event names, property names, and feature flag keys as part of an analytics contract. Reuse existing names and patterns found in the project. When introducing new ones, make them clear, descriptive, and consistent with existing conventions.

Files

ATTRIBUTION.mdAdded by AutoGineer998 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md7.6 KiB
references/EXAMPLE-android.md49.7 KiB
references/EXAMPLE-angular.md23.4 KiB
references/EXAMPLE-astro-hybrid.md26.8 KiB
references/EXAMPLE-astro-ssr.md26.7 KiB
references/EXAMPLE-astro-static.md19.4 KiB
references/EXAMPLE-astro-view-transitions.md23.1 KiB
references/EXAMPLE-django.md30.0 KiB
references/EXAMPLE-expo.md35.5 KiB
references/EXAMPLE-fastapi.md40.9 KiB
references/EXAMPLE-flask.md32.0 KiB
references/EXAMPLE-javascript-node.md9.0 KiB
references/EXAMPLE-javascript-web.md11.7 KiB
references/EXAMPLE-laravel.md59.5 KiB
references/EXAMPLE-next-app-router.md17.3 KiB
references/EXAMPLE-next-pages-router.md18.9 KiB
references/EXAMPLE-nuxt-3.6.md22.1 KiB
references/EXAMPLE-nuxt-4.md28.7 KiB
references/EXAMPLE-python.md11.6 KiB
references/EXAMPLE-react-native.md46.4 KiB
references/EXAMPLE-react-react-router-6.md13.5 KiB
references/EXAMPLE-react-react-router-7-data.md20.1 KiB
references/EXAMPLE-react-react-router-7-declarative.md15.0 KiB
references/EXAMPLE-react-react-router-7-framework.md32.2 KiB
references/EXAMPLE-react-tanstack-router-code-based.md19.2 KiB
references/EXAMPLE-react-tanstack-router-file-based.md18.0 KiB
references/EXAMPLE-react-vite.md12.4 KiB
references/EXAMPLE-ruby-on-rails.md37.6 KiB
references/EXAMPLE-ruby.md10.3 KiB
references/EXAMPLE-sveltekit.md18.4 KiB
references/EXAMPLE-swift.md18.6 KiB
references/EXAMPLE-tanstack-start.md28.4 KiB
references/EXAMPLE-vue-3.md17.9 KiB
references/android.md21.7 KiB
references/angular.md12.5 KiB
references/astro.md8.3 KiB
references/django.md6.7 KiB
references/flask.md2.9 KiB
references/identify-users.md8.1 KiB
references/ios.md5.4 KiB
references/js.md12.3 KiB
references/laravel.md2.1 KiB
references/next-js.md12.5 KiB
references/node.md28.8 KiB
references/nuxt-js-3-6.md6.6 KiB
references/nuxt-js.md7.2 KiB
references/posthog-js.md42.3 KiB
references/posthog-node.md23.4 KiB
references/posthog-python.md31.3 KiB
references/python.md31.1 KiB
references/react-native.md43.8 KiB
references/react-router-v6.md11.6 KiB
references/react-router-v7-data-mode.md11.4 KiB
references/react-router-v7-declarative-mode.md11.6 KiB
references/react-router-v7-framework-mode.md14.9 KiB
references/react.md18.5 KiB
references/ruby-on-rails.md10.6 KiB
references/ruby.md18.9 KiB
references/svelte.md7.2 KiB
references/tanstack-start.md5.1 KiB
references/vue-js.md9.1 KiB

references/django.md

Django - Docs

PostHog makes it easy to get data about traffic and usage of your Django app. Integrating PostHog enables analytics, custom events capture, feature flags, and more.

This guide walks you through integrating PostHog into your Django app using the Python SDK.

Beta: integration via LLM

Install PostHog for Django in seconds with our wizard by running this prompt with LLM coding agents like Cursor and Bolt, or by running it in your terminal.

npx @posthog/wizard@latest

Learn more

Or, to integrate manually, continue with the rest of this guide.

Installation

To start, run pip install posthog to install PostHog’s Python SDK.

Then, set the PostHog API key and host in your AppConfig in your your_app/apps.py so that's it's available everywhere:

your_app/apps.py

PostHog AI

from django.apps import AppConfig
import posthog
class YourAppConfig(AppConfig):
    name = "your_app_name"
    def ready(self):
        posthog.api_key = '<ph_project_token>'
        posthog.host = 'https://us.i.posthog.com'

You can find your project token and instance address in your project settings.

Next, if you haven't done so already, make sure you add your AppConfig to your settings.py under INSTALLED_APPS:

settings.py

PostHog AI

INSTALLED_APPS = [
    # other apps
    'your_app_name.apps.MyAppConfig',  # Add your app config
]

Lastly, to access PostHog in any file, simply import posthog and call the method you'd like. For example, to capture an event:

Python

PostHog AI

import posthog
def some_request(request):
    with posthog.new_context():
        posthog.identify_context(request.user.id)
        posthog.capture('event_name')

Identifying users

Identifying users is required. Backend events need a distinct_id that matches the ID your frontend uses when calling posthog.identify(). Without this, backend events are orphaned — they can't be linked to frontend event captures, session replays, LLM traces, or error tracking.
See our guide on identifying users for how to set this up.

Django contexts middleware

The Python SDK provides a Django middleware that automatically wraps all requests with a context. This middleware extracts session and user information from request headers and tags all events captured during the request with relevant metadata.

Basic setup

Add the middleware to your Django settings:

Python

PostHog AI

MIDDLEWARE = [
    # ... other middleware
    'posthog.integrations.django.PosthogContextMiddleware',
    # ... other middleware
]

The middleware automatically extracts and uses:

Session ID from the X-POSTHOG-SESSION-ID header, if present
Distinct ID from the X-POSTHOG-DISTINCT-ID header, if present
Current URL as $current_url
Request method as $request_method

All events captured during the request (including exceptions) will include these properties and be associated with the extracted session and distinct ID.

If you are using PostHog on your frontend, the JavaScript Web SDK will add the session and distinct ID headers automatically if you enable tracing headers.

JavaScript

PostHog AI

posthog.init('<ph_project_token>', {
    __add_tracing_headers: ['your-backend-domain.com']
})

Exception capture

By default, the middleware captures exceptions and sends them to PostHog's error tracking. Disable this by setting:

Python

PostHog AI

# settings.py
POSTHOG_MW_CAPTURE_EXCEPTIONS = False

Adding custom tags

Use POSTHOG_MW_EXTRA_TAGS to add custom properties to all requests:

Python

PostHog AI

# settings.py
def add_user_tags(request):
    # type: (HttpRequest) -> Dict[str, Any]
    tags = {}
    if hasattr(request, 'user') and request.user.is_authenticated:
        tags['user_id'] = request.user.id
        tags['email'] = request.user.email
    return tags
POSTHOG_MW_EXTRA_TAGS = add_user_tags

Filtering requests

Skip tracking for certain requests using POSTHOG_MW_REQUEST_FILTER:

Python

PostHog AI

# settings.py
def should_track_request(request):
    # type: (HttpRequest) -> bool
    # Don't track health checks or admin requests
    if request.path.startswith('/health') or request.path.startswith('/admin'):
        return False
    return True
POSTHOG_MW_REQUEST_FILTER = should_track_request

Modifying default tags

Use POSTHOG_MW_TAG_MAP to modify or remove default tags:

Python

PostHog AI

# settings.py
def customize_tags(tags):
    # type: (Dict[str, Any]) -> Dict[str, Any]
    # Remove URL for privacy
    tags.pop('$current_url', None)
    # Add custom prefix to method
    if '$request_method' in tags:
        tags['http_method'] = tags.pop('$request_method')
    return tags
POSTHOG_MW_TAG_MAP = customize_tags

Complete configuration example

Python

PostHog AI

# settings.py
def add_request_context(request):
    # type: (HttpRequest) -> Dict[str, Any]
    tags = {}
    if hasattr(request, 'user') and request.user.is_authenticated:
        tags['user_type'] = 'authenticated'
        tags['user_id'] = str(request.user.id)
    else:
        tags['user_type'] = 'anonymous'
    # Add request info
    tags['user_agent'] = request.META.get('HTTP_USER_AGENT', '')
    return tags
def filter_tracking(request):
    # type: (HttpRequest) -> bool
    # Skip internal endpoints
    return not request.path.startswith(('/health', '/metrics', '/admin'))
def clean_tags(tags):
    # type: (Dict[str, Any]) -> Dict[str, Any]
    # Remove sensitive data
    tags.pop('user_agent', None)
    return tags
POSTHOG_MW_EXTRA_TAGS = add_request_context
POSTHOG_MW_REQUEST_FILTER = filter_tracking
POSTHOG_MW_TAG_MAP = clean_tags
POSTHOG_MW_CAPTURE_EXCEPTIONS = True

All events captured within the request context automatically include the configured tags and are associated with the session and user identified from the request headers.

Next steps

For any technical questions for how to integrate specific PostHog features into Django (such as analytics, feature flags, A/B testing, etc.), have a look at our Python SDK docs.

Alternatively, the following tutorials can help you get started:

Community questions

Ask a question

Was this page useful?

HelpfulCould be better

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an API key, Needs Python, Needs Node.js

Security

What our scanner noticed· Low risk

Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

PostHog

Publisher

PostHog (Official)

Source

PostHog/skills · skills/posthog/all/skills/omnibus-instrument-integration · commit a5d30e7

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by PostHog or PostHog.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download omnibus-instrument-integration.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by PostHog

Add PostHog SDK integration

Instructions

Reference files

Key principles

Files

references/django.md

Django - Docs

Beta: integration via LLM

Installation

Identifying users

Django contexts middleware

Basic setup

Exception capture

Adding custom tags

Filtering requests

Modifying default tags

Complete configuration example

Next steps

Community questions

Was this page useful?

Requirements and compatibility

Security

Attribution and licence

Related skills

Claude API

Transformers

Open Notebook

Vision Sft

LLM Evaluation

Lora Qlora Recipes

Download ZIP