browser-fetch-router
Shared browser and web-fetch router CLI for coding agents
Open source Open in the app JSON README (API)
About
Shared browser and web-fetch router CLI for coding agents
Details
- Kind
- Plugins
- Topic
- Developer tools
- Publisher
- seungpyoson
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.1.0
- Last push
- 2026-08-01T07:19:04Z
- Repository state
- ativo
- Language
- Python
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
seungpyoson/browser-fetch-router
README
# Browser Fetch Router
`browser-fetch-router` is a shared, policy-aware browser and web-fetch CLI for
coding agents. It centralizes provider routing, URL safety, approvals, caching,
cost controls, audit logging, and lifecycle cleanup so individual agents do not
reimplement those rules.
## Install
```bash
python3 -m pip install .
browser-fetch-router --help
```
The package exposes these entry points:
- `browser-fetch-router`
- `read-web`
- `read-user-tabs`
- `interactive-browser`
## Agent Usage
Each agent invocation should set:
- `BFR_AGENT=<agent-name>`
- `BFR_SESSION_ID=<uuid-or-ulid>`
Then call the shared CLI:
```bash
browser-fetch-router read-web <url> --json
browser-fetch-router read-web <url> --allow-jina-auth --json
browser-fetch-router read-web https://example.com --json
browser-fetch-router read-user-tabs list --json
browser-fetch-router interactive-browser "open example.com and summarize visible text" --json
```
### read-web Provider Credential
Generic public pages use Jina Reader. The default is anonymous: ambient
`JINA_API_KEY` presence alone never authorizes use, and the anonymous path does
not read or validate it. Retry an anonymous `jina_auth_required` result with
`--allow-jina-auth` when authenticated Reader access is intended.
Authenticated Jina may consume free or prepaid account tokens.
`--allow-paid` controls only a new Parallel fallback; it never authorizes Jina
authentication. An adapter must not read or embed the credential. Credential
retrieval, validation, request construction, caching, and rate limiting stay in
the shared CLI.
`browser-fetch-router doctor --json` reports only the local state
`missing`, `malformed`, or `configured`, plus that authenticated opt-in is
required. It does not make a Reader request or claim that the remote service
accepted the credential.
### read-user-tabs CDP Setup
`read-user-tabs` reads from a loopback Chrome CDP endpoint at
`http://127.0.0.1:9222`. Start a separate temporary profile. Do not use the
normal browser profile for CDP. The required flags are
`--remote-debugging-address=127.0.0.1 --remote-debugging-port=9222 --user-data-dir=<temporary-profile>`.
The managed setup helper prints the safe path, and `--launch` starts the
temporary loopback profile:
```bash
browser-fetch-router read-user-tabs setup --json
browser-fetch-router read-user-tabs setup --launch --start-url https://example.com --json
```
```bash
BFR_TMPDIR="${TMPDIR:-/tmp}"
BFR_CDP_PROFILE="$(mktemp -d "${BFR_TMPDIR%/}/bfr-cdp-profile.XXXXXX")"
# macOS:
export CHROME_BIN="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
# Linux:
# export CHROME_BIN="$(command -v google-chrome || command -v chromium || command -v chromium-browser)"
"$CHROME_BIN" \
--remote-debugging-address=127.0.0.1 \
--remote-debugging-port=9222 \
--user-data-dir="$BFR_CDP_PROFILE" \
--no-first-run \
--no-default-browser-check
```
### interactive-browser Providers
- `--provider cloud` is live when `BROWSER_USE_API_KEY` is present and
`--allow-hosted-browser` is supplied.
- `--provider browserbase` is live when `BROWSERBASE_API_KEY` is present and
`--allow-hosted-browser` is supplied. If your Browserbase account requires a
project id, also set `BROWSERBASE_PROJECT_ID`.
- Local interactive mode is not advertised as a daily-use provider in this
build because it would require additional model/provider credentials.
## Agent Adapter Install
Install thin agent adapters with the shared CLI:
```bash
browser-fetch-router install-agent --all --json
browser-fetch-router install-agent pi --json
browser-fetch-router install-agent --select codex,gemini,opencode --json
```
The supported/default agent matrix, Pi migration note, Kimi inheritance caveat,
environment override behavior, and `--adapter-path` rules are documented in
[`docs/browser-fetch-router-install-agent-contract.md`](docs/browser-fetch-router-install-agent-contract.md).
To prove an external global command is not stale, capture its path before
activating or prepending the reviewed candidate environment. Then run the
candidate verifier against that absolute target:
```bash
checkout_root="/absolute/path/to/reviewed-browser-fetch-router"
cd "$checkout_root"
external_bfr_shim="$(command -v browser-fetch-router)"
python3 -m browser_fetch_router doctor --global-install --global-shim "$external_bfr_shim" --json
```
The verifier reports candidate and target identities, package roots, schema
defaults, the target's `read-web --help` capability, and doctor health. It
rejects self-verification. If the external command does not match this
package's expected contract it returns `stale_global_install` with a
`pipx install --force "$checkout_root"` reinstall instruction using the
reviewed checkout's captured absolute path.
## Tests
```bash
python3 -m pytest tests/browser_fetch_router
```
For contributor readiness, also verify package installability from outside the
repository:
```bash
python3 -m pip install <checkout-path>
browser-fetch-router --help
```
Generated virtualenvs, caches, bytecode, and package metadata are ignored by the
repository. Keep `git status --short` clean after running the documented flow.