Usage
Prerequisites
- macOS, Windows or Linux. The bridge finds Chrome in the usual install places; set
AI_BROWSER_BRIDGE_CHROME_PATHto point it somewhere else. On Linux,/exportcopies withwl-copy,xcliporxsel, 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 withbrew 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.