:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import type { QueryToolInfo, ToolInfo } from '@/lib/instructions'
import { type InstructionsContext, InstructionsFormatter } from '@/lib/instructions-formatter'
import { getToolDefinition } from '@/tools/toolDefinitions'
import type { Tool, ZodObjectAny } from '@/tools/types'
const AGENT_HELP_HEADER = `# PostHog API guide for agents
\`posthog-cli api\` is the agent-first interface to the PostHog API. It exposes the same tool surface as the PostHog MCP server's \`exec\` tool, so the reference below is the canonical guide for interacting with PostHog. Treat it as instructions to follow, not just documentation.
On top of the reference below, the CLI adds:
- Add \`--project-id <id>\` and optionally \`--organization-id <id>\` to \`posthog-cli api call\` to select the target for that invocation. Explicit target flags replace both inherited project and organization defaults. Repeat the flags on every call, or set \`POSTHOG_CLI_PROJECT_ID\` and \`POSTHOG_CLI_ORGANIZATION_ID\` in each agent's environment. Project-only targets derive their organization from the project. Organization-only targets never fall back to a project in another organization; pass a project ID for project-scoped tools. Switch tools do not persist a selection across CLI invocations.
- \`posthog-cli api call --dry-run <tool> '<json>'\` — validate input against the tool schema without executing. Use it before any mutation.
- Destructive tools refuse to run without \`--confirm\`; add it only after verifying the exact target IDs.
- \`posthog-cli api skill list\` and \`posthog-cli api skill install <skill-id>\` — install PostHog agent skills into \`.agents/skills/\`. Before starting a PostHog task, check the skill list for a match; if one exists, install it, read its \`SKILL.md\`, and follow it — skills contain task-specific workflows that individual tools do not.
- \`posthog-cli api agents-md install [--path AGENTS.md]\` — install the PostHog steering snippet into a repository.`
const EXEC_INVOCATION_PATTERN = /posthog:exec\(\{\s*"command":\s*"((?:\\.|[^"\\])*)"\s*\}\)/g
function commandToCliInvocation(command: string): string {
const braceIndex = command.indexOf('{')
if (braceIndex === -1) {
return `posthog-cli api ${command}`
}
return `posthog-cli api ${command.slice(0, braceIndex).trimEnd()} '${command.slice(braceIndex)}'`
}
/** The MCP templates document the exec surface as \`posthog:exec({ "command": "<cmd>" })\`
* tool calls. The CLI exposes the identical command strings as \`posthog-cli api <cmd>\`,
* so rewriting invocations (instead of forking the templates) keeps one source of truth. */
export function toCliSyntax(text: string): string {
return text
.replace(EXEC_INVOCATION_PATTERN, (_match, command: string) =>
commandToCliInvocation(command.replace(/\\"/g, '"'))
)
.replace('### Using the `posthog` tool', '### Using `posthog-cli api`')
.replace(
'Pass CLI-style commands in the `command` parameter for all PostHog interactions.',
'Pass CLI-style commands as arguments to `posthog-cli api` for all PostHog interactions.'
)
}
/** Build the full agent-facing guide for \`posthog-cli api --agent-help\` from the same
* exec-tool templates the MCP server serves, including the tool-domain index and the
* query-tool catalog derived from the bundled tool registry (no network or auth needed). */
export function buildAgentHelp(tools: Tool<ZodObjectAny>[]): string {
const formatter = new InstructionsFormatter()
const toolInfos: ToolInfo[] = tools.map((tool) => ({
name: tool.name,
category: getToolDefinition(tool.name).category,
}))
const queryTools: QueryToolInfo[] = tools
.filter((tool) => tool.name.startsWith('query-'))
.map((tool) => {
const definition = getToolDefinition(tool.name)
return {
name: tool.name,
title: definition.title,
...(definition.system_prompt_hint ? { systemPromptHint: definition.system_prompt_hint } : {}),
} as QueryToolInfo
})
const ctx: InstructionsContext = { guidelines: '', tools: toolInfos, queryTools }
const sections = [AGENT_HELP_HEADER, formatter.buildExecToolDescription(), formatter.buildExecCommandReference(ctx)]
return toCliSyntax(sections.join('\n\n'))
}