feat: implement enricher (#1715)

## TLDR

Adds a file enrichment feature that annotates PostHog-related code with live metadata (event volume, flag rollout/staleness, experiment links) as the agent reads files.

Closes #1097

## Problem

When the agent reads source files containing PostHog SDK calls, it has no awareness of the current state of those flags or events in production. This means the agent lacks important product context — such as whether a flag is rolled out, how much volume an event has, or whether an event is verified — that would help it make better recommendations.

## Changes

- Introduces a new `@posthog/enricher` package dependency in the agent, with a `FileEnrichmentDeps`/`Enrichment` abstraction in `packages/agent/src/enrichment/file-enricher.ts` that wraps `PostHogEnricher` and exposes an `enrichFileForAgent` function
- For the Claude adapter, a `PostToolUse` hook (`createReadEnrichmentHook`) intercepts `Read` tool responses, strips line numbers, runs enrichment, and returns `additionalContext` to the model alongside writing enriched content to an `EnrichedReadCache` keyed by `tool_use_id`; the cache is consumed in `toolUpdateFromToolResult` so the UI displays the annotated version
- For the Codex adapter, enrichment is applied directly inside `readTextFile` on the `CodexClient`, replacing the file content before it reaches codex-acp
- Adds a `toInlineComments()` method on `EnrichedResult` that appends PostHog annotations as inline comments on the same source line (rather than inserting new lines above), and a corresponding `formatInlineComments` function in the comment formatter
- API errors (401, 500, network failures, malformed JSON) in `enrichFromApi` are now tolerated via `Promise.allSettled` rather than rejecting, returning partial/empty enrichment instead
- Fixes a HogQL query bug where typed placeholders (`{name:Type}`) and `INTERVAL` with a placeholder were rejected; `daysBack` is now inlined directly into the query string
- Enrichment is enabled by default when `posthog` config is present and can be disabled via `enricher: { enabled: false }` in `AgentConfig`
- Grammar file resolution in `ParserManager` now checks multiple candidate paths to support packaged Electron app layouts; the `forge.config.ts` asar unpack glob and a new `copyEnricherGrammars` Vite plugin ensure grammars are available at both dev and packaged runtime paths
- CI build and test workflows include a build step for `@posthog/enricher`
- Adds unit tests for `enrichFileForAgent`, `createReadEnrichmentHook`, and `createCodexClient.readTextFile`

Author: k11kirky

.github/workflows/build.yml

@@ -42,6 +42,9 @@ jobs:
       - name: Build git
         run: pnpm --filter @posthog/git build
 
+      - name: Build enricher
+        run: pnpm --filter @posthog/enricher build
+
       - name: Build agent
         run: pnpm --filter agent build
 

.github/workflows/test.yml

@@ -81,6 +81,7 @@ jobs:
           pnpm --filter @posthog/platform build &
           pnpm --filter @posthog/shared build
           pnpm --filter @posthog/git build
+          pnpm --filter @posthog/enricher build
           pnpm --filter agent build &
           wait
 

apps/code/forge.config.ts

@@ -143,7 +143,7 @@ const config: ForgeConfig = {
   packagerConfig: {
     asar: {
       unpack:
-        "{**/*.node,**/spawn-helper,**/.vite/build/claude-cli/**,**/.vite/build/plugins/posthog/**,**/.vite/build/codex-acp/**,**/node_modules/node-pty/**,**/node_modules/@parcel/**,**/node_modules/file-icon/**,**/node_modules/better-sqlite3/**,**/node_modules/bindings/**,**/node_modules/file-uri-to-path/**}",
+        "{**/*.node,**/spawn-helper,**/.vite/build/claude-cli/**,**/.vite/build/plugins/posthog/**,**/.vite/build/codex-acp/**,**/.vite/build/grammars/**,**/node_modules/node-pty/**,**/node_modules/@parcel/**,**/node_modules/file-icon/**,**/node_modules/better-sqlite3/**,**/node_modules/bindings/**,**/node_modules/file-uri-to-path/**}",
     },
     prune: false,
     name: "PostHog Code",

apps/code/vite.main.config.mts

@@ -424,6 +424,52 @@ function copyDrizzleMigrations(): Plugin {
   };
 }
 
+let enricherGrammarsCopied = false;
+
+function copyEnricherGrammars(): Plugin {
+  return {
+    name: "copy-enricher-grammars",
+    writeBundle() {
+      // `.vite/grammars` is what the bundle resolves at dev-time; electron-forge
+      // only copies `.vite/build/**` into the packaged app, so we need both.
+      const destDirs = [
+        join(__dirname, ".vite/grammars"),
+        join(__dirname, ".vite/build/grammars"),
+      ];
+
+      if (enricherGrammarsCopied && destDirs.every((d) => existsSync(d))) {
+        return;
+      }
+
+      const candidates = [
+        join(__dirname, "node_modules/@posthog/enricher/grammars"),
+        join(__dirname, "../../node_modules/@posthog/enricher/grammars"),
+        join(__dirname, "../../packages/enricher/grammars"),
+      ];
+
+      const sourceDir = candidates.find((p) => existsSync(p));
+      if (!sourceDir) {
+        console.warn(
+          "[copy-enricher-grammars] grammars directory not found. Checked:",
+          candidates.join(", "),
+        );
+        return;
+      }
+
+      for (const destDir of destDirs) {
+        if (!existsSync(destDir)) {
+          mkdirSync(destDir, { recursive: true });
+        }
+        cpSync(sourceDir, destDir, { recursive: true });
+      }
+      enricherGrammarsCopied = true;
+      console.log(
+        `Copied enricher grammars from ${sourceDir} to ${destDirs.join(", ")}`,
+      );
+    },
+  };
+}
+
 let codexAcpCopied = false;
 
 function copyCodexAcpBinaries(): Plugin {
@@ -492,6 +538,7 @@ export default defineConfig(({ mode }) => {
       copyPosthogPlugin(isDev),
       copyDrizzleMigrations(),
       copyCodexAcpBinaries(),
+      copyEnricherGrammars(),
       createPosthogPlugin(env, "posthog-code-main"),
     ].filter(Boolean),
     define: {

packages/agent/package.json

@@ -109,6 +109,7 @@
     "@opentelemetry/resources": "^2.0.0",
     "@opentelemetry/sdk-logs": "^0.208.0",
     "@opentelemetry/semantic-conventions": "^1.28.0",
+    "@posthog/enricher": "workspace:*",
     "@types/jsonwebtoken": "^9.0.10",
     "commander": "^14.0.2",
     "hono": "^4.11.7",

packages/agent/src/adapters/acp-connection.ts

@@ -1,6 +1,6 @@
 import { AgentSideConnection, ndJsonStream } from "@agentclientprotocol/sdk";
 import type { SessionLogWriter } from "../session-log-writer";
-import type { ProcessSpawnedCallback } from "../types";
+import type { PostHogAPIConfig, ProcessSpawnedCallback } from "../types";
 import { Logger } from "../utils/logger";
 import {
   createBidirectionalStreams,
@@ -26,6 +26,10 @@ export type AcpConnectionConfig = {
   allowedModelIds?: Set<string>;
   /** Callback invoked when the agent calls the create_output tool for structured output */
   onStructuredOutput?: (output: Record<string, unknown>) => Promise<void>;
+  /** PostHog API config; when set, enables file-read enrichment unless disabled. */
+  posthogApiConfig?: PostHogAPIConfig;
+  /** Defaults to true when posthogApiConfig is set. Set to false to disable enrichment. */
+  enricherEnabled?: boolean;
 };
 
 export type AcpConnection = {
@@ -54,6 +58,13 @@ export function createAcpConnection(
   return createClaudeConnection(config);
 }
 
+function resolveEnricherApiConfig(
+  config: AcpConnectionConfig,
+): PostHogAPIConfig | undefined {
+  const enabled = !!config.posthogApiConfig && config.enricherEnabled !== false;
+  return enabled ? config.posthogApiConfig : undefined;
+}
+
 function createClaudeConnection(config: AcpConnectionConfig): AcpConnection {
   const logger =
     config.logger?.child("AcpConnection") ??
@@ -102,6 +113,7 @@ function createClaudeConnection(config: AcpConnectionConfig): AcpConnection {
     agent = new ClaudeAcpAgent(client, {
       ...config.processCallbacks,
       onStructuredOutput: config.onStructuredOutput,
+      posthogApiConfig: resolveEnricherApiConfig(config),
     });
     return agent;
   }, agentStream);
@@ -192,6 +204,7 @@ function createCodexConnection(config: AcpConnectionConfig): AcpConnection {
     agent = new CodexAcpAgent(client, {
       codexProcessOptions: config.codexOptions ?? {},
       processCallbacks: config.processCallbacks,
+      posthogApiConfig: resolveEnricherApiConfig(config),
     });
     return agent;
   }, agentStream);

packages/agent/src/adapters/claude/claude-agent.ts

@@ -51,6 +51,12 @@ import {
   POSTHOG_METHODS,
   POSTHOG_NOTIFICATIONS,
 } from "../../acp-extensions";
+import {
+  createEnrichment,
+  type Enrichment,
+  type FileEnrichmentDeps,
+} from "../../enrichment/file-enricher";
+import type { PostHogAPIConfig } from "../../types";
 import { unreachable, withTimeout } from "../../utils/common";
 import { Logger } from "../../utils/logger";
 import { Pushable } from "../../utils/streams";
@@ -62,6 +68,7 @@ import {
   handleSystemMessage,
   handleUserAssistantMessage,
 } from "./conversion/sdk-to-acp";
+import type { EnrichedReadCache } from "./hooks";
 import {
   fetchMcpToolMetadata,
   getConnectedMcpServerNames,
@@ -116,6 +123,7 @@ export interface ClaudeAcpAgentOptions {
   onProcessExited?: (pid: number) => void;
   onMcpServersReady?: (serverNames: string[]) => void;
   onStructuredOutput?: (output: Record<string, unknown>) => Promise<void>;
+  posthogApiConfig?: PostHogAPIConfig;
 }
 
 export class ClaudeAcpAgent extends BaseAcpAgent {
@@ -125,12 +133,29 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
   backgroundTerminals: { [key: string]: BackgroundTerminal } = {};
   clientCapabilities?: ClientCapabilities;
   private options?: ClaudeAcpAgentOptions;
+  private enrichment?: Enrichment;
+  private enrichedReadCache: EnrichedReadCache = new Map();
 
   constructor(client: AgentSideConnection, options?: ClaudeAcpAgentOptions) {
     super(client);
     this.options = options;
     this.toolUseCache = {};
     this.logger = new Logger({ debug: true, prefix: "[ClaudeAcpAgent]" });
+    this.enrichment = createEnrichment(options?.posthogApiConfig, this.logger);
+  }
+
+  protected getEnrichmentDeps(): FileEnrichmentDeps | undefined {
+    return this.enrichment?.deps;
+  }
+
+  override async closeSession(): Promise<void> {
+    try {
+      await super.closeSession();
+    } finally {
+      this.enrichment?.dispose();
+      this.enrichment = undefined;
+      this.enrichedReadCache.clear();
+    }
   }
 
   async initialize(request: InitializeRequest): Promise<InitializeResponse> {
@@ -355,6 +380,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
       client: this.client,
       toolUseCache: this.toolUseCache,
       fileContentCache: this.fileContentCache,
+      enrichedReadCache: this.enrichedReadCache,
       logger: this.logger,
       supportsTerminalOutput,
     };
@@ -993,6 +1019,8 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
       onProcessSpawned: this.options?.onProcessSpawned,
       onProcessExited: this.options?.onProcessExited,
       effort,
+      enrichmentDeps: this.enrichment?.deps,
+      enrichedReadCache: this.enrichedReadCache,
     });
 
     // Use the same abort controller that buildSessionOptions gave to the query
@@ -1354,6 +1382,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
         client: this.client,
         toolUseCache: this.toolUseCache,
         fileContentCache: this.fileContentCache,
+        enrichedReadCache: this.enrichedReadCache,
         logger: this.logger,
         registerHooks: false,
       };

packages/agent/src/adapters/claude/conversion/sdk-to-acp.ts

@@ -21,7 +21,7 @@ import { POSTHOG_NOTIFICATIONS } from "@/acp-extensions";
 import { image, text } from "../../../utils/acp-content";
 import { unreachable } from "../../../utils/common";
 import type { Logger } from "../../../utils/logger";
-import { registerHookCallback } from "../hooks";
+import { type EnrichedReadCache, registerHookCallback } from "../hooks";
 import type { Session, ToolUpdateMeta, ToolUseCache } from "../types";
 import {
   type ClaudePlanEntry,
@@ -51,6 +51,7 @@ type ChunkHandlerContext = {
   sessionId: string;
   toolUseCache: ToolUseCache;
   fileContentCache: { [key: string]: string };
+  enrichedReadCache?: EnrichedReadCache;
   client: AgentSideConnection;
   logger: Logger;
   parentToolCallId?: string;
@@ -67,6 +68,7 @@ export interface MessageHandlerContext {
   client: AgentSideConnection;
   toolUseCache: ToolUseCache;
   fileContentCache: { [key: string]: string };
+  enrichedReadCache?: EnrichedReadCache;
   logger: Logger;
   registerHooks?: boolean;
   supportsTerminalOutput?: boolean;
@@ -248,7 +250,7 @@ function extractTextFromContent(content: unknown): string | null {
   return null;
 }
 
-function stripCatLineNumbers(text: string): string {
+export function stripCatLineNumbers(text: string): string {
   return text.replace(/^ *\d+[\t→]/gm, "");
 }
 
@@ -318,6 +320,7 @@ function handleToolResultChunk(
       supportsTerminalOutput: ctx.supportsTerminalOutput,
       toolUseId: chunk.tool_use_id,
       cachedFileContent: ctx.fileContentCache,
+      enrichedReadCache: ctx.enrichedReadCache,
     },
   );
 
@@ -448,6 +451,7 @@ function toAcpNotifications(
   supportsTerminalOutput?: boolean,
   cwd?: string,
   mcpToolUseResult?: Record<string, unknown>,
+  enrichedReadCache?: EnrichedReadCache,
 ): SessionNotification[] {
   if (typeof content === "string") {
     const update: SessionUpdate = {
@@ -468,6 +472,7 @@ function toAcpNotifications(
     sessionId,
     toolUseCache,
     fileContentCache,
+    enrichedReadCache,
     client,
     logger,
     parentToolCallId,
@@ -498,6 +503,7 @@ function streamEventToAcpNotifications(
   registerHooks?: boolean,
   supportsTerminalOutput?: boolean,
   cwd?: string,
+  enrichedReadCache?: EnrichedReadCache,
 ): SessionNotification[] {
   const event = message.event;
   switch (event.type) {
@@ -514,6 +520,8 @@ function streamEventToAcpNotifications(
         registerHooks,
         supportsTerminalOutput,
         cwd,
+        undefined,
+        enrichedReadCache,
       );
     case "content_block_delta":
       return toAcpNotifications(
@@ -528,6 +536,8 @@ function streamEventToAcpNotifications(
         registerHooks,
         supportsTerminalOutput,
         cwd,
+        undefined,
+        enrichedReadCache,
       );
     case "message_start":
     case "message_delta":
@@ -717,6 +727,7 @@ export async function handleStreamEvent(
     context.registerHooks,
     context.supportsTerminalOutput,
     context.session.cwd,
+    context.enrichedReadCache,
   )) {
     await client.sessionUpdate(notification);
     context.session.notificationHistory.push(notification);
@@ -840,6 +851,7 @@ export async function handleUserAssistantMessage(
     context.supportsTerminalOutput,
     session.cwd,
     mcpToolUseResult,
+    context.enrichedReadCache,
   )) {
     await client.sessionUpdate(notification);
     session.notificationHistory.push(notification);

packages/agent/src/adapters/claude/conversion/tool-use-to-acp.ts

@@ -31,6 +31,7 @@ function stripSystemReminders(value: string): string {
 }
 
 import { resourceLink, text, toolContent } from "../../../utils/acp-content";
+import type { EnrichedReadCache } from "../hooks";
 import { getMcpToolMetadata } from "../mcp/tool-metadata";
 
 type ToolInfo = Pick<ToolCall, "title" | "kind" | "content" | "locations">;
@@ -526,6 +527,7 @@ export function toolUpdateFromToolResult(
     supportsTerminalOutput?: boolean;
     toolUseId?: string;
     cachedFileContent?: Record<string, string>;
+    enrichedReadCache?: EnrichedReadCache;
   },
 ): Pick<ToolCallUpdate, "title" | "content" | "locations" | "_meta"> {
   if (
@@ -538,7 +540,21 @@ export function toolUpdateFromToolResult(
   }
 
   switch (toolUse?.name) {
-    case "Read":
+    case "Read": {
+      const cache = options?.enrichedReadCache;
+      const enriched =
+        cache && options?.toolUseId ? cache.get(options.toolUseId) : undefined;
+      if (enriched !== undefined && cache && options?.toolUseId) {
+        cache.delete(options.toolUseId);
+        return {
+          content: [
+            {
+              type: "content" as const,
+              content: text(markdownEscape(enriched)),
+            },
+          ],
+        };
+      }
       if (Array.isArray(toolResult.content) && toolResult.content.length > 0) {
         return {
           content: toolResult.content.map((item) => {
@@ -582,6 +598,7 @@ export function toolUpdateFromToolResult(
         };
       }
       return {};
+    }
 
     case "Bash": {
       const result = toolResult.content;