rechrome 1.0.0 → 1.2.0

package/.env.example

@@ -10,3 +10,7 @@
 
 # Bind address for the server (default: 127.0.0.1, use 0.0.0.0 for remote access)
 # RECH_HOST=127.0.0.1
+
+# Playwright MCP extension settings (can be set on server or client; client overrides server)
+# PLAYWRIGHT_MCP_EXTENSION_ID=your-extension-id
+# PLAYWRIGHT_MCP_EXTENSION_TOKEN=your-extension-token

package/README.md

@@ -10,7 +10,7 @@ Built on top of [playwright-multi-tab](https://github.com/snomiao/playwright-mul
 
 - **Session isolation** — clients are automatically namespaced by git repo or hostname
 - **File transfer** — screenshots and PDFs are automatically downloaded to the client
-- **Vision descriptions** — optional Gemini-powered screenshot descriptions
+- **Vision descriptions** — opt-in Gemini-powered screenshot descriptions (`--gemini-vision`)
 - **Hot-reload config** — `.env.local` changes are picked up without restart
 - **Security** — bearer auth, path traversal protection, env allowlisting for child processes
 
@@ -61,6 +61,9 @@ rechrome open https://example.com
 # Take a screenshot
 rechrome screenshot
 
+# Take a screenshot with Gemini vision description
+rechrome screenshot --gemini-vision
+
 # List open tabs
 rechrome tab-list
 
@@ -76,12 +79,14 @@ Copy `.env.example` to `.env.local` and edit:
 cp .env.example .env.local
 ```
 
-| Variable | Description | Default |
-|---|---|---|
-| `REMOTE_CHROME_URL` | Connection URL (auto-generated by `rechrome serve`) | — |
-| `GEMINI_API_KEY` | Gemini API key for screenshot vision descriptions | — |
-| `PLAYWRIGHT_CLI` | Path to playwright-cli binary (recommended: `playwright-cli-multi-tab` for full multi-tab support) | `playwright-cli` |
-| `RECH_HOST` | Server bind address | `127.0.0.1` |
+| Variable                         | Description                                                                                        | Default          |
+| -------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------- |
+| `REMOTE_CHROME_URL`              | Connection URL (auto-generated by `rechrome serve`)                                                | —                |
+| `GEMINI_API_KEY`                 | Gemini API key for `--gemini-vision` screenshot descriptions                                       | —                |
+| `PLAYWRIGHT_CLI`                 | Path to playwright-cli binary (recommended: `playwright-cli-multi-tab` for full multi-tab support) | `playwright-cli` |
+| `RECH_HOST`                      | Server bind address                                                                                | `127.0.0.1`      |
+| `PLAYWRIGHT_MCP_EXTENSION_ID`    | Chrome extension ID (client overrides server)                                                      | —                |
+| `PLAYWRIGHT_MCP_EXTENSION_TOKEN` | Chrome extension token (client overrides server)                                                   | —                |
 
 ### Remote access
 

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "rechrome",
-  "version": "1.0.0",
-  "type": "module",
+  "version": "1.2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/snomiao/rechrome.git"
@@ -10,6 +9,16 @@
     "rech": "./rech.js",
     "rechrome": "./rech.js"
   },
+  "files": [
+    ".env.example",
+    "LICENSE",
+    "README.md",
+    "rech.js",
+    "rech.ts",
+    "serve.js",
+    "serve.ts"
+  ],
+  "type": "module",
   "scripts": {
     "serve": "bun run rech.ts serve",
     "test": "bun test",
@@ -22,14 +31,5 @@
     "branches": [
       "main"
     ]
-  },
-  "files": [
-    "rech.ts",
-    "rech.js",
-    "serve.ts",
-    "serve.js",
-    ".env.example",
-    "README.md",
-    "LICENSE"
-  ]
+  }
 }

package/rech.js

@@ -70,6 +70,11 @@ export async function describeImage(imagePath: string): Promise<string | null> {
   }
 }
 
+export const PASSTHROUGH_ENV_KEYS = [
+  "PLAYWRIGHT_MCP_EXTENSION_ID",
+  "PLAYWRIGHT_MCP_EXTENSION_TOKEN",
+] as const;
+
 export function log(msg: string) {
   mkdirSync(LOG_DIR, { recursive: true });
   const ts = new Date().toISOString();
@@ -136,15 +141,33 @@ async function getClientIdentity(): Promise<{ gitUrl?: string; hostname?: string
       }
       if (branch) gitUrl += `/tree/${branch}`;
       // Strip any embedded credentials from the URL
-      try { const u = new URL(gitUrl); u.username = ""; u.password = ""; gitUrl = u.toString(); } catch {}
+      try {
+        const u = new URL(gitUrl);
+        u.username = "";
+        u.password = "";
+        gitUrl = u.toString();
+      } catch {}
       return { gitUrl };
     }
   } catch {}
   return { hostname: hostname(), cwd };
 }
 
+function getClientEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const key of PASSTHROUGH_ENV_KEYS) {
+    if (process.env[key]) env[key] = process.env[key];
+  }
+  return env;
+}
+
 async function run(url: string, args: string[]) {
   const { key, host, port } = parseUrl(url);
+
+  // Extract --gemini-vision flag (not forwarded to server args)
+  const geminiVision = args.includes("--gemini-vision");
+  const filteredArgs = args.filter((a) => a !== "--gemini-vision");
+
   const identity = await getClientIdentity();
   console.error(
     `[rech] connecting to ${host}:${port} (identity: ${identity.gitUrl || `${identity.hostname}:${identity.cwd}`})`,
@@ -152,7 +175,7 @@ async function run(url: string, args: string[]) {
   const res = await fetch(`http://${host}:${port}/run`, {
     method: "POST",
     headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
-    body: JSON.stringify({ args, identity }),
+    body: JSON.stringify({ args: filteredArgs, identity, env: getClientEnv(), geminiVision }),
     signal: AbortSignal.timeout(70_000),
   }).catch((e) => {
     console.error(`[rech] ${e.message}`);

package/rech.ts

@@ -70,6 +70,11 @@ export async function describeImage(imagePath: string): Promise<string | null> {
   }
 }
 
+export const PASSTHROUGH_ENV_KEYS = [
+  "PLAYWRIGHT_MCP_EXTENSION_ID",
+  "PLAYWRIGHT_MCP_EXTENSION_TOKEN",
+] as const;
+
 export function log(msg: string) {
   mkdirSync(LOG_DIR, { recursive: true });
   const ts = new Date().toISOString();
@@ -136,15 +141,33 @@ async function getClientIdentity(): Promise<{ gitUrl?: string; hostname?: string
       }
       if (branch) gitUrl += `/tree/${branch}`;
       // Strip any embedded credentials from the URL
-      try { const u = new URL(gitUrl); u.username = ""; u.password = ""; gitUrl = u.toString(); } catch {}
+      try {
+        const u = new URL(gitUrl);
+        u.username = "";
+        u.password = "";
+        gitUrl = u.toString();
+      } catch {}
       return { gitUrl };
     }
   } catch {}
   return { hostname: hostname(), cwd };
 }
 
