English · 简体中文

     

Website (screenshots & demo) · Chrome Web Store · Install from source · Issues

---

browsa (browser side panel AI) is a Chrome / Edge extension that opens a chat panel next to whatever tab you're on, reads the page you're viewing — article, video, or PDF — and hands it to your own agent or model. Plug in the local CLI agents you already use — Codex, Claude Code (subscription login — no separate model-API purchase needed) — or connect opencode, Hermes, or any OpenAI / Anthropic / Ollama-compatible endpoint. Your keys stay on your machine.

Highlights

1. Connect the agent you already use

However you use Codex / Claude Code in your terminal, that's how you use it in browsa — same subscription sign-in, same tool abilities (run commands, read/write files, web search), now with eyes on the browser: browsa feeds web content to the agent, tool execution streams live, and approval cards for dangerous actions appear right in the panel.

Agent	How to connect	Sign-in
Codex (OpenAI)	agent-bridge local daemon	ChatGPT Plus / Pro subscription login — no separate model-API purchase
Claude Code (Anthropic)	agent-bridge local daemon	Claude Pro subscription login — no separate model-API purchase
opencode	official headless server, direct	whatever model you configure it with
Hermes	self-hosted, /v1/runs protocol	self-hosted

One browsa card connects to several agents at once; the sidebar dropdown switches between them.

2. Reads the whole web — videos included

• Videos: subtitles or auto-transcription (ASR) → notes with clickable [mm:ss] timestamps; click one to jump straight back to the moment. Subtitle-less videos can be read visually too
• PDFs / papers: parsed entirely in-browser — tables, multi-column layout, and headings reconstructed; figure regions cropped out and sent to vision models
• Articles & messy pages: clean article text; feed-style pages read the page's own data directly (YouTube, Bilibili, 小红书…)

Full list under "What browsa reads" below.

Architecture

flowchart LR
    P["Current tab<br/>articles · videos · PDFs · messy pages"]
    B["browsa side panel<br/>read · chat · approvals"]
    subgraph Y["Your backends — local or self-hosted"]
        A1["Codex · Claude Code<br/>via agent-bridge · subscription login"]
        A2["opencode · Hermes<br/>official server, direct"]
        A3["Any LLM API<br/>OpenAI · Anthropic · Ollama…"]
    end
    P -->|"📎 attach: text / subtitles / tables / figures"| B
    B -->|"page content + your question"| Y
    Y -->|"streamed reply · tool progress · approvals"| B

Loading

Install

Chrome Web Store — easiest. Add browsa to Chrome. The store build updates itself; store review can lag a few days behind the GitHub build.

From source — newest features first.

1. Clone or download this repo (or grab the zip from Releases).
2. Open chrome://extensions (or edge://extensions) and enable Developer mode.
3. Click Load unpacked → select the browsa/ directory.

Then, either way:

1. Press Ctrl+Shift+H (or click the toolbar icon) — the panel opens next to any page.
2. Click ⚙ Settings and connect a provider below.

Build & package

npm install          # first time only
npm test             # run 1,000+ unit tests
npm run package      # → browsa-v<version>.zip

npm version patch|minor bumps the version in both package.json and manifest.json automatically.

Connect a provider

Open ⚙ Settings, fill in the address, hit Ping — connectivity is verified and capabilities auto-detected; the first provider you verify becomes active. Two kinds of backends:

• Agent providers — full agent backends with server-side tool execution (bash, file ops, web search…). The AI can actually do things.
• LLM providers — plain chat endpoints for conversation. Model ID required.

🔧 Agent Bridge — bridge local CLI agents (Codex, Claude Code…)

agent-bridge is a tiny standalone local daemon that adapts CLI agents (codex, claude) to one unified local HTTP protocol — a ChatGPT Plus / Claude Pro subscription login works as the model source — no separate model-API purchase needed:

npm i -g @xiaohuzai/agent-bridge                  # published on npm (Node 18+)
cp "$(npm root -g)/@xiaohuzai/agent-bridge/agents.example.json" agents.json
agent-bridge serve                                # one bridge per entry; ports live in agents.json

