Merge branch 'main' into feat/cloud-agent/user-authored-prs

Author: tatoalo

CONTRIBUTING.md

@@ -9,7 +9,9 @@ We love contributions big and small. PostHog Code is the IDE for understanding h
 3. Create a branch (`feat/my-change`, `fix/that-bug`)
 4. Make your changes and open a pull request
 
-We recommend creating an issue first if one doesn't already exist so we can align on the approach before you invest time.
+Issues labeled [`good first issue`](https://github.com/PostHog/code/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22) are a great place to start!
+
+If an issue does not yet exist for your change, please create one first so we can align on the approach before you invest time.
 
 ## Development setup
 

apps/code/scripts/download-binaries.mjs

@@ -19,7 +19,7 @@ const DEST_DIR = join(__dirname, "..", "resources", "codex-acp");
 const BINARIES = [
   {
     name: "codex-acp",
-    version: "0.9.5",
+    version: "0.11.1",
     getUrl: (version, target) => {
       const ext = target.includes("windows") ? "zip" : "tar.gz";
       return `https://github.com/zed-industries/codex-acp/releases/download/v${version}/codex-acp-${version}-${target}.${ext}`;

apps/code/src/main/services/agent/service.ts

@@ -16,8 +16,12 @@ import { isMcpToolReadOnly } from "@posthog/agent";
 import { hydrateSessionJsonl } from "@posthog/agent/adapters/claude/session/jsonl-hydration";
 import { getEffortOptions } from "@posthog/agent/adapters/claude/session/models";
 import { Agent } from "@posthog/agent/agent";
-import { getAvailableModes } from "@posthog/agent/execution-mode";
 import {
+  getAvailableCodexModes,
+  getAvailableModes,
+} from "@posthog/agent/execution-mode";
+import {
+  DEFAULT_CODEX_MODEL,
   DEFAULT_GATEWAY_MODEL,
   fetchGatewayModels,
   formatGatewayModelName,
@@ -178,6 +182,56 @@ const onAgentLog: OnLogCallback = (level, scope, message, data) => {
   }
 };
 
+const HAIKU_EXPLORE_AGENT_OVERRIDE = {
+  description:
+    'Fast agent for exploring and understanding codebases. Use this when you need to find files by pattern (eg. "src/components/**/*.tsx"), search for code or keywords (eg. "where is the auth middleware?"), or answer questions about how the codebase works (eg. "how does the session service handle reconnects?"). When calling this agent, specify a thoroughness level: "quick" for targeted lookups, "medium" for broader exploration, or "very thorough" for comprehensive analysis across multiple locations.',
+  model: "haiku",
+  prompt: `You are a fast, read-only codebase exploration agent.
+
+Your job is to find files, search code, read the most relevant sources, and report findings clearly.
+
+Rules:
+- Never create, modify, delete, move, or copy files.
+- Never use shell redirection or any command that changes system state.
+- Use Glob for broad file pattern matching.
+- Use Grep for searching file contents.
+- Use Read when you know the exact file path to inspect.
+- Use Bash only for safe read-only commands like ls, git status, git log, git diff, find, cat, head, and tail.
+- Adapt your search approach based on the thoroughness level specified by the caller.
+- Return file paths as absolute paths in your final response.
+- Avoid using emojis.
+- Wherever possible, spawn multiple parallel tool calls for grepping and reading files.
+- Search efficiently, then read only the most relevant files.
+- Return findings directly in your final response — do not create files.`,
+  tools: [
+    "Bash",
+    "Glob",
+    "Grep",
+    "Read",
+    "WebFetch",
+    "WebSearch",
+    "NotebookRead",
+    "TodoWrite",
+  ],
+};
+
+function buildClaudeCodeOptions(args: {
+  additionalDirectories?: string[];
+  effort?: EffortLevel;
+  plugins: { type: "local"; path: string }[];
+}) {
+  return {
+    ...(args.additionalDirectories?.length && {
+      additionalDirectories: args.additionalDirectories,
+    }),
+    ...(args.effort && { effort: args.effort }),
+    plugins: args.plugins,
+    agents: {
+      "ph-explore": HAIKU_EXPLORE_AGENT_OVERRIDE,
+    },
+  };
+}
+
 interface SessionConfig {
   taskId: string;
   taskRunId: string;
@@ -550,10 +604,18 @@ When creating pull requests, add the following footer at the end of the PR descr
     });
 
     try {
+      const systemPrompt = this.buildSystemPrompt(
+        credentials,
+        taskId,
+        customInstructions,
+      );
+
       const acpConnection = await agent.run(taskId, taskRunId, {
         adapter,
         gatewayUrl: proxyUrl,
         codexBinaryPath: adapter === "codex" ? getCodexBinaryPath() : undefined,
+        model,
+        instructions: adapter === "codex" ? systemPrompt.append : undefined,
         processCallbacks: {
           onProcessSpawned: (info) => {
             this.processTracking.register(
@@ -631,40 +693,37 @@ When creating pull requests, add the following footer at the end of the PR descr
         },
         ...externalPlugins,
       ];
+      const claudeCodeOptions = buildClaudeCodeOptions({
+        additionalDirectories,
+        effort,
+        plugins,
+      });
 
       let configOptions: SessionConfigOption[] | undefined;
       let agentSessionId: string;
 
-      if (isReconnect && adapter === "codex" && config.sessionId) {
-        const existingSessionId = config.sessionId;
-        const loadResponse = await connection.loadSession({
-          sessionId: existingSessionId,
-          cwd: repoPath,
-          mcpServers,
-        });
-        configOptions = loadResponse.configOptions ?? undefined;
-        agentSessionId = existingSessionId;
-      } else if (isReconnect && adapter === "claude" && config.sessionId) {
+      if (isReconnect && config.sessionId) {
         const existingSessionId = config.sessionId;
 
-        const posthogAPI = agent.getPosthogAPI();
-        if (posthogAPI) {
-          await hydrateSessionJsonl({
-            sessionId: existingSessionId,
-            cwd: repoPath,
-            taskId,
-            runId: taskRunId,
-            permissionMode: config.permissionMode,
-            posthogAPI,
-            log,
-          });
+        // Claude-specific: hydrate session JSONL from PostHog before resuming
+        if (adapter !== "codex") {
+          const posthogAPI = agent.getPosthogAPI();
+          if (posthogAPI) {
+            await hydrateSessionJsonl({
+              sessionId: existingSessionId,
+              cwd: repoPath,
+              taskId,
+              runId: taskRunId,
+              permissionMode: config.permissionMode,
+              posthogAPI,
+              log,
+            });
+          }
         }
 
-        const systemPrompt = this.buildSystemPrompt(
-          credentials,
-          taskId,
-          customInstructions,
-        );
+        // Both adapters implement unstable_resumeSession:
+        // - Claude: delegates to SDK's resumeSession with JSONL hydration
+        // - Codex: delegates to codex-acp's loadSession internally
         const resumeResponse = await connection.unstable_resumeSession({
           sessionId: existingSessionId,
           cwd: repoPath,
@@ -679,13 +738,7 @@ When creating pull requests, add the following footer at the end of the PR descr
             ...(permissionMode && { permissionMode }),
             ...(model != null && { model }),
             claudeCode: {
-              options: {
-                ...(additionalDirectories?.length && {
-                  additionalDirectories,
-                }),
-                ...(effort && { effort }),
-                plugins,
-              },
+              options: claudeCodeOptions,
             },
           },
         });
@@ -698,11 +751,6 @@ When creating pull requests, add the following footer at the end of the PR descr
             taskRunId,
           });
         }
-        const systemPrompt = this.buildSystemPrompt(
-          credentials,
-          taskId,
-          customInstructions,
-        );
         const newSessionResponse = await connection.newSession({
           cwd: repoPath,
           mcpServers,
@@ -712,11 +760,7 @@ When creating pull requests, add the following footer at the end of the PR descr
             ...(permissionMode && { permissionMode }),
             ...(model != null && { model }),
             claudeCode: {
-              options: {
-                ...(additionalDirectories?.length && { additionalDirectories }),
-                ...(effort && { effort }),
-                plugins,
-              },
+              options: claudeCodeOptions,
             },
           },
         });
@@ -1622,7 +1666,9 @@ For git operations while detached:
 
     const defaultModel =
       adapter === "codex"
-        ? (modelOptions[0]?.value ?? "")
+        ? (modelOptions.find((o) => o.value === DEFAULT_CODEX_MODEL)?.value ??
+          modelOptions[0]?.value ??
+          "")
         : DEFAULT_GATEWAY_MODEL;
 
     const resolvedModelId = modelOptions.some((o) => o.value === defaultModel)
@@ -1637,18 +1683,21 @@ For git operations while detached:
       });
     }
 
-    const modeOptions = getAvailableModes().map((mode) => ({
+    const modes =
+      adapter === "codex" ? getAvailableCodexModes() : getAvailableModes();
+    const modeOptions = modes.map((mode) => ({
       value: mode.id,
       name: mode.name,
       description: mode.description ?? undefined,
     }));
+    const defaultMode = adapter === "codex" ? "auto" : "plan";
 
     const configOptions: SessionConfigOption[] = [
       {
         id: "mode",
         name: "Approval Preset",
         type: "select",
-        currentValue: "plan",
+        currentValue: defaultMode,
         options: modeOptions,
         category: "mode",
         description:

apps/code/src/main/services/git/schemas.ts

@@ -260,6 +260,7 @@ export const createPrInput = z.object({
   draft: z.boolean().optional(),
   stagedOnly: z.boolean().optional(),
   taskId: z.string().optional(),
+  conversationContext: z.string().optional(),
 });
 
 export type CreatePrInput = z.infer<typeof createPrInput>;
@@ -331,6 +332,7 @@ export const getBranchChangedFilesOutput = z.array(changedFileSchema);
 
 export const generateCommitMessageInput = z.object({
   directoryPath: z.string(),
+  conversationContext: z.string().optional(),
 });
 
 export const generateCommitMessageOutput = z.object({
@@ -339,6 +341,7 @@ export const generateCommitMessageOutput = z.object({
 
 export const generatePrTitleAndBodyInput = z.object({
   directoryPath: z.string(),
+  conversationContext: z.string().optional(),
 });
 
 export const generatePrTitleAndBodyOutput = z.object({

apps/code/src/main/services/git/service.ts

@@ -515,6 +515,7 @@ export class GitService extends TypedEventEmitter<GitServiceEvents> {
     draft?: boolean;
     stagedOnly?: boolean;
     taskId?: string;
+    conversationContext?: string;
   }): Promise<CreatePrOutput> {
     const { directoryPath, flowId } = input;
 
@@ -537,12 +538,14 @@ export class GitService extends TypedEventEmitter<GitServiceEvents> {
         createBranch: (dir, name) => this.createBranch(dir, name),
         checkoutBranch: (dir, name) => this.checkoutBranch(dir, name),
         getChangedFilesHead: (dir) => this.getChangedFilesHead(dir),
-        generateCommitMessage: (dir) => this.generateCommitMessage(dir),
+        generateCommitMessage: (dir) =>
+          this.generateCommitMessage(dir, input.conversationContext),
         commit: (dir, msg, opts) => this.commit(dir, msg, opts),
         getSyncStatus: (dir) => this.getGitSyncStatus(dir),
         push: (dir) => this.push(dir),
         publish: (dir) => this.publish(dir),
-        generatePrTitleAndBody: (dir) => this.generatePrTitleAndBody(dir),
+        generatePrTitleAndBody: (dir) =>
+          this.generatePrTitleAndBody(dir, input.conversationContext),
         createPr: (dir, title, body, draft) =>
           this.createPrViaGh(dir, title, body, draft),
         onProgress: emitProgress,
@@ -988,6 +991,7 @@ export class GitService extends TypedEventEmitter<GitServiceEvents> {
 
   public async generateCommitMessage(
     directoryPath: string,
+    conversationContext?: string,
   ): Promise<{ message: string }> {
     const [stagedDiff, unstagedDiff, conventions, changedFiles] =
       await Promise.all([
@@ -1029,20 +1033,26 @@ Rules:
 - Use imperative mood ("Add feature" not "Added feature")
 - Be specific about what changed
 - If using conventional commits, include the appropriate prefix
+- If conversation context is provided, use it to understand WHY the changes were made and reflect that intent
 - Do not include any explanation, just output the commit message`;
 
+    const contextSection = conversationContext
+      ? `\n\nConversation context (why these changes were made):\n${conversationContext}`
+      : "";
+
     const userMessage = `Generate a commit message for these changes:
 
 Changed files:
 ${filesSummary}
 
 Diff:
-${truncatedDiff}`;
+${truncatedDiff}${contextSection}`;
 
     log.debug("Generating commit message", {
       fileCount: changedFiles.length,
       diffLength: diff.length,
       conventionalCommits: conventions.conventionalCommits,
+      hasConversationContext: !!conversationContext,
     });
 
     const response = await this.llmGateway.prompt(
@@ -1055,6 +1065,7 @@ ${truncatedDiff}`;
 
   public async generatePrTitleAndBody(
     directoryPath: string,
+    conversationContext?: string,
   ): Promise<{ title: string; body: string }> {
     await this.fetchIfStale(directoryPath);
 
@@ -1110,13 +1121,18 @@ Rules for the title:
 Rules for the body:
 - Start with a TL;DR section (1-2 sentences summarizing the change)
 - Include a "What changed?" section with bullet points describing the key changes
+- If conversation context is provided, use it to explain WHY the changes were made in the TL;DR
 - Be thorough but concise
 - Use markdown formatting
 - Only describe changes that are actually in the diff — do not invent or assume changes
 ${templateHint}
 
 Do not include any explanation outside the TITLE and BODY sections.`;
 
+    const contextSection = conversationContext
+      ? `\n\nConversation context (why these changes were made):\n${conversationContext}`
+      : "";
+
     const userMessage = `Generate a PR title and description for these changes:
 
 Branch: ${currentBranch ?? "unknown"} -> ${defaultBranch}
@@ -1125,12 +1141,13 @@ Commits in this PR:
 ${commitsSummary || "(no commits yet - changes are uncommitted)"}
 
 Diff:
-${truncatedDiff || "(no diff available)"}`;
+${truncatedDiff || "(no diff available)"}${contextSection}`;
 
     log.debug("Generating PR title and body", {
       commitCount: commits.length,
       diffLength: fullDiff.length,
       hasTemplate: !!prTemplate.template,
+      hasConversationContext: !!conversationContext,
     });
 
     const response = await this.llmGateway.prompt(

apps/code/src/main/trpc/routers/git.ts

@@ -312,14 +312,20 @@ export const gitRouter = router({
     .input(generateCommitMessageInput)
     .output(generateCommitMessageOutput)
     .mutation(({ input }) =>
-      getService().generateCommitMessage(input.directoryPath),
+      getService().generateCommitMessage(
+        input.directoryPath,
+        input.conversationContext,
+      ),
     ),
 
   generatePrTitleAndBody: publicProcedure
     .input(generatePrTitleAndBodyInput)
     .output(generatePrTitleAndBodyOutput)
     .mutation(({ input }) =>
-      getService().generatePrTitleAndBody(input.directoryPath),
+      getService().generatePrTitleAndBody(
+        input.directoryPath,
+        input.conversationContext,
+      ),
     ),
 
   searchGithubIssues: publicProcedure