Skip to content
This repository was archived by the owner on Jan 27, 2026. It is now read-only.
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 2 additions & 83 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,84 +1,3 @@
# Welcome to the PostHog examples repo
# The `posthog/examples` repo is now `posthog/context-mill`

The examples repo assembles PostHog context for AI agents and LLMs. It gathers up-to-date content from multiple sources, packaging PostHog developer docs, prompts, and working example code into a versioned manifest, which can be shipped anywhere as a zip file.

The [PostHog MCP server](https://github.com/PostHog/posthog/tree/master/products/mcp) currently fetches the examples repo manifest and exposes it to any MCP-compatible client as resources and slash commands. This is what currently powers the PostHog [wizard](https://github.com/PostHog/wizard).

## Context engine

![context engine diagram](https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/context_engine_29f6d6ddc0.png)

The examples repo effectively acts as a context engine, an assembly line for turning disparate PostHog knowledge into something portable, something AI systems can reliably consume.

You can break its context engineering flow into three main stages.

**1. Context sourcing**: The examples repo pulls from the entire PostHog developer docs, with pages delivered from posthog.com as raw Markdown. It also includes curated, hand-crafted prompts and working example apps.

**2. Context assembly**: The examples repo transforms and packages the sourced context into a zip file manifest, which is meant to be portable and self-contained. We can structure and shape the manifest however we need.

**3. Context delivery**: The examples repo creates a versioned release for the manifest, which can be consumed by any agent or MCP server as a skill or resource.

## Example apps

We've got live, working example code that demonstrates PostHog in action. You can run these yourself to see events flow into your PostHog project.

## Example apps are not production-grade

These are more like model airplanes. They're dramatically simplified to make it easy to see PostHog in action. You shouldn't use these as starter projects or put them into production. The authentication is fake!

But the leanness makes these useful for agent-driven development. Use these as context to help your agent make better integration decisions about PostHog.

```
examples/
├── basics/
│ ├── next-app-router/ # Next.js 15 with App Router
│ ├── next-pages-router/ # Next.js 15 with Pages Router
│ ├── react-react-router/ # React with React Router
│ ├── react-tanstack-router/ # React with TanStack Router
│ └── tanstack-start/ # TanStack Start
│ └── django/ # Django
├── llm-prompts/ # Workflow guides for AI agents
├── mcp-commands/ # MCP command prompts (`/command` in agents, can wrap `llm-prompts`)
└── scripts/ # Build scripts
```

## MCP resources

This repository serves as the **single source of truth** for PostHog integration resources accessed via the [PostHog MCP server](https://github.com/PostHog/posthog/tree/master/services/mcp).

### Build outputs

Run `npm run build:docs` to generate:

| Output | Description |
|--------|-------------|
| `dist/*.md` | Example projects converted to markdown |
| `dist/manifest.json` | Resource URIs and metadata |
| `dist/examples-mcp-resources.zip` | Complete archive for MCP server |

### Manifest structure

The manifest defines:
- **Workflows**: Step-by-step guides with automatic next-step linking
- **Docs**: PostHog documentation URLs (fetched at runtime)
- **Prompts**: MCP command prompts with template variable substitution
- **Templates**: Resource templates for parameterized access (e.g., `posthog://examples/{framework}`)

### Adding new resources

**Workflows**: Add markdown files to `llm-prompts/[category]/` following the naming convention `[order].[step]-[name].md`

**Examples**: Add new example projects to `basics/` and configure in `scripts/build-examples-mcp-resources.js`

**Prompts**: Add JSON files to `mcp-commands/`

The build script automatically discovers, orders, and generates URIs for all resources.

### Architecture

- **Single source of truth**: All URIs defined in this repo
- **Zero hardcoding**: MCP server purely reflects the manifest for `resources` and `prompts` (as defined in the MCP [spec](https://modelcontextprotocol.io/specification/2025-11-25#features))
- **Easy to extend**: Add resources by creating properly named files
- **Version controlled**: Resources evolve with the examples

See `llm-prompts/README.md` for detailed workflow conventions.
Check it out here: https://github.com/PostHog/context-mill/