Open ⚙ Settings, select the Agent Bridge card, click ＋ Add agent and fill in bridge addresses one per row — one agent per address, with an optional alias (leave it empty and Ping discovers the agent's name automatically) and that bridge's own API key (keys can differ per bridge). The sidebar dropdown lists them as "Agent Bridge · codex", each with its own independent session thread. Approval cards for dangerous actions appear right in the panel; screenshots, pasted images, and PDF figures ride along with your message (≤8 per turn). Multi-turn context lives in the agent itself.

Don't want to run those three commands yourself? Click "Copy setup prompt" on the Agent Bridge card in settings and paste the whole block to your CLI agent — it performs the install, config, and launch for you (full text in the setup guide).

🔧 OpenCode Agent — connect the opencode CLI agent

opencode ships a first-party headless server — browsa connects to it directly (sessions, streaming, tool progress, and approval prompts for dangerous actions like shell commands). Browsa can connect to any opencode serve address — but bare opencode serve picks a random port that changes on every restart, so the set-and-forget move is to pin one:

opencode serve --port 4096

Open ⚙ Settings, select the OpenCode Agent provider, fill Base URL http://127.0.0.1:4096 (the placeholder suggests it), Ping, done. Multi-turn context lives in the opencode session; browsa just sends your turns. When opencode asks to run a dangerous command, the approval card appears right in the panel. Works from any directory — start the server in the project you want it to work on.

🤖 Hermes Agent — self-hosted agent with built-in tools

Hermes is a self-hosted AI agent with built-in tools (web search, terminal, file ops, memory, skills). browsa uses its /v1/runs API — richer than plain chat completions (tool progress, approval/clarification prompts for dangerous actions) — with a stable X-Hermes-Session-Id per conversation so Hermes can maintain session continuity server-side. Falls back to plain /v1/chat/completions automatically if a Hermes deployment doesn't advertise /v1/runs support.

1. Install Hermes

pip install hermes-agent   # or follow the official install guide

2. Enable the API server — add to ~/.hermes/.env:

API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key

3. Start Hermes

hermes gateway
# → [API Server] API server listening on http://127.0.0.1:8642

4. Configure browsa — open ⚙ Settings, select the Hermes Agent provider. It only needs a Base URL and API key — its own /v1/runs protocol is used automatically (no API-type dropdown).

Field	Value
Base URL	http://<server-ip>:8642
API Key	value of API_SERVER_KEY

5. Ping to verify. /v1/runs support is auto-detected and enabled automatically.

💬 LLM providers — OpenAI · Anthropic · Ollama · Groq · LiteLLM · any compatible endpoint

Any endpoint that speaks OpenAI Chat Completions (/v1/chat/completions), OpenAI Responses (/v1/responses), or Anthropic Messages (/v1/messages).

Open ⚙ Settings → LLM Providers. An empty LLM 1 slot is reserved for you — fill it in and hit Save, or use ＋ Add Provider anytime:

Field	Value
Alias	a name you choose (e.g. "My OpenAI", "本地模型") — shown in the sidebar dropdown so multiple providers stay distinguishable
Base URL	e.g. https://api.openai.com
API Key	your API key
Model ID	e.g. gpt-4o, claude-sonnet-4-6 (required) — comma-separate multiple models and the sidebar dropdown expands to one "Alias · model" entry each
API	the protocol this endpoint speaks: Chat Completions / Responses / Anthropic

Add as many LLM providers as you like; each picks its own protocol and carries its own alias. A single card can also carry several Model IDs — one card covers an entire gateway hosting dozens of models. Use the ✕ on a card to remove it (the built-in agent cards — Hermes, OpenCode, Agent Bridge — are fixed and not removable).

What browsa reads

Click 📎 to attach the current tab — Auto mode (clean article text, falling back to DOM tree, then full page text) or 📷 Screenshot mode (the visible tab, for multimodal models). Attaching a PDF — or a page that turns out to be one — is automatic; no mode to pick.

You're reading	What browsa sends
Articles & docs	clean article text; the site's llms.txt instructions folded into the context
PDFs & papers	full layout — tables, headings, columns — parsed in-browser; figure regions cropped and sent as images to vision models (compacted to labeled placeholders in history after answering)
Videos	transcript with clickable [mm:ss] timestamps; subtitle-less videos auto-transcribed (ASR, optional — Volcengine Ark key in Settings) or visually analyzed together with the speech
GitHub file pages	raw source from raw.githubusercontent.com — markdown and code keep their structure
Feishu / Lark docs	the page's editor block structure parsed directly — headings, lists, and table rows & columns survive
Anything messy	the page's own network requests observed and read directly — subtitles, comments, article source (YouTube, Bilibili, 小红书, and more)

Highlight text on a page and the floating toolbar appears: Explain and Translate answer inline — a streaming card right next to the selection, no panel needed — while Ask and Summarize (and the right-click menu) ride into the panel. No need to click 📎.

Features

The full reference lives here:

Chat — streaming, thinking blocks, diagrams, follow-up…

Feature	What you get
Streaming replies	tokens appear as they arrive; click ✕ or press Esc to stop
Think blocks	<think> / <thinking> content in a collapsible block, auto-collapsed after streaming
Markdown & highlighting	full GFM (tables, code blocks, lists); 40+ languages via highlight.js; diff blocks color + green / - red
LaTeX	inline $...$ and display $$...$$ via KaTeX — formula-heavy messages offloaded to a Web Worker so the panel doesn't jank
Mermaid · ECharts · Markmap	```mermaid / ```echarts / ```markmap code blocks render inline, each with a zoom / copy / export-SVG toolbar; just ask for a chart or mind map — the model knows the format. If a Mermaid block fails to parse, one click sends it back to your model for a fix — the repaired diagram is validated locally before it replaces the broken one
Follow-up ("追问")	select any text inside a reply to open a scoped side-conversation about just that excerpt, without touching the main history; fully resizable
Outline rail	from 4 turns on, a quiet tick rail tracks the conversation — click to jump, hover to preview
Edit & resend · Regenerate	✏ edits and resends any user message; ⟳ re-runs any assistant reply
Queued follow-ups	typing while a reply streams queues your message; it sends automatically once the stream ends
Error cards	provider errors classified into plain language (auth / rate-limit / timeout / network / 5xx), raw error expandable and copyable
Copy & timestamps	⎘ copies the full raw Markdown; hover any message to see its send time
Reply source labels	every reply is stamped with the provider / agent that produced it (same name as the sidebar dropdown); switching to an agent asks whether to carry the conversation over as its first message or start a new session (sending without choosing continues without context)

History & sessions — drawers, search, export…

Feature	What you get
Sessions	save the conversation as a named session; browse and restore from the 🕐 drawer; pin favorites above the list
Search everywhere	Ctrl+F across all messages in a conversation; the drawer filters sessions by title and message content (content-only hits flagged)
Export	any session as a Markdown file
Safe deletion	two-step armed delete for sessions; multi-select messages for batch deletion; clearing history is undoable for 5 seconds

Input — images, drafts, quick actions…

Feature	What you get
Image attachments	drag-and-drop or paste images into the composer (for multimodal models)
Input history & drafts	↑/↓ recalls previously sent messages; an unsent draft survives closing the panel
Slash commands	type / for completions — see the table below
Quick actions	one-click Summarize / Key Points / Explain / → 中文 / Outline above the composer
Selection toolbar & context menu	highlight text on any page: Ask · Explain · → 中文 · Summarize — Explain / Translate answer inline (streaming, in place); Ask / Summarize and the right-click menu go to the panel

Settings — system prompt, languages, llms.txt, auto-summarize…

Setting	What it does
System prompt	prepended to every conversation as role: system — set reply language, tone, and format rules here
Reply language	force replies in a specific language regardless of page language
UI language	English, 中文, or Auto (follows the browser) — applies immediately, no reload
Selection toolbar & llms.txt	toggle the floating toolbar on text selection; on 📎, the site's LLM instructions are fetched once and baked into the attached page context — kept out of the system prompt so the prompt prefix stays byte-stable across turns (prompt-cache friendly)
Reading preferences	message font size, send shortcut (Enter / Shift+Enter), thinking-block auto-collapse
ASR	the speech-to-text provider for subtitle-less videos (Volcengine Ark by default): API key, language, subtitle source
Auto-summarize long attachments	automatic — pages or transcripts over the threshold (default 100,000 chars) are chunked, summarized in parallel, and merged in the background; [mm:ss] markers are preserved so seek links keep working; any error fails open to the original text
Deep extract	on by default — before attaching, browsa expands collapsed sections and pages through paginated content so far more of the page reaches the model

Slash commands

Type / in the composer to see autocomplete. All commands accept extra instructions — /summarize focus on the methodology:

Command	Prompt sent to the model
/summarize	3–5 bullet summary
/translate	Translate to Chinese
/rewrite	More concise rewrite, keeping all facts
/explain	Explain for a beginner in simple language
/outline	Nested outline of headings only
/keypoints	Top 5 takeaways
/prompt	Show the current active system prompt (not sent to the model)

Keyboard shortcuts

Shortcut	Action
Ctrl+Shift+H	Open / close side panel
Enter	Send message (configurable in Settings)
Shift+Enter	New line
Ctrl+K	Clear history (with undo)
Ctrl+/	Cycle context mode (Auto ↔ Screenshot)
Ctrl+F	Open in-conversation search
Esc	Cancel stream / close search / close drawer

How it works

Code map

• background.js — MV3 service worker, single message router; streaming via per-turn ports, auto-summarize for oversized attachments.
• sidepanel.js — chat UI orchestrator; rendering (Markdown/Mermaid/Markmap/KaTeX/ECharts), sessions, search, follow-up each live in lib/sidepanel/.
• lib/ — page extraction (Readability cascade + XHR interception), SSE streaming clients (/v1/chat/completions, Hermes /v1/runs, the opencode / agent-bridge agent clients), chrome.storage.local wrapper, content scripts.

Browser compatibility

Chrome / Edge 116+ (primary target); Brave 1.56+ should work (same Chromium surface). Firefox is not supported (no side_panel API).

Security

• API keys are stored in chrome.storage.local on your machine only — never sent anywhere except your configured baseUrl.
• Before page context is sent to your provider, every URL in it is masked locally: credentials hiding in query strings, userinfo, or fragments (tokens, passwords, signatures, session IDs) never leave your machine. URLs browsa itself fetches (media, images) are untouched.
• PDFs are parsed entirely client-side (WASM + pdf.js) — the file's bytes never leave your device; only extracted text goes to your provider.
• LLM replies are sanitized with DOMPurify before rendering (blocks data:image/svg+xml sources; Mermaid's SVG output is stripped of <script> / event-handler attributes).
• Content scripts only observe network requests; they never modify or block them.

License

MIT — free to use, modify, and distribute.

---

_{browsa — read anywhere, ask anywhere.}