docs(browser): document where to find bridge.json on the host#48
Conversation
The persistent bridge state file (port + token) had only a terse inline mention. Add a dedicated "The bridge state file (bridge.json)" section to docs/browser.md with the exact per-OS path (macOS / Linux / Windows, incl. defaults), the file's JSON shape, the 0600/0700 perms, read-it commands (sh + PowerShell), how to reset the token, explicit-token precedence, and the legacy temp-dir fallback. Cross-link it from the token-sharing bullet, the troubleshooting "no token set" row, and the package README. Docs only; no version bump. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation in docs/browser.md and packages/opencode-browser/README.md to detail how the bridge port and token are persisted in the bridge.json state file across macOS, Linux, and Windows. It adds a new section explaining the file's location, structure, and usage, as well as how to retrieve or reset the token. There are no review comments, and I have no feedback to provide.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 04455c8916
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - **Reset the token.** Delete `bridge.json` (or set an explicit `token` / `OCB_TOKEN`). The next | ||
| launch generates a fresh token, rewrites the file, and logs it once as `browser_bridge_token` — | ||
| re-paste it into the extension dashboard. |
There was a problem hiding this comment.
For upgraded installs that still have $TMPDIR/opencode-browser-bridge.json / %TEMP%\opencode-browser-bridge.json, deleting only the new bridge.json does not reset the token: readBridgeFile() falls back to the legacy file when the persistent file is missing, then writes that old token back to the new path. Users following this reset advice after an upgrade will keep reusing the old secret instead of getting a fresh one, so the instructions should also tell them to delete the legacy temp file or set an explicit token.
Useful? React with 👍 / 👎.
| - **Explicit token wins.** An explicit `token` (plugin option) / `OCB_TOKEN` (MCP) overrides | ||
| whatever is in the file; it's still written back so other adapters on the host converge on it. |
There was a problem hiding this comment.
When an adapter is already hosting with a different token, setting token/OCB_TOKEN in a new adapter does not make everyone converge: the new adapter writes the new token to bridge.json before election, then connects as a guest with that token while the existing broker still validates against its in-memory token and closes the handshake. This can leave all subsequent adapters that read the file unable to join until the old host is restarted, so the docs should say to stop/restart the current host rather than implying a live override.
Useful? React with 👍 / 👎.
1 participant
What
Documents where to find
bridge.jsonon the host — the per-user file the plugin and MCP server use to persist the bridge port + token across sessions. It previously had only a one-line inline mention.docs/browser.md— new "The bridge state file (bridge.json)" section~/Library/Application Support/opencode-browser/bridge.json$XDG_STATE_HOME/opencode-browser/bridge.json(default~/.local/state/...)%APPDATA%\opencode-browser\bridge.json(default%USERPROFILE%\AppData\Roaming\...){ "port", "token" }), the0600/0700permissions.catfor macOS/Linux,Get-Contentfor PowerShell) so you can grab the token without digging through the log.$TMPDIR/opencode-browser-bridge.json) that older builds used — the reason the token used to change on reboot.Cross-links
Wired the new section into the token-sharing bullet, the troubleshooting "no token set" row, and the package
README.md(which also gets a short three-path summary).Verification
### The bridge state file (\bridge.json`)→ all#the-bridge-state-file-bridgejsonlinks match; README../../docs/browser.md` target resolves.pnpm lint+pnpm format:check→ clean.Docs only; no behavior change, no version bump.
🤖 Generated with Claude Code