ai-browser-bridge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YosefHayim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,130 @@
+<p align="center">
+  <img src="assets/hero.png" alt="chatgpt-local-bridge — controla una sesión de ChatGPT en el navegador desde tu terminal mediante un puente MCP aislado" width="640" />
+</p>
+
+# chatgpt-local-bridge
+
+[English](README.md) · [עברית](README.he.md) · **Español** · [中文](README.zh.md)
+
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+![Node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
+![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)
+![Playwright](https://img.shields.io/badge/Playwright-browser-2EAD33?logo=playwright&logoColor=white)
+![MCP](https://img.shields.io/badge/MCP-connector-000000)
+
+---
+
+> Controla una conversación real de ChatGPT en el navegador desde tu terminal y dale un conjunto reducido y aislado (sandbox) de herramientas locales del repositorio vía MCP — sin entregarle nunca una shell.
+
+## Por qué existe
+
+ChatGPT rinde mejor en el navegador: el estado real de la cuenta, el selector de modelos, la edición de mensajes, la regeneración y el historial de conversación se mantienen intactos. Programar rinde mejor en la terminal, donde archivos, pruebas, diffs y parches se inspeccionan y modifican directamente.
+
+`chatgpt-local-bridge` conecta esas dos superficies. Un prompt en la terminal controla tu sesión existente de ChatGPT en el navegador, y ChatGPT puede acceder al repositorio actual mediante un pequeño conjunto de **herramientas MCP validadas** — `grep`, `read`, `apply_patch`, `run_tests`, `git_diff` — en lugar de acceso directo a la shell. Tú permaneces en un único flujo de terminal; ChatGPT conserva su interfaz real.
+
+## Características
+
+- **ChatGPT desde la terminal** — envía prompts y recibe respuestas sin salir de la shell; la conversación real del navegador es la fuente de verdad.
+- **Herramientas locales en sandbox vía MCP** — cada operación de archivo se valida contra la raíz del repositorio seleccionado; sin shell arbitraria, solo comandos de prueba en lista blanca.
+- **Acciones del navegador como comandos** — `/resume`, `/new`, `/model`, `/rewind`, `/stop`, `/context`, `/diff`, `/compact` y más.
+- **Sesiones y transcripciones locales por repositorio** — cada ejecución se registra en `<repo>/.bridge/` y se exporta como Markdown, JSON o JSONL.
+- **Controles de seguridad** — modos de permiso (`read-only` / `ask` / `auto`) y checkpoints automáticos de archivos alrededor de cada parche.
+- **Convenciones del proyecto** — comandos personalizados además de `AGENTS.md` / `CLAUDE.md` se envían a ChatGPT en las ejecuciones de `/task`.
+- **Un editor real** — historial de prompts, búsqueda inversa, cola de prompts y autocompletado de menciones `@file`.
+
+## Arquitectura
+
+```text
+ terminal (you)
+      │
+      │  Ink / React CLI
+      ▼
+ orchestrator ──────────────┬───────────────────────────────┐
+      │  browser automation │                   MCP server   │
+      ▼  (Playwright + CDP) │                  (MCP SDK)      ▼
+ ChatGPT browser UI         │                        local repo tools
+      ▲                     │                     (grep/read/patch/test/diff)
+      │                     ▼                                 │
+      └───── Cloudflare Tunnel (cloudflared) ◄────────────────┘
+              public https://…trycloudflare.com/mcp
+```
+
+Cuatro capas, cada una con un solo trabajo:
+
+| Capa | Tecnología | Responsabilidad |
+|------|------------|-----------------|
+| **CLI** | Ink / React | Interfaz de terminal: panel de mensajes, barra de estado, menciones `@file`, comandos `/`. |
+| **Navegador** | Playwright + Chrome DevTools Protocol | Controla la pestaña real de ChatGPT y captura respuestas. Los selectores están aislados en `src/browser/chatgpt-page.ts` para que los cambios de UI sean fáciles de arreglar. |
+| **Servidor MCP** | MCP SDK + Zod | Expone las herramientas locales del repositorio a ChatGPT como handlers validados por esquema y en sandbox. |
+| **Túnel** | Cloudflare Tunnel (`cloudflared`) | Da al servidor MCP local una URL HTTPS pública temporal que el conector de ChatGPT puede alcanzar — sin despliegue. |
+
+**¿Por qué un túnel?** El conector MCP de ChatGPT llama a las herramientas por HTTPS, pero el servidor de herramientas se ejecuta en tu máquina. En lugar de desplegar nada, el bridge levanta un túnel efímero de Cloudflare (`*.trycloudflare.com`) frente al puerto local y sincroniza esa URL `…/mcp` con la app de ChatGPT al iniciar. (ngrok resolvería el mismo problema de alcance; se usa `cloudflared` de Cloudflare porque sus túneles rápidos no requieren cuenta ni token.)
+
+## Inicio rápido
+
+**Requisitos previos**
+
+- **macOS** — Chrome se inicia desde `/Applications/Google Chrome.app`, y los ayudantes de portapapeles/procesos usan `pbcopy`/`lsof`.
+- **Node.js ≥ 20** y **pnpm** (el repo fija `pnpm@10.14.0`).
+- **Google Chrome** — el bridge controla un perfil real de Chrome.
+- **`cloudflared`** *(opcional)* — solo necesario para que ChatGPT llame a herramientas locales. Sin él la TUI igual funciona. Instala con `brew install cloudflared`.
+
+**Instalar y construir**
+
+```bash
+git clone https://github.com/YosefHayim/chatgpt-local-bridge.git
+cd chatgpt-local-bridge
+pnpm install
+pnpm build
+```
+
+**Inicia sesión una vez y luego ejecuta**
+
+```bash
+# Abre el perfil aislado de Chrome del bridge e inicia sesión en ChatGPT (persiste entre ejecuciones)
+node dist/bridge.js login
+
+# Lanza la interfaz de terminal sobre el repositorio donde ChatGPT trabajará
+node dist/bridge.js --repo /path/to/your/project
+```
+
+¿Prefieres un comando `bridge` global? Ejecuta `pnpm link --global` tras construir, y usa `bridge`, `bridge login`, `bridge ask "…"`, etc.
+
+## Dónde se guarda el estado
+
+Todo el estado del bridge para un proyecto se escribe **dentro de ese proyecto**, bajo `<repo>/.bridge/`. En el primer uso, el bridge escribe `.bridge/.gitignore` con un único `*`. Eso hace que git ignore **todo** lo que hay en el directorio — incluidas las transcripciones y las cookies de inicio de sesión — de modo que nada pueda llegar a un commit, aunque viva dentro del repositorio. Tanto `git add -A` como `git add .bridge/` lo omiten; solo un `git add -f` explícito podría forzarlo. El archivo se reafirma en cada ejecución, así que borrarlo o manipularlo se cura automáticamente.
+
+> La configuración escrita por el usuario y destinada a aplicarse a **todos** los repositorios sigue en tu directorio home: comandos personalizados en `~/.chatgpt-local-bridge/commands/*.md` y hooks de usuario en `~/.chatgpt-local-bridge/hooks.json`.
+
+## Permisos y checkpoints
+
+```bash
+/permissions read-only   # grep_code, read_file, git_diff
+/permissions auto        # también las herramientas de escritura/prueba acotadas
+/permissions ask         # bloquea herramientas de escritura/prueba/proceso (confirmación interactiva pendiente)
+```
+
+`apply_patch` toma un snapshot de cada ruta tocada antes y después del cambio. Recupera con `/checkpoints`, `/restore <id>` o `/rewind --files <id>`.
+
+## Pruebas
+
+```bash
+pnpm test          # vitest run
+pnpm typecheck     # tsc --noEmit
+pnpm verify:push   # typecheck + test + build (ejecutar antes de push)
+```
+
+La cobertura se centra en las rutas sensibles a la seguridad — validación de sandbox, resolución de rutas locales del repositorio, la auto-exclusión de `.bridge/`, los almacenes de sesiones/checkpoints, permisos y conteo de contexto.
+
+## Limitaciones
+
+- **Solo macOS** por ahora (ruta de Chrome fija y ayudantes `pbcopy`/`lsof`).
+- Los selectores del navegador de ChatGPT pueden romperse cuando cambia la UI web; los arreglos están localizados en la capa del navegador.
+- El uso de contexto es una **estimación** — el navegador no expone el conteo exacto de tokens del servidor.
+- El túnel de Cloudflare requiere `cloudflared` instalado.
+- Local-first por diseño; no es un servicio multiusuario alojado.
+- La ejecución de comandos de hooks se analiza y reporta pero aún no se ejecuta.
+
+## Licencia
+
+[MIT](LICENSE) © YosefHayim

package/README.he.md

@@ -0,0 +1,152 @@
+<p align="center">
+  <img src="assets/hero.png" alt="chatgpt-local-bridge — drive a ChatGPT browser session from your terminal over a sandboxed MCP bridge" width="640" />
+</p>
+
+# chatgpt-local-bridge
+
+[English](README.md) · **עברית** · [Español](README.es.md) · [中文](README.zh.md)
+
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+![Node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
+![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)
+![Playwright](https://img.shields.io/badge/Playwright-browser-2EAD33?logo=playwright&logoColor=white)
+![MCP](https://img.shields.io/badge/MCP-connector-000000)
+
+<div dir="rtl">
+
+> הפעילו שיחת ChatGPT אמיתית מהדפדפן ישירות מהטרמינל, ותנו לה גישה מצומצמת ומבוקרת (sandbox) לכלי הריפו המקומי דרך MCP — בלי למסור לה אף פעם גישת shell.
+
+## למה זה קיים
+
+‏ChatGPT נמצא בשיאו בדפדפן — מצב החשבון האמיתי, בורר המודלים, עריכת הודעות, רגנרציה והיסטוריית השיחה נשמרים במלואם. פיתוח קוד נמצא בשיאו בטרמינל, שם בודקים ומשנים קבצים, טסטים, diffs ו-patches ישירות.
+
+‏`chatgpt-local-bridge` מחבר בין שני המשטחים האלה. שורת פקודה בטרמינל מפעילה את שיחת ה-ChatGPT הקיימת שלכם בדפדפן, ו-ChatGPT יכול לגשת לריפו הנוכחי דרך מספר מצומצם של **כלי MCP מאומתים** — `grep`, `read`, `apply_patch`, `run_tests`, `git_diff` — במקום גישת shell חופשית. אתם נשארים בתהליך עבודה אחד בטרמינל; ל-ChatGPT נשאר ה-UI האמיתי שלו.
+
+## יכולות
+
+- **הפעלת ChatGPT מהטרמינל** — שולחים פרומפטים ומקבלים תשובות בלי לעזוב את ה-shell; שיחת הדפדפן האמיתית היא מקור האמת.
+- **כלים מקומיים ב-sandbox דרך MCP** — כל פעולת קובץ מאומתת מול שורש הריפו הנבחר; אין shell חופשי, רק פקודות טסט מאושרות מראש.
+- **פעולות דפדפן כפקודות** — ‏`/resume`, `/new`, `/model`, `/rewind`, `/stop`, `/context`, `/diff`, `/compact` ועוד.
+- **סשנים ותמלולים מקומיים לריפו** — כל הרצה נשמרת תחת `<repo>/.bridge/` וניתנת לייצוא כ-Markdown, JSON או JSONL.
+- **בקרות בטיחות** — מצבי הרשאה (`read-only` / `ask` / `auto`) ו-checkpoints אוטומטיים של קבצים סביב כל patch.
+- **מוסכמות פרויקט** — פקודות מותאמות אישית וגם `AGENTS.md` / `CLAUDE.md` מוזנים ל-ChatGPT בהרצות `/task`.
+- **קומפוזר אמיתי** — היסטוריית פרומפטים, חיפוש לאחור, תור פרומפטים, והשלמה אוטומטית לאזכורי `@file`.
+
+## ארכיטקטורה
+
+</div>
+
+```text
+ terminal (you)
+      │
+      │  Ink / React CLI
+      ▼
+ orchestrator ──────────────┬───────────────────────────────┐
+      │  browser automation │                   MCP server   │
+      ▼  (Playwright + CDP) │                  (MCP SDK)      ▼
+ ChatGPT browser UI         │                        local repo tools
+      ▲                     │                     (grep/read/patch/test/diff)
+      │                     ▼                                 │
+      └───── Cloudflare Tunnel (cloudflared) ◄────────────────┘
+              public https://…trycloudflare.com/mcp
+```
+
+<div dir="rtl">
+
+ארבע שכבות, לכל אחת תפקיד אחד:
+
+| שכבה | טכנולוגיה | אחריות |
+|------|-----------|--------|
+| **CLI** | Ink / React | ממשק טרמינל: חלונית הודעות, שורת סטטוס, אזכורי `@file`, פקודות `/`. |
+| **דפדפן** | Playwright + Chrome DevTools Protocol | מפעיל את לשונית ה-ChatGPT האמיתית ולוכד תשובות. הסלקטורים מבודדים ב-`src/browser/chatgpt-page.ts` כך ששינויי UI קלים לתיקון. |
+| **שרת MCP** | MCP SDK + Zod | חושף את כלי הריפו המקומיים ל-ChatGPT כ-handlers מאומתי-סכמה ומוגני-sandbox. |
+| **מנהרה** | Cloudflare Tunnel (`cloudflared`) | מעניק לשרת ה-MCP המקומי כתובת HTTPS ציבורית זמנית שה-connector של ChatGPT יכול להגיע אליה — ללא פריסה. |
+
+**למה בכלל מנהרה?** ה-connector של ChatGPT קורא לכלים דרך HTTPS, אבל שרת הכלים רץ על המחשב שלכם. במקום לפרוס משהו, ה-bridge מקים מנהרת Cloudflare זמנית (`*.trycloudflare.com`) מול הפורט המקומי ומסנכרן את כתובת ה-`…/mcp` הזו אל אפליקציית ChatGPT בעת ההפעלה. (‏ngrok היה פותר את אותה בעיית נגישות; נבחר `cloudflared` של Cloudflare מכיוון שמנהרות ה-quick שלו אינן דורשות חשבון או טוקן.)
+
+## התחלה מהירה
+
+**דרישות מקדימות**
+
+- **macOS** — ‏Chrome מופעל מ-`/Applications/Google Chrome.app`, ועוזרי הלוח/תהליכים משתמשים ב-`pbcopy`/`lsof`.
+- **Node.js ≥ 20** ו-**pnpm** (הריפו מקבע `pnpm@10.14.0`).
+- **Google Chrome** — ה-bridge מפעיל פרופיל Chrome אמיתי.
+- **`cloudflared`** *(אופציונלי)* — נדרש רק כדי ש-ChatGPT יקרא לכלים מקומיים. בלעדיו ה-TUI עדיין רץ. התקנה: `brew install cloudflared`.
+
+**התקנה ובנייה**
+
+</div>
+
+```bash
+git clone https://github.com/YosefHayim/chatgpt-local-bridge.git
+cd chatgpt-local-bridge
+pnpm install
+pnpm build
+```
+
+<div dir="rtl">
+
+**התחברו פעם אחת, ואז הריצו**
+
+</div>
+
+```bash
+# פתיחת פרופיל ה-Chrome המבודד של ה-bridge והתחברות ל-ChatGPT (נשמר בין הרצות)
+node dist/bridge.js login
+
+# הפעלת ממשק הטרמינל מול הריפו שבו ChatGPT יעבוד
+node dist/bridge.js --repo /path/to/your/project
+```
+
+<div dir="rtl">
+
+מעדיפים פקודת `bridge` גלובלית? הריצו `pnpm link --global` אחרי הבנייה, ואז השתמשו ב-`bridge`, `bridge login`, `bridge ask "…"` וכו'.
+
+## איפה נשמר המצב (state)
+
+כל מצב ה-bridge של פרויקט נכתב **בתוך אותו פרויקט**, תחת `<repo>/.bridge/`. בשימוש הראשון נכתב `.bridge/.gitignore` המכיל `*` בודד. זה גורם ל-git להתעלם מ**כל** מה שבתיקייה — כולל התמלולים ועוגיות ההתחברות — כך ששום דבר לא יכול להיכנס ל-commit, למרות שהוא נמצא בתוך הריפו. גם `git add -A` וגם `git add .bridge/` מדלגים עליו; רק `git add -f` מפורש יכול לעקוף. הקובץ נכתב מחדש בכל הרצה, כך שמחיקה או שינוי שלו מתרפאים אוטומטית.
+
+> תצורה שנכתבת על ידי המשתמש ומיועדת לחול על **כל** הריפואים נשמרת עדיין בתיקיית הבית: פקודות מותאמות ב-`~/.chatgpt-local-bridge/commands/*.md` ו-hooks ברמת המשתמש ב-`~/.chatgpt-local-bridge/hooks.json`.
+
+## הרשאות ו-checkpoints
+
+</div>
+
+```bash
+/permissions read-only   # grep_code, read_file, git_diff
+/permissions auto        # גם כלי הכתיבה/טסט המצומצמים
+/permissions ask         # חוסם כלי כתיבה/טסט/תהליך (אישור אינטראקטיבי בהמשך)
+```
+
+<div dir="rtl">
+
+‏`apply_patch` שומר snapshot של כל נתיב שנגעו בו לפני ואחרי השינוי. שחזור עם `/checkpoints`, `/restore <id>` או `/rewind --files <id>`.
+
+## בדיקות
+
+</div>
+
+```bash
+pnpm test          # vitest run
+pnpm typecheck     # tsc --noEmit
+pnpm verify:push   # typecheck + test + build (להריץ לפני push)
+```
+
+<div dir="rtl">
+
+הכיסוי מתמקד בנתיבים רגישי-בטיחות — אימות sandbox, רזולוציית נתיבים מקומיים לריפו, מנגנון ההתעלמות העצמית של `.bridge/`, מאגרי הסשנים/checkpoints, הרשאות וספירת הקשר.
+
+## מגבלות
+
+- **macOS בלבד** כיום (נתיב Chrome קשיח ועוזרי `pbcopy`/`lsof`).
+- סלקטורים של ChatGPT עלולים להישבר כשממשק הווב משתנה; התיקונים ממוקדים בשכבת הדפדפן.
+- ניצול ההקשר הוא **הערכה** — הדפדפן אינו חושף ספירת טוקנים מדויקת מצד השרת.
+- מנהרת Cloudflare דורשת `cloudflared` מותקן.
+- מקומי-תחילה מעיצובו; אינו שירות רב-משתמשים מאוחסן.
+- הרצת פקודות hook מנותחת ומדווחת אך עדיין אינה מבוצעת.
+
+## רישיון
+
+[MIT](LICENSE) © YosefHayim
+
+</div>

package/README.md

@@ -0,0 +1,250 @@
+<p align="center">
+  <img src="assets/hero.png" alt="ai-browser-bridge — drive ChatGPT or Gemini from your terminal over a sandboxed MCP bridge" width="640" />
+</p>
+
+# ai-browser-bridge
+
+> Drive a real ChatGPT or Gemini browser conversation from your terminal, and give ChatGPT a narrow, sandboxed set of local repo tools over MCP — without ever handing it a shell.
+
+**English** · [עברית](README.he.md) · [Español](README.es.md) · [中文](README.zh.md)
+
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+![Node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
+![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)
+![Playwright](https://img.shields.io/badge/Playwright-browser-2EAD33?logo=playwright&logoColor=white)
+![MCP](https://img.shields.io/badge/MCP-connector-000000)
+
+---
+
+## Why this exists
+
+ChatGPT is at its best in the browser — real account state, the model picker, message editing, regeneration, and conversation history all intact. Coding is at its best in the terminal, where files, tests, diffs, and patches are inspected and changed directly.
+
+`ai-browser-bridge` connects those two surfaces. A terminal prompt drives your existing ChatGPT or Gemini browser session, and ChatGPT can reach into the current repo through a small set of **validated MCP tools** — `grep`, `read`, `apply_patch`, `run_tests`, `git_diff` — instead of raw shell access. You stay in one terminal workflow; the provider keeps its real UI.
+
+## Features
+
+- **Terminal-driven ChatGPT** — send prompts and stream replies without leaving the shell; the real browser conversation stays the source of truth.
+- **Six providers, one command** — `chatgpt`, `gemini`, `claude`, `deepseek`, `grok`, `perplexity`. Pick one with `--provider`, or **fan out** across several (`--provider claude,deepseek,grok`) and get every reply keyed by provider in one call.
+- **Built for agents** — a stable non-interactive `bridge ask … --json` contract (never hangs in a pipe) plus an outbound MCP `ask` tool, so any agent can drive a web chat.
+- **Sandboxed local tools over MCP** — every file operation is validated against the selected repo root; no arbitrary shell, allowlisted test commands only.
+- **Browser actions as commands** — `/resume`, `/new`, `/model`, `/rewind`, `/stop`, `/context`, `/diff`, `/compact`, and more.
+- **Repo-local sessions & transcripts** — every run is recorded under `<repo>/.bridge/` and exportable as Markdown, JSON, or JSONL.
+- **Safety controls** — permission modes (`read-only` / `ask` / `auto`) and automatic file checkpoints around every patch.
+- **Project conventions** — custom commands plus `AGENTS.md` / `CLAUDE.md` are fed to ChatGPT for `/task` runs.
+- **A real composer** — prompt history, reverse search, queued prompts, and `@file` mention autocomplete.
+
+## Architecture
+
+```text
+ terminal (you)
+      │
+      │  Ink / React CLI
+      ▼
+ orchestrator ──────────────┬───────────────────────────────┐
+      │  browser automation │                   MCP server   │
+      ▼  (Playwright + CDP) │                  (MCP SDK)      ▼
+ ChatGPT browser UI         │                        local repo tools
+      ▲                     │                     (grep/read/patch/test/diff)
+      │                     ▼                                 │
+      └───── Cloudflare Tunnel (cloudflared) ◄────────────────┘
+              public https://…trycloudflare.com/mcp
+```
+
+Four layers, each with one job:
+
+| Layer | Tech | Responsibility |
+|-------|------|----------------|
+| **CLI** | Ink / React | Terminal UI: message pane, status line, `@file` mentions, `/commands`. |
+| **Browser** | Playwright + Chrome DevTools Protocol | Drives the real ChatGPT or Gemini tab; captures responses. Selectors live under `src/features/providers/chatgpt/` and `src/features/providers/gemini/`. |
+| **MCP server** | MCP SDK + Zod | Exposes the local repo tools to ChatGPT as schema-validated, sandboxed handlers. |
+| **Tunnel** | Cloudflare Tunnel (`cloudflared`) | Gives the local MCP server a temporary public HTTPS URL that ChatGPT's connector can reach — no deployment required. |
+
+**Why a tunnel at all?** ChatGPT's MCP connector calls tools over HTTPS, but the tool server runs on your machine. Rather than deploy anything, the bridge spins up an ephemeral Cloudflare Tunnel (`*.trycloudflare.com`) in front of the local port and syncs that `…/mcp` URL into the ChatGPT app on startup. (ngrok would solve the same reachability problem; Cloudflare's `cloudflared` is used because its quick tunnels need no account or auth token.)
+
+## Quick start
+
+**Prerequisites**
+
+- **macOS** — Chrome is launched from `/Applications/Google Chrome.app`, and clipboard/process helpers use `pbcopy`/`lsof`.
+- **Node.js ≥ 20** and **pnpm** (the repo pins `pnpm@10.14.0`).
+- **Google Chrome** — the bridge drives a real Chrome profile.
+- **`cloudflared`** *(optional, ChatGPT only)* — only needed for ChatGPT to call local MCP tools. Without it the TUI still runs. Install with `brew install cloudflared`.
+
+**Install & build**
+
+```bash
+git clone https://github.com/YosefHayim/ai-browser-bridge.git
+cd ai-browser-bridge
+pnpm install
+pnpm build
+```
+
+**Sign in once, then run (ChatGPT — default)**
+
+```bash
+node dist/bridge.js login
+node dist/bridge.js --repo /path/to/your/project
+```
+
+**Sign in once, then run (Gemini web)**
+
+```bash
+node dist/bridge.js login --provider gemini
+node dist/bridge.js --provider gemini --repo /path/to/your/project
+```
+
+Prefer a global `bridge` command? Run `pnpm link --global` after building, then use `bridge`, `bridge login`, `bridge ask "…"`, etc.
+
+**One-shot, non-interactive**
+
+```bash
+node dist/bridge.js ask "summarize @src/core/engine.ts" --repo /path/to/project
+node dist/bridge.js ask "hello" --provider gemini --repo /path/to/project
+```
+
+## Usage
+
+```text
+/help             list commands              /sessions         list local sessions
+/resume <query>   resume by number/title/id  /transcript       print the session transcript
+/new              start a new conversation   /export           export transcript (md/json/jsonl)
+/model [name]     show or switch the model    /permissions      show or switch MCP permission mode
+/rewind [text]    edit last prompt + regen   /checkpoints      list file checkpoints
+/stop             stop the active response   /restore <id>     restore files from a checkpoint
+/context          model-aware context est.   /status           repo/model/context/session status
+/diff             ask ChatGPT to read diff   /mcp              connector + exposed tools
+/task <request>   project-agent task (MCP)   /connector        (re)run ChatGPT connector setup
+```
+
+**File mentions** — reference repo files inline; they are resolved inside the repo and expanded before ChatGPT sees them:
+
+```text
+refactor the CLI input flow in @src/features/terminal/tui/App.tsx
+compare @src/features/store/fileResolver.ts with @src/features/store/fileResolver.test.ts
+```
+
+Paths that escape the repo root are skipped; files over 100 KB are summarized rather than inlined.
+
+## Agents & fan-out
+
+`bridge ask` is a stable, non-interactive surface for scripts and agents — it prints to stdout, never prompts in a pipe, and `--json` emits a machine-readable payload.
+
+```bash
+# one provider
+bridge ask --provider claude --json "summarize the tradeoffs of optimistic locking"
+
+# fan out across several free chats; one call, replies keyed by provider
+bridge ask --provider claude,deepseek,grok --json "same question, three models"
+# → { "claude": { "ok": true, "reply": "…", "elapsedMs": 8123 },
+#     "deepseek": { "ok": true, "reply": "…", "elapsedMs": 6210 },
+#     "grok": { "ok": false, "error": "…", "elapsedMs": 300000 } }
+```
+
+Fan-out is **partial-failure tolerant**: the run exits non-zero only when *every* provider fails, or — with `--strict` — when *any* fails. A one-time `bridge login --provider <name>` signs each provider in (an isolated Chrome profile per provider; your daily browser is untouched).
+
+The same fan-out core is exposed as an **outbound MCP `ask` tool** — launch it as a stdio MCP server with `bridge serve` and any MCP-capable agent can call `ask({ prompt, providers })` as a native tool instead of shelling out. Register it with Claude Code:
+
+```bash
+claude mcp add ai-browser-bridge -- bridge serve
+```
+
+…or add it to any MCP client config directly (the standard stdio-server shape):
+
+```jsonc
+{
+  "mcpServers": {
+    "ai-browser-bridge": { "command": "bridge", "args": ["serve"] }
+  }
+}
+```
+
+The `ask` tool takes `{ prompt, providers?, timeoutSeconds? }` and returns each provider's reply keyed by id (the same partial-failure-tolerant fan-out as `bridge ask`). Run `bridge login --provider <name>` once first, so the gateway has a signed-in session to drive. This is the opposite direction to the inbound MCP server, which exposes your repo tools *to* the web model.
+
+> Provider adapters other than ChatGPT/Gemini ship with best-effort selectors marked `LIVE-VERIFY` — confirm them against the live signed-in site before relying on them in production.
+
+## Where state lives
+
+All bridge state for a project is written **inside that project**, under `<repo>/.bridge/`:
+
+```text
+<repo>/.bridge/
+├── .gitignore        # a single "*", written automatically — see below
+├── config.json       # per-repo settings (includes `provider`: chatgpt | gemini)
+├── chrome-profile/   # signed-in ChatGPT session for this repo
+├── chrome-profile-gemini/  # signed-in Gemini session for this repo
+├── sessions/<id>/    # metadata.json + append-only events.jsonl transcript
+├── logs/<date>.jsonl # prompts, replies, and MCP tool-call summaries
+├── checkpoints/      # before/after snapshots around each apply_patch
+├── exports/          # /export output
+├── downloads/<conv>/ # attachment downloads (default when no --out given)
+└── screenshots/      # /screenshot and /ui-qa captures
+```
+
+On first use the bridge writes `.bridge/.gitignore` containing a single `*`. That makes git ignore **everything** in the directory — the session transcripts and the login cookies included — so none of it can be committed, even though it lives inside the repo. `git add -A` and `git add .bridge/` both skip it; only an explicit `git add -f` could override. The file is re-asserted on every run, so deleting or tampering with it heals automatically.
+
+> User-authored config meant to apply across **all** repos lives in your home directory: custom commands in `~/.ai-browser-bridge/commands/*.md` and user-level hooks in `~/.ai-browser-bridge/hooks.json`.
+
+### Migrating from `chatgpt-local-bridge`
+
+The package was renamed to **`ai-browser-bridge`**. Global user config moved from `~/.chatgpt-local-bridge/` to `~/.ai-browser-bridge/` — copy your `commands/` folder and `hooks.json` if you had them. Repo-local state stays at `<repo>/.bridge/` (unchanged). Re-run `/connector` or `bridge ask --tools` once so ChatGPT picks up the renamed MCP connector app.
+
+## Permissions & checkpoints
+
+```bash
+/permissions read-only   # grep_code, read_file, git_diff
+/permissions auto        # also the narrow write/test tools
+/permissions ask         # blocks write/test/process tools (interactive confirm pending)
+```
+
+`apply_patch` snapshots every touched path before and after the change. Recover with `/checkpoints`, `/restore <id>`, or `/rewind --files <id>`.
+
+## Testing
+
+```bash
+pnpm test          # vitest run
+pnpm typecheck     # tsc --noEmit
+pnpm verify:push   # biome ci + typecheck + test + build + check:class-api + check:tsdoc + check:boundaries
+```
+
+Coverage focuses on the safety-sensitive paths — sandbox validation, repo-local path resolution, the `.bridge/` self-ignore guard, session/checkpoint stores, permissions, and context counting.
+
+## Gemini web support
+
+The bridge can drive **gemini.google.com** from the terminal with the same Playwright/CDP pattern as ChatGPT:
+
+```bash
+bridge login --provider gemini
+bridge --provider gemini --repo /path/to/project
+bridge ask "explain this repo" --provider gemini --repo /path/to/project
+```
+
+**What works on Gemini web**
+
+- Terminal-driven prompts and captured replies
+- `@file` mention expansion (read-only repo context inlined into prompts)
+- Model detection/switching when the Gemini UI exposes a picker
+- Separate Chrome profile at `<repo>/.bridge/chrome-profile-gemini/`
+
+**What does not work on Gemini web (today)**
+
+- **MCP connector** — gemini.google.com has no custom connector UI like ChatGPT Settings → Connectors. The bridge skips the MCP server and Cloudflare tunnel when `--provider gemini`.
+- **`/task`, `/connector`, `/mcp`** — these require live MCP tools; use ChatGPT for those workflows.
+- **Attachment download** — `bridge download` is ChatGPT-only for now.
+
+For full MCP on Gemini, use the official [Gemini API Remote MCP](https://ai.google.dev/gemini-api/docs/function-calling) or [Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md) instead of the browser UI.
+
+**Selector maintenance:** when Google changes the Gemini web UI, fix selectors only in [`src/browser/gemini-page.ts`](src/browser/gemini-page.ts).
+
+## Limitations
+
+- **macOS-only** today (hardcoded Chrome path and `pbcopy`/`lsof` helpers).
+- ChatGPT and Gemini browser selectors can break when the web UI changes; fixes are localized to the browser layer.
+- Context usage is an **estimate** — the browser does not expose exact server-side token counts.
+- The Cloudflare Tunnel requires `cloudflared` installed.
+- Local-first by design; not a hosted multi-user service.
+- Hook command execution is parsed and reported but not yet executed (an allowlisted confirmation flow is pending).
+
+## License
+
+[MIT](LICENSE) © YosefHayim