Prompt management

Prompt management lets you create and update LLM prompts directly in PostHog. When you use prompts through the SDK, they're fetched at runtime with caching and fallback support—so you can iterate on prompts without deploying code.

Why use prompt management?

• Update prompts without code deploys – Change prompts instantly from the PostHog UI
• Non-engineers can iterate – Product and content teams can tweak prompts without touching code
• Track prompt usage – Link prompts to generations to see which prompts drive which outputs
• Versioning – Every change creates an immutable version you can view, compare, or restore
• Labels – Point a label like production at a version and fetch by label, so saving a prompt and releasing it are separate steps
• Configuration – Store model parameters or any settings next to the prompt and change them without a deploy
• A/B testing – Compare prompt versions on cost, latency, and eval pass rate using PostHog Experiments

Creating prompts

1. Navigate to Prompt management > Prompts
2. Click New prompt
3. Enter a name for your prompt
4. Write your prompt content, using {{variables}} for dynamic values
5. Click Create prompt

This creates version 1 of your prompt. Each subsequent edit creates a new immutable version.

Markdown preview

When viewing a prompt, markdown rendering is enabled by default, formatting your prompt text with headings, lists, bold, and other markdown elements. Click the markdown icon next to the Prompt label to toggle it off and view plain text. When editing a prompt, the view switches to plain text automatically.

Prompt naming rules

• Names are immutable after creation (cannot be changed)
• Only letters, numbers, hyphens, and underscores allowed (^[a-zA-Z0-9_-]+$)
• Names must be unique within your project

Managing prompts via MCP

You can also manage prompts through the PostHog MCP server using AI agents like Claude Code, Cursor, or any MCP-connected tool.

The MCP server provides six prompt management tools:

This enables teams to manage prompts programmatically from agent workflows without using the web UI.

Template variables

Use double curly braces to define variables in your prompts:

You are a helpful assistant for {{company_name}}.
The user's name is {{user_name}} and their subscription tier is {{tier}}.

Variable names can include letters, numbers, underscores, hyphens, and dots.

Versioning

Every prompt change creates a new immutable version. Previous versions are preserved and accessible.

How versioning works

• The first save creates version 1
• Each subsequent publish increments the version number
• Previous versions are never modified
• By default, the SDK fetches the latest version

Publish a new version

1. Open a prompt and click New version
2. Make your changes
3. Click Publish — the button shows the number the new version will get, for example Publish v4
4. Review the diff of your changes, optionally add a note describing what changed, and confirm

The note appears alongside the version in the Version history sidebar, so you can scan past changes without opening diffs. It can also be set programmatically via the version_description field on the publish API and the MCP prompt-update tool.

If someone else published a new version while you were editing, publishing fails with a warning. Your edits are preserved in the editor — review them against the new latest version and publish again.

Restore a previous version

1. Open a prompt and select a version from the Version history sidebar
2. Click New version — the editor is prefilled with that version's content
3. Edit the prompt content if nee