+function getClientEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const key of PASSTHROUGH_ENV_KEYS) {
+    if (process.env[key]) env[key] = process.env[key];
+  }
+  return env;
+}
+
 async function run(url: string, args: string[]) {
   const { key, host, port } = parseUrl(url);
+
+  // Extract --gemini-vision flag (not forwarded to server args)
+  const geminiVision = args.includes("--gemini-vision");
+  const filteredArgs = args.filter((a) => a !== "--gemini-vision");
+
   const identity = await getClientIdentity();
   console.error(
     `[rech] connecting to ${host}:${port} (identity: ${identity.gitUrl || `${identity.hostname}:${identity.cwd}`})`,
@@ -152,7 +175,7 @@ async function run(url: string, args: string[]) {
   const res = await fetch(`http://${host}:${port}/run`, {
     method: "POST",
     headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
-    body: JSON.stringify({ args, identity }),
+    body: JSON.stringify({ args: filteredArgs, identity, env: getClientEnv(), geminiVision }),
     signal: AbortSignal.timeout(70_000),
   }).catch((e) => {
     console.error(`[rech] ${e.message}`);

package/serve.js

@@ -2,7 +2,15 @@ import { file } from "bun";
 import { createHash } from "crypto";
 import { mkdirSync } from "fs";
 import { join, resolve, relative, isAbsolute } from "path";
-import { log, parseUrl, getOrCreateUrl, authCheck, describeImage, RECH_DIR } from "./rech.js";
+import {
+  log,
+  parseUrl,
+  getOrCreateUrl,
+  authCheck,
+  describeImage,
+  RECH_DIR,
+  PASSTHROUGH_ENV_KEYS,
+} from "./rech.js";
 
 export function isUnderDir(base: string, candidate: string): boolean {
   const absBase = resolve(base) + "/";
@@ -44,6 +52,8 @@ export async function serve() {
       let args: string[];
       let sessionId: string;
       let clientName = "";
+      let clientEnv: Record<string, string> = {};
+      let geminiVision = false;
       if (Array.isArray(body)) {
         args = body;
         const clientAddr = `${req.headers.get("x-forwarded-for") || server.requestIP(req)?.address || "unknown"}`;
@@ -66,6 +76,13 @@ export async function serve() {
           clientName = clientAddr;
           log(`session from client IP fallback: ${clientAddr} -> ${sessionId}`);
         }
+        // Extract allowlisted env vars from client (client overrides server)
+        if (body.env && typeof body.env === "object") {
+          for (const key of PASSTHROUGH_ENV_KEYS) {
+            if (typeof body.env[key] === "string") clientEnv[key] = body.env[key];
+          }
+        }
+        if (body.geminiVision) geminiVision = true;
       }
 
       let clientSession = "";
@@ -117,6 +134,13 @@ export async function serve() {
         }
       }
 
+      // Merge passthrough env: server .env.local defaults, then client overrides
+      const passthroughEnv: Record<string, string | undefined> = {};
+      for (const key of PASSTHROUGH_ENV_KEYS) {
+        if (process.env[key]) passthroughEnv[key] = process.env[key];
+      }
+      Object.assign(passthroughEnv, clientEnv);
+
       const childEnv: Record<string, string | undefined> = {
         PATH: process.env.PATH,
         HOME: process.env.HOME,
@@ -124,6 +148,7 @@ export async function serve() {
         DISPLAY: process.env.DISPLAY,
         XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR,
         ...(clientName ? { PLAYWRIGHT_MCP_CLIENT_NAME: clientName } : {}),
+        ...passthroughEnv,
       };
       const proc = Bun.spawn([bin, ...filteredArgs, "--extension", `-s=${namespacedSession}`], {
         cwd: workDir,
@@ -177,12 +202,14 @@ export async function serve() {
         }
       }
 
-      // Auto-describe screenshot files with Gemini vision
+      // Auto-describe screenshot files with Gemini vision (opt-in via --gemini-vision)
       const descriptions: Record<string, string> = {};
-      for (const f of outputFiles) {
-        if (/\.(?:png|jpe?g)$/i.test(f)) {
-          const desc = await describeImage(join(workDir, f));
-          if (desc) descriptions[f] = desc;
+      if (geminiVision) {
+        for (const f of outputFiles) {
+          if (/\.(?:png|jpe?g)$/i.test(f)) {
+            const desc = await describeImage(join(workDir, f));
+            if (desc) descriptions[f] = desc;
+          }
         }
       }
 

package/serve.ts

@@ -2,7 +2,15 @@ import { file } from "bun";
 import { createHash } from "crypto";
 import { mkdirSync } from "fs";
 import { join, resolve, relative, isAbsolute } from "path";
-import { log, parseUrl, getOrCreateUrl, authCheck, describeImage, RECH_DIR } from "./rech.ts";
+import {
+  log,
+  parseUrl,
+  getOrCreateUrl,
+  authCheck,
+  describeImage,
+  RECH_DIR,
+  PASSTHROUGH_ENV_KEYS,
+} from "./rech.ts";
 
 export function isUnderDir(base: string, candidate: string): boolean {
   const absBase = resolve(base) + "/";
@@ -44,6 +52,8 @@ export async function serve() {
       let args: string[];
       let sessionId: string;
       let clientName = "";
+      let clientEnv: Record<string, string> = {};
+      let geminiVision = false;
       if (Array.isArray(body)) {
         args = body;
         const clientAddr = `${req.headers.get("x-forwarded-for") || server.requestIP(req)?.address || "unknown"}`;
@@ -66,6 +76,13 @@ export async function serve() {
           clientName = clientAddr;
           log(`session from client IP fallback: ${clientAddr} -> ${sessionId}`);
         }
+        // Extract allowlisted env vars from client (client overrides server)
+        if (body.env && typeof body.env === "object") {
+          for (const key of PASSTHROUGH_ENV_KEYS) {
+            if (typeof body.env[key] === "string") clientEnv[key] = body.env[key];
+          }
+        }
+        if (body.geminiVision) geminiVision = true;
       }
 
       let clientSession = "";
@@ -117,6 +134,13 @@ export async function serve() {
         }
       }
 
+      // Merge passthrough env: server .env.local defaults, then client overrides
+      const passthroughEnv: Record<string, string | undefined> = {};
+      for (const key of PASSTHROUGH_ENV_KEYS) {
+        if (process.env[key]) passthroughEnv[key] = process.env[key];
+      }
+      Object.assign(passthroughEnv, clientEnv);
+
       const childEnv: Record<string, string | undefined> = {
         PATH: process.env.PATH,
         HOME: process.env.HOME,
@@ -124,6 +148,7 @@ export async function serve() {
         DISPLAY: process.env.DISPLAY,
         XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR,
         ...(clientName ? { PLAYWRIGHT_MCP_CLIENT_NAME: clientName } : {}),
+        ...passthroughEnv,
       };
       const proc = Bun.spawn([bin, ...filteredArgs, "--extension", `-s=${namespacedSession}`], {
         cwd: workDir,
@@ -177,12 +202,14 @@ export async function serve() {
         }
       }
 
-      // Auto-describe screenshot files with Gemini vision
+      // Auto-describe screenshot files with Gemini vision (opt-in via --gemini-vision)
       const descriptions: Record<string, string> = {};
-      for (const f of outputFiles) {
-        if (/\.(?:png|jpe?g)$/i.test(f)) {
-          const desc = await describeImage(join(workDir, f));
-          if (desc) descriptions[f] = desc;
+      if (geminiVision) {
+        for (const f of outputFiles) {
+          if (/\.(?:png|jpe?g)$/i.test(f)) {
+            const desc = await describeImage(join(workDir, f));
+            if (desc) descriptions[f] = desc;
+          }
         }
       }