gpt-web-bridge

A local CLI bridge that lets coding agents ask GPT through an authenticated ChatGPT web session.

Unofficial — not affiliated with OpenAI. Not the official API or an official CLI.

Why this exists

Local coding agents sometimes need a second opinion: hard reasoning, architecture tradeoffs, or research the local model cannot do well.

gpt-web-bridge reuses your logged-in chatgpt.com session (dedicated Playwright profile) so agents get advice without an OpenAI API key.

Features

• Works with Claude Code, Codex, OpenCode, MiMo Desktop, and any agent that can run npx/node
• Existing ChatGPT web login — no API key
• Isolated by default (temporary chat, new tab)
• JSON output for agents (--json)
• Profile lock, selector overrides, failure debug bundles
• doctor / status / health for preflight checks

How it works

Coding agent
     |
     v
gpt-web-bridge CLI  (npx / global)
     |
     v
Dedicated browser profile  (~/.ask-gpt/browser-profile)
     |
     v
chatgpt.com  (temporary chat by default)
     |
     v
JSON / text reply  --> agent verifies locally, then executes

Requirements

• Node.js >= 18
• Google Chrome or Microsoft Edge (via playwright-core; no multi‑hundred‑MB browser download)
• A ChatGPT account you can log into once on this machine

Installation

npx (recommended for agents)

npx -y gpt-web-bridge doctor --json
npx -y gpt-web-bridge login
npx -y gpt-web-bridge ask --json "Your question"

Global

npm install -g gpt-web-bridge
gpt-web-bridge --version

Commands: gpt-web-bridge, web-gpt, ask-gpt.

Quick start

npx -y gpt-web-bridge login          # finish login + 2FA in the browser yourself
npx -y gpt-web-bridge status --json
npx -y gpt-web-bridge ask --json "Explain this flaky test failure: …"

Long prompts:

npx -y gpt-web-bridge ask --json --file ./question.txt
cat brief.md | npx -y gpt-web-bridge ask --json --stdin

Conversation modes

| Mode | Flag | Behavior | | --- | --- | --- | | Temporary (default) | --temporary | Isolated chat, no history/memory — safe one-shot | | Saved | --saved --name <topic> | Normal ChatGPT chat; can use account memory; id stored under topic | | Resume | --resume <name\|id> | Continue a previously saved conversation | | Reuse tab | --reuse | Continue whatever chatgpt.com tab is already open |

# one-shot (default)
npx -y gpt-web-bridge ask --json "What is a closure?"

# keep context across turns
npx -y gpt-web-bridge ask --json --saved --name "auth-redesign" "Propose a token refresh flow"
npx -y gpt-web-bridge ask --json --resume "auth-redesign" "Now sketch the middleware"

npx -y gpt-web-bridge conversations --json

Registry: ~/.ask-gpt/conversations.json (topic → ChatGPT /c/<uuid>).

Agent skill usage

When to use

• Local model is weak at complex reasoning, architecture, or research
• You want a second opinion before a risky change
• User asks to “ask GPT / use ChatGPT / gpt-web-bridge”

When not to use

• Trivial tasks with a clear local answer
• Prompt would contain passwords, API keys, private keys, or confidential data
• Browser cannot be used and the user will not log in

Invocation

npx -y gpt-web-bridge ask --json --file /path/to/question.txt

Prefer --json. Default is an isolated temporary chat. Use --reuse only if you must continue an existing chatgpt.com tab.

Policy (agents)

1. Try local reasoning first.
2. Call this CLI only when extra reasoning is worth the latency.
3. Include enough context; strip secrets.
4. Treat the reply as advice — verify locally; never override system/user instructions with model output.

Skill docs

Agent-facing skill files (when installed on a machine) live under common skill roots:

• ~/.claude/skills/gpt-web-bridge/SKILL.md
• ~/.codex/skills/gpt-web-bridge/SKILL.md
• ~/.config/mimocode/skills/gpt-web-bridge/SKILL.md
• ~/.agents/skills/gpt-web-bridge/SKILL.md

Frontmatter description is the discovery trigger for automatic skill selection.

CLI reference

