Add headless CLI for one-shot agent runs

AGENTS.md

@@ -37,7 +37,7 @@ Hosts:
 - `apps/code`: Electron desktop host.
 - `apps/web`: web host and portability smoke test.
 - `apps/mobile`: React Native host.
-- `apps/cli`: thin shell over `@posthog/cli`.
+- `packages/cli`: headless CLI (`@posthog/code-cli`, bin `posthog-code-cli`) — one-shot agent runs over the in-process ACP connection.
 
 ## Rules
 

knip.json

@@ -34,6 +34,10 @@
       "project": ["src/**/*.ts", "bin/**/*.ts"],
       "includeEntryExports": true
     },
+    "packages/cli": {
+      "project": ["src/**/*.ts"],
+      "includeEntryExports": true
+    },
     "packages/agent": {
       "project": ["src/**/*.ts"],
       "ignore": ["src/templates/**"],

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

@@ -119,6 +119,7 @@ function createClaudeConnection(config: AcpConnectionConfig): AcpConnection {
       onStructuredOutput: config.onStructuredOutput,
       posthogApiConfig: resolveEnricherApiConfig(config),
       gatewayEnv: config.claudeGatewayEnv,
+      logger: config.logger?.child("ClaudeAcpAgent"),
     });
     return agent;
   }, agentStream);

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

@@ -251,6 +251,8 @@ export interface ClaudeAcpAgentOptions {
   posthogApiConfig?: PostHogAPIConfig;
   /** Explicit gateway config — avoids global process.env mutation across concurrent sessions. */
   gatewayEnv?: GatewayEnv;
+  /** Injected logger; defaults to a console logger with debug enabled. */
+  logger?: Logger;
 }
 
 export class ClaudeAcpAgent extends BaseAcpAgent {
@@ -274,7 +276,9 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
     this.toolUseCache = {};
     this.emittedToolCalls = new Set();
     this.toolUseStreamCache = new Map();
-    this.logger = new Logger({ debug: true, prefix: "[ClaudeAcpAgent]" });
+    this.logger =
+      options?.logger ??
+      new Logger({ debug: true, prefix: "[ClaudeAcpAgent]" });
     this.enrichment = createEnrichment(options?.posthogApiConfig, this.logger);
   }
 

packages/cli/e2e/cli.e2e.test.ts

@@ -0,0 +1,82 @@
+import { execFile, execFileSync } from "node:child_process";
+import {
+  existsSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { describe, expect, it } from "vitest";
+
+const execFileAsync = promisify(execFile);
+
+// Same env contract as packages/agent/e2e/config.ts: a local llm-gateway plus
+// a personal API key. Without the token the suite self-skips (never silent).
+const GATEWAY_URL =
+  process.env.POSTHOG_CODE_E2E_GATEWAY_URL || "http://localhost:3308/ci";
+const TOKEN = process.env.POSTHOG_CODE_E2E_GATEWAY_PERSONAL_API_KEY ?? "";
+const MODEL = process.env.POSTHOG_CODE_E2E_CLAUDE_MODEL || "claude-haiku-4-5";
+
+const CLI_PATH = resolve(__dirname, "../dist/cli.js");
+
+function setupRepo(): string {
+  // realpath: on macOS os.tmpdir() is a symlink and the SDK keys its session
+  // store by resolved path.
+  const repo = realpathSync(mkdtempSync(join(tmpdir(), "code-cli-e2e-")));
+  writeFileSync(join(repo, "hello.txt"), "hello\n");
+  execFileSync("git", ["init", "-q"], { cwd: repo });
+  execFileSync("git", ["add", "-A"], { cwd: repo });
+  execFileSync(
+    "git",
+    [
+      "-c",
+      "commit.gpgsign=false",
+      "-c",
+      "user.email=e2e@posthog.dev",
+      "-c",
+      "user.name=e2e",
+      "commit",
+      "-qm",
+      "init",
+    ],
+    { cwd: repo },
+  );
+  return repo;
+}
+
+describe.skipIf(!TOKEN)("posthog-code-cli", () => {
+  it("runs one turn and prints the answer", async () => {
+    expect(
+      existsSync(CLI_PATH),
+      `CLI not built at ${CLI_PATH} — run pnpm --filter @posthog/code-cli build first`,
+    ).toBe(true);
+    const repo = setupRepo();
+    try {
+      const { stdout } = await execFileAsync(
+        process.execPath,
+        [
+          CLI_PATH,
+          "Reply with exactly the word OK and nothing else.",
+          "--cwd",
+          repo,
+          "--model",
+          MODEL,
+        ],
+        {
+          env: {
+            ...process.env,
+            ANTHROPIC_BASE_URL: GATEWAY_URL,
+            ANTHROPIC_AUTH_TOKEN: TOKEN,
+          },
+          timeout: 240_000,
+        },
+      );
+      expect(stdout).toContain("OK");
+    } finally {
+      rmSync(repo, { recursive: true, force: true });
+    }
+  });
+});

packages/cli/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@posthog/code-cli",
+  "version": "0.0.0-dev",
+  "private": true,
+  "description": "Headless CLI for PostHog Code — one-shot agent runs over the in-process ACP connection",
+  "type": "module",
+  "bin": {
+    "posthog-code-cli": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "node ../../scripts/rimraf.mjs dist && tsup",
+    "typecheck": "pnpm exec tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "clean": "node ../../scripts/rimraf.mjs dist .turbo"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "1.1.0",
+    "@posthog/agent": "workspace:*",
+    "@posthog/shared": "workspace:*",
+    "commander": "^14.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "tsup": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "^4.1.8"
+  }
+}

