Usage

Prerequisites

  • macOS, Windows or Linux. The bridge finds Chrome in the usual install places; set AI_BROWSER_BRIDGE_CHROME_PATH to point it somewhere else. On Linux, /export copies with wl-copy, xclip or xsel, so install one of them.
  • Node.js 24.11 or newer and pnpm (the repo pins pnpm@10.14.0).
  • Google Chrome or Chrome for Testing: the bridge drives one shared bridge profile through a debug port. Sign in once in that bridge-launched window; every repo reuses it.
  • cloudflared (optional; ChatGPT, Claude, Grok): only needed for those providers to call local MCP tools. Without it the TUI still runs. Install with brew install cloudflared.

Install and build

git clone https://github.com/YosefHayim/ai-browser-bridge.git
cd ai-browser-bridge
pnpm install
pnpm build

Install the published CLI with npm install -g ai-browser-bridge; it also installs SKILL.md. From a source checkout, run pnpm build && pnpm link --global to get the bridge command, then use bridge, bridge chrome start, bridge ask "...", and so on.

Start Chrome, then run (ChatGPT, the default)

node dist/bridge.js chrome start
node dist/bridge.js --repo /path/to/your/project
node dist/bridge.js --debug-port 9223 --profile /path/to/chrome-profile

Start Chrome, then run (Gemini web)

node dist/bridge.js chrome start --provider gemini
node dist/bridge.js --provider gemini --repo /path/to/your/project

One-shot, non-interactive

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

Browser profile policy

Chrome 136+ no longer accepts remote debugging switches against the real default Chrome data directory. ai-browser-bridge therefore never launches Chrome on ~/Library/Application Support/Google/Chrome. By default it launches the browser on the debug port with one global bridge profile:

~/.ai-browser-bridge/chrome-profile

That profile is the browser-login SSOT for the bridge. Sign in once in the bridge-launched Chrome window, then bridge chrome start, bridge ask, and the TUI reuse that login from any repo or shell root.

For release and automation work, Chrome's team recommends Chrome for Testing. Install it separately, then point the bridge at that app while keeping the same shared profile:

AI_BROWSER_BRIDGE_CHROME_APP="Google Chrome for Testing" bridge chrome start

The app override changes only which Chrome build is launched. The profile remains ~/.ai-browser-bridge/chrome-profile; do not add per-repo Chrome profiles. See Chrome's remote-debugging profile change for the upstream reason.

Use your own Chrome instead

Chrome 144+ can share your everyday Chrome with local tools: open chrome://inspect/#remote-debugging and turn remote debugging on (Chrome guide). Then choose it:

export AI_BROWSER_BRIDGE_BROWSER=my-chrome

The bridge then never launches or quits Chrome. Each command connects to your running Chrome, opens its own tab, and closes that tab when it ends; it never types into a tab you opened. Chrome asks you to click Allow each time a command connects. bridge stop only ever closes a Chrome the bridge launched, and fan-out tasks with isolate still use their own isolated profile.

Interactive commands

/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 MCP connector setup
/conversations    list/search/open browser conversations

File mentions

Reference repo files inline; they are resolved inside the repo and expanded before ChatGPT sees them:

refactor the CLI input flow in @src/terminal/tui/shell/app.tsx
compare @src/store/file-mentions.ts with @src/store/file-mentions.test.ts

Paths that escape the repo root are skipped; files over 100 KB are summarized rather than inlined.

Conversation search

bridge chat search "query" --json opens ChatGPT's Search UI, selects Chats, and returns matching Conversations across titles and message content. It scrolls the result overlay up to --limit; add --open to navigate the browser to the best match.

Rate-safe Project organization

Prepare one ordered plan with Conversations for any number of Projects (Conversation ids are preferred because they can be verified exactly):

[
  { "conversation": "11111111-1111-4111-8111-111111111111", "project": "Yoga App" },
  { "conversation": "22222222-2222-4222-8222-222222222222", "project": "Invoices & Purchases" }
]

Then validate it and start the autonomous queue:

bridge chat organize --plan @organization-plan.json --dry-run
bridge chat organize --plan @organization-plan.json \
  --interval 60 --cooldown 600 --max-attempts 4

# No plan argument is needed after the queue exists
bridge chat organize status
bridge chat organize pause
bridge chat organize resume

The queue verifies every move from ChatGPT's loaded Project label, with the destination Project page as a fallback. Adaptive pacing starts from --interval 60 with jitter. After three successful moves it reduces the base interval by 20%, down to --min-interval 15; a ChatGPT "Too many requests" response increases the base interval by 50%, up to --max-interval 180, and waits for the --cooldown 600. The learned pace is persisted across pause/resume. Pass --no-adaptive for the old fixed/random interval behavior.

bridge chat organize pause writes a persisted pause request; an active queue finishes only its current UI operation, notices the request within one second of a delay, and releases its lock. bridge chat organize resume selects the latest queue, clears the pause marker, and reconstructs the original plan from persisted state. Use --queue <fingerprintOrPath> when more than one queue exists.

Rate limits and closed browser sessions do not consume move attempts. When pending work reaches zero, the queue automatically runs the orphan scanner to the stable end of ChatGPT history (eight unchanged bottom passes; it errors rather than returning a partial inventory). The final audit reports remaining intentional/unplanned orphans and any planned Conversation that is still loose; still-loose planned Conversations are automatically retried up to --max-attempts. Progress is persisted under .bridge/chat-organization-queues/, so an agent does not need to keep watching. Use --restart only to intentionally replay the full plan, and --no-verify only when the completion audit is intentionally unnecessary. --json keeps summaries on stdout and progress on stderr.