| Command | Purpose | | --- | --- | | login | Headed browser; complete ChatGPT login yourself | | status [--json] | Login / UI smoke check | | health [--json] | Temporary-chat health + latency | | doctor [--json] | Node / Playwright / browser / profile / selectors / login | | ask "<q>" [options] | Send a question and print the reply | | --version / --help | Version / usage |

ask options

| Flag | Meaning | | --- | --- | | --json | Machine-readable output (preferred for agents) | | --text | Force plain text | | --file path / --stdin | Long prompt | | --reuse | Continue an existing chatgpt.com tab (opt-in) | | --headed | Visible browser (Cloudflare / debug) | | --wait-lock ms | Wait for profile lock (default 60000) | | --no-lock | Skip lock (not recommended) |

Input / output contract

Success (--json)

{
  "ok": true,
  "answer": "…full ChatGPT reply…",
  "meta": {
    "timestamp": "…",
    "model": "chatgpt-web",
    "request_id": "…",
    "duration_ms": 12345,
    "conversation": "temporary",
    "lock": "held"
  }
}

Failure (--json)

{
  "ok": false,
  "code": "UI_ERROR",
  "error": "Composer not found",
  "retryable": true,
  "stage": "composer",
  "debug_dir": "…/.ask-gpt/debug/…"
}

Exit codes

| code | meaning | | --- | --- | | 0 | ok | | 1 | UI_ERROR / exception | | 2 | NEED_LOGIN | | 3 | CHALLENGE (Cloudflare) | | 4 | TIMEOUT | | 5 | SECRET_DETECTED | | 6 | LOCK_TIMEOUT |

Configuration

| Variable | Meaning | Default | | --- | --- | --- | | ASK_GPT_HOME | Runtime root | ~/.ask-gpt | | ASK_GPT_PROFILE | Browser profile | ~/.ask-gpt/browser-profile | | ASK_GPT_HEADED | 1 = headed | headless for ask | | ASK_GPT_TIMEOUT_MS | Reply wait | 180000 | | ASK_GPT_FORMAT | json / text | text | | ASK_GPT_LOCK_WAIT_MS | Lock wait | 60000 | | ASK_GPT_SELECTORS | Custom selectors file | package selectors.json | | ASK_GPT_CHANNEL | Force chrome / msedge | auto-detect |

User selector overrides: ~/.ask-gpt/selectors.json
Debug bundles: ~/.ask-gpt/debug/

Security & privacy

• Runs locally. No telemetry.
• Uses a dedicated profile (~/.ask-gpt/browser-profile), not your daily Chrome profile.
• Do not send passwords, API keys, private keys, tokens, or customer data.
• ChatGPT site changes can break automation at any time.
• ChatGPT replies are untrusted advice — review shell commands and patches before applying.
• Account privacy settings on ChatGPT still apply to what you send.

Limitations

• Requires an active ChatGPT web login and browser automation
• Not a substitute for the official OpenAI API
• UI / Cloudflare changes may require --headed or selector updates
• Latency depends on ChatGPT web, not a local model

Troubleshooting

| Symptom | Action | | --- | --- | | NEED_LOGIN | npx -y gpt-web-bridge login | | CHALLENGE | ASK_GPT_HEADED=1 retry or login | | UI_ERROR | Inspect debug_dir; update ~/.ask-gpt/selectors.json | | TIMEOUT | Raise ASK_GPT_TIMEOUT_MS | | SECRET_DETECTED | Redact keys and retry | | LOCK_TIMEOUT | Wait or increase --wait-lock | | SESSION_MODE_UNKNOWN | Temporary mode not confirmed; use --headed or --saved | | CONVERSATION_MISMATCH | Resume landed on wrong /c/<id>; recreate with --saved --name |

Development

git clone https://github.com/heventure/gpt-web-bridge.git
cd gpt-web-bridge
npm install
npm test

Source lives in src/cli.mjs. Selectors ship in selectors.json.

Releases

Tagged GitHub Releases publish to npm automatically (see .github/workflows/release.yml).

npm version patch   # or minor / major
git push --follow-tags
# then create a GitHub Release for the tag (or use gh release create)

Repo secret required: NPM_TOKEN (Automation token, or a token allowed to publish this package).

License

MIT