@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "stagehand": {
+      "command": "node",
+      "args": ["../core/dist/facade/stdio-server.mjs"]
+    }
+  }
+}
@@ -0,0 +1,65 @@
+# Claude Agent SDK + Stagehand facade over MCP/stdio
+
+A runnable example embedding a Claude agent via `@anthropic-ai/claude-agent-sdk`, with the
+Stagehand facade (`run` / `snapshot` / `screenshot`) wired in as a stdio MCP server
+programmatically — install, export keys, one line to run.
+
+## Setup
+
+Use Node.js 24 or later. From the repository root, build the integrations package first:
+
+```bash
+pnpm install
+pnpm exec turbo run build --filter @browserbasehq/stagehand-integrations
+```
+
+Export credentials (Browserbase is the default and recommended backend):
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+export BROWSERBASE_API_KEY=bb_live_...
+export BROWSERBASE_PROJECT_ID=...
+```
+
+## Run
+
+```bash
+pnpm --filter @browserbasehq/stagehand-integrations-example-claude-code-facade start "Open https://example.com, snapshot it, and report the heading citing the snapshot ID."
+```
+
+| Variable                 | Purpose                                                                                          |
+| ------------------------ | ------------------------------------------------------------------------------------------------ |
+| `STAGEHAND_BROWSER`      | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. |
+| `BROWSERBASE_API_KEY`    | Browserbase credential for the browser session.                                                  |
+| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project.                                                                    |
+| `CLAUDE_STAGEHAND_MODEL` | Agent model; defaults to `claude-sonnet-5`.                                                      |
+| `ANTHROPIC_API_KEY`      | Claude Agent SDK credential (never forwarded to the browser).                                    |
+
+The agent is restricted to the three `mcp__stagehand__*` tools (`allowedTools` plus a
+`canUseTool` guard — headless runs hang on unanswered permission prompts otherwise), and its
+system prompt is the canonical `FACADE_AGENT_INSTRUCTIONS` imported from the facade package.
+
+## Connecting a running Claude Code CLI instead
+
+To use the facade from the interactive `claude` CLI rather than the SDK, the project-scoped
+`.mcp.json` in this directory is all that's needed — Claude Code inherits your shell
+environment, so the exports above are the only configuration:
+
+```bash
+cd packages/integrations/claude-code
+claude
+```
+
+Headless one-shot form:
+
+```bash
+claude -p "your instruction" --mcp-config .mcp.json --allowedTools "mcp__stagehand__run,mcp__stagehand__snapshot,mcp__stagehand__screenshot"
+```
+
+## Security model
+
+The `run` tool executes model-authored JavaScript inside the Stagehand browser extension's
+service worker — browser-side, never on your machine. Browserbase is the recommended isolation
+boundary: the privileged execution environment is a disposable cloud browser. The SDK example
+spawns the facade server with an explicit `STAGEHAND_*`/`BROWSERBASE_*` allowlist; your
+Anthropic credentials never reach the browser session.
@@ -0,0 +1,24 @@
+{
+  "name": "@browserbasehq/stagehand-integrations-example-claude-code-facade",
+  "version": "4.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node src/agent.ts",
+    "test": "pnpm -w exec turbo run build --filter @browserbasehq/stagehand-integrations && vitest run",
+    "test:unit": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "catalog:",
+    "@browserbasehq/stagehand-integrations": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}
@@ -0,0 +1,67 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import {
+  FACADE_AGENT_INSTRUCTIONS,
+  FACADE_TOOLS,
+} from "@browserbasehq/stagehand-integrations/facade";
+import { fileURLToPath } from "node:url";
+
+import { buildAllowlistedEnv } from "./env.ts";
+
+export const STAGEHAND_TOOL_NAMES = FACADE_TOOLS.map((tool) => `mcp__stagehand__${tool.name}`);
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  const instruction = (args[0] === "--" ? args.slice(1) : args).join(" ").trim();
+  if (!instruction) throw new Error('Usage: pnpm start "your instruction"');
+
+  // Resolved here (not at module load) so a missing build surfaces through
+  // handleFailure instead of an uncaught module error.
+  const serverPath = fileURLToPath(
+    import.meta.resolve("@browserbasehq/stagehand-integrations/facade/stdio-server"),
+  );
+
+  const result = query({
+    prompt: instruction,
+    options: {
+      model: process.env.CLAUDE_STAGEHAND_MODEL ?? "claude-sonnet-5",
+      maxTurns: 20,
+      systemPrompt: FACADE_AGENT_INSTRUCTIONS,
+      mcpServers: {
+        stagehand: {
+          command: process.execPath,
+          args: [serverPath],
+          env: buildAllowlistedEnv(),
+        },
+      },
+      allowedTools: STAGEHAND_TOOL_NAMES,
+      // Headless runs hang on any unanswered permission prompt; allow exactly
+      // the stagehand tools and deny everything else.
+      canUseTool: async (toolName) =>
+        toolName.startsWith("mcp__stagehand__")
+          ? { behavior: "allow", updatedInput: undefined }
+          : { behavior: "deny", message: "Only stagehand browser tools are permitted." },
+    },
+  });
+
+  for await (const message of result) {
+    if (message.type === "result") {
+      if (message.subtype === "success") {
+        // oxlint-disable-next-line no-console -- CLI example prints the agent result.
+        console.log(message.result);
+        return;
+      }
+      throw new Error(`Agent did not finish: ${message.subtype}`);
+    }
+  }
+  throw new Error("Agent stream ended without a result message.");
+}
+
+if (import.meta.main) {
+  main().catch(handleFailure);
+}
+
+function handleFailure(error: unknown): void {
+  // oxlint-disable-next-line no-console -- CLI example reports failures to stderr.
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+}
@@ -0,0 +1,10 @@
+/** Only STAGEHAND_* and BROWSERBASE_* host env vars cross into the server. */
+export function buildAllowlistedEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (/^(STAGEHAND_|BROWSERBASE_)/.test(key) && value) {
+      env[key] = value;
+    }
+  }
+  return env;
+}
@@ -0,0 +1,25 @@
+import { FACADE_TOOLS } from "@browserbasehq/stagehand-integrations/facade";
+import { describe, expect, it } from "vitest";
+
+import { STAGEHAND_TOOL_NAMES } from "../src/agent.ts";
+import { buildAllowlistedEnv } from "../src/env.ts";
+
+describe("claude-code stagehand example", () => {
+  it("allows exactly the namespaced facade tools", () => {
+    const expected = FACADE_TOOLS.map((tool) => `mcp__stagehand__${tool.name}`).sort();
+    expect([...STAGEHAND_TOOL_NAMES].sort()).toEqual(expected);
+  });
+
+  it("allowlist excludes non-STAGEHAND/BROWSERBASE host vars", () => {
+    process.env.STAGEHAND_BROWSER = "local";
+    process.env.NOT_ALLOWLISTED_SECRET = "must-not-cross";
+    try {
+      const env = buildAllowlistedEnv();
+      expect(env.STAGEHAND_BROWSER).toBe("local");
+      expect(env).not.toHaveProperty("NOT_ALLOWLISTED_SECRET");
+    } finally {
+      delete process.env.STAGEHAND_BROWSER;
+      delete process.env.NOT_ALLOWLISTED_SECRET;
+    }
+  });
+});
@@ -0,0 +1,10 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts", "vitest.config.ts"]
+}
@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["tests/**/*.test.ts"],
+    hookTimeout: 20_000,
+    testTimeout: 20_000,
+  },
+});