packages/cli/src/args.test.ts

@@ -0,0 +1,145 @@
+import { mkdtempSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { parseCliArgs } from "./args";
+
+// argv passed to parseCliArgs mirrors process.argv: [node, script, ...args].
+function argv(...args: string[]): string[] {
+  return ["/usr/bin/node", "/path/to/posthog-code-cli", ...args];
+}
+
+describe("parseCliArgs", () => {
+  describe("defaults", () => {
+    it("returns default options when no flags or prompt are given", () => {
+      const result = parseCliArgs(argv());
+
+      expect("error" in result).toBe(false);
+      if ("error" in result) return;
+      expect(result.prompt).toBeUndefined();
+      expect(result.cwd).toBe(realpathSync(process.cwd()));
+      expect(result.permissionMode).toBe("auto");
+      expect(result.output).toBe("text");
+      expect(result.debug).toBe(false);
+    });
+  });
+
+  it("parses the prompt positional", () => {
+    const result = parseCliArgs(argv("Fix the failing test"));
+
+    expect("error" in result).toBe(false);
+    if ("error" in result) return;
+    expect(result.prompt).toBe("Fix the failing test");
+  });
+
+  describe("individual flags", () => {
+    it("parses --cwd to the realpath of a valid directory", () => {
+      const tmp = mkdtempSync(join(tmpdir(), "cli-args-test-"));
+      const result = parseCliArgs(argv("--cwd", tmp));
+
+      expect("error" in result).toBe(false);
+      if ("error" in result) return;
+      expect(result.cwd).toBe(realpathSync(tmp));
+    });
+
+    it("parses --permission-mode bypassPermissions", () => {
+      const result = parseCliArgs(
+        argv("--permission-mode", "bypassPermissions"),
+      );
+
+      expect("error" in result).toBe(false);
+      if ("error" in result) return;
+      expect(result.permissionMode).toBe("bypassPermissions");
+    });
+
+    it("parses a valid --model id", () => {
+      const result = parseCliArgs(argv("--model", "claude-opus-4"));
+
+      expect("error" in result).toBe(false);
+      if ("error" in result) return;
+      expect(result.model).toBe("claude-opus-4");
+    });
+
+    it("parses --system-prompt as-is", () => {
+      const result = parseCliArgs(
+        argv("--system-prompt", "Respond only in haiku"),
+      );
+
+      expect("error" in result).toBe(false);
+      if ("error" in result) return;
+      expect(result.systemPrompt).toBe("Respond only in haiku");
+    });
+
+    it("parses --output json", () => {
+      const result = parseCliArgs(argv("--output", "json"));
+
+      expect("error" in result).toBe(false);
+      if ("error" in result) return;
+      expect(result.output).toBe("json");
+    });
+
+    it("parses --debug as true when present", () => {
+      const result = parseCliArgs(argv("--debug"));
+
+      expect("error" in result).toBe(false);
+      if ("error" in result) return;
+      expect(result.debug).toBe(true);
+    });
+  });
+
+  describe("invalid --permission-mode values", () => {
+    it.each(["default", "plan", "acceptEdits", "yolo"])(
+      "rejects %j with an error result",
+      (mode) => {
+        const result = parseCliArgs(argv("--permission-mode", mode));
+
+        expect("error" in result).toBe(true);
+        if (!("error" in result)) return;
+        expect(typeof result.error).toBe("string");
+        expect(result.error.length).toBeGreaterThan(0);
+      },
+    );
+  });
+
+  describe("invalid --model prefixes", () => {
+    it.each(["gpt-4", "llama-3"])(
+      "rejects %j since it does not start with claude-",
+      (model) => {
+        const result = parseCliArgs(argv("--model", model));
+
+        expect("error" in result).toBe(true);
+        if (!("error" in result)) return;
+        expect(typeof result.error).toBe("string");
+        expect(result.error.length).toBeGreaterThan(0);
+      },
+    );
+  });
+
+  it("rejects an invalid --output value", () => {
+    const result = parseCliArgs(argv("--output", "yaml"));
+
+    expect("error" in result).toBe(true);
+    if (!("error" in result)) return;
+    expect(typeof result.error).toBe("string");
+    expect(result.error.length).toBeGreaterThan(0);
+  });
+
+  it("rejects a --cwd path that does not exist", () => {
+    const bogusPath = join(tmpdir(), "definitely-does-not-exist-cli-args-test");
+    const result = parseCliArgs(argv("--cwd", bogusPath));
+
+    expect("error" in result).toBe(true);
+    if (!("error" in result)) return;
+    expect(typeof result.error).toBe("string");
+    expect(result.error.length).toBeGreaterThan(0);
+  });
+
+  it("accepts a --cwd path pointing to a real directory", () => {
+    const tmp = mkdtempSync(join(tmpdir(), "cli-args-test-"));
+    const result = parseCliArgs(argv("--cwd", tmp));
+
+    expect("error" in result).toBe(false);
+    if ("error" in result) return;
+    expect(result.cwd).toBe(realpathSync(tmp));
+  });
+});