Searches Google in the Chrome you already have, reads the best results and returns clean Markdown inside a hard token budget. An MCP server for your local agent and a zero-dependency Node.js library. No API keys, no cloud.
Replay: a local agent asks how backpressure works in Node.js streams and calls the web_search tool. tiny-browse searches Google in a headless Chrome, reads the results page three ways and votes, opens the top result, drops its navigation, cookie banner, sidebar and footer, and returns 1,343 tokens of Markdown instead of 68,928 tokens of HTML. The local agent answers and cites nodejs.org.
local agent · web_search
01 your local agent
How does backpressure work in Node.js streams? Cite the docs.
Backpressure is data building up behind a buffer when the receiver is slower than the source. In Node.js streams, write() returns false when the buffer is full: stop writing and wait for the drain event. nodejs.org
There is a general problem that occurs during data handling called backpressure and describes a buildup of data behind a buffer during data transfer.
## How Does Backpressure Resolve These Issues?
In Node.js, there is an internal built-in function called .pipe() …
_[Showing the sections most relevant to the query]_
Markdown to the model1,343 tokens
max_tokens 1,500−98.1%
ask
search
read
fit
answer
replay · token counts measured with tiny-browse on nodejs.org
Works with every MCP client, and with plain Node.js
Claude CodeClaude DesktopGitHub CopilotCursorWindsurfGemini CLIClineCodexYour own agentClaude CodeClaude DesktopGitHub CopilotCursorWindsurfGemini CLIClineCodexYour own agent
One tool call from your local agent. Four steps. Only the answer comes back.
Everything runs on your machine, in a Chrome profile of its own, without your cookies.
google.com/search?q=…
✓ layout ✓ a11y ✓ selectors
→ 5 results, merged by vote
01
Search
Google loads in your Chrome. The results page is read three independent ways and merged by vote. DuckDuckGo and Bing take over when Google refuses.
GET nodejs.org/en/learn/…
render: http 24 ms
render: browser (only if needed)
02
Read
Each page is fetched over plain HTTP and rendered with scripts off. Pages that need JavaScript get a full Chrome load. The faster way is remembered per site.
– navigation
– cookie banner
+ headings, code, tables, lists
03
Extract
The main content is found from how the page is laid out, not from class names. Menus, ads, cookie banners and hidden text are dropped.
68,928 tokens of HTML
→ 1,343 tokens of Markdown
cursor: continue later
04
Fit
The page is split into sections by heading and packed into max_tokens, keeping the sections most relevant to the query. A cursor reads the rest.
Small on disk. Careful on the web. Exact about tokens.
$ npm pack --dry-run
name: @shubhamcodess/tiny-browse
package size: 126.6 kB
total files: 7
"dependencies": {}
no bundled browser · no API keys · no LLM inside
126 kB, zero dependencies
One package, nothing else installed. It drives the Chrome, Edge, Brave or Chromium already on your computer instead of downloading a browser of its own.
$ tiny-browse doctor
[ok] node >= 22
[ok] browser - Google Chrome
also found: Microsoft Edge
[ok] chrome session - 809 ms
Your browser, found for you
Detects your browser, starts it headless in a profile of its own and stops it when you are done.
max_tokens: 1500
1,343 tokens · truncated: true
cursor: "eyJ1cmwiOi…" → read the rest
A hard token budget
max_tokens is a limit, not a hint. focus keeps the relevant sections; cursor continues a long page.
✓ layout✓ accessibility tree✓ selectors
→ merged by vote: 5 results
google → duckduckgo → bing, when an engine refuses or runs out of budget
Survives search page redesigns
Results are parsed three independent ways and merged by vote, so one changed class name rarely breaks search. Fallback engines take over automatically.
google 3/min · 20/h · 100/day
CAPTCHA → pause 15 min, 1 h, 4 h
GET http://192.168.1.1
× private_address: refused
cookies: none · profile: its own
Careful by default
Strict search budgets shared by every process, no private-network access, pages read without your cookies. Bot checks are reported, never bypassed.
There is a general problem that occurs during data handling…
<!-- end untrusted content -->
Web text is labelled as web text
Every page arrives wrapped in markers with its URL, so your local agent can tell content from instructions and cite its source. Structured results ride along for MCP clients that support them.
For local agents that need the web, and code that needs it too
The same engine behind two doors: MCP tools for your local agent, functions for your Node.js code.
Web search for local agents
A local agent on a local model has no web access. Add tiny-browse as an MCP server and it can search and read pages: no API keys, no cloud service.
claude mcp add tiny-browse -- npx -y @shubhamcodess/tiny-browse mcp
Answers grounded in sources
Every page comes back with its URL and only its relevant sections, so an assistant answers from current pages and cites them instead of guessing.
web_search { "query": "…", "read": 3 }
Current docs for local coding agents
Libraries change after a model’s training cutoff. web_fetch with focus pulls just the part of the docs your local agent needs, code blocks intact.
import { webFetch, webSearch } from"@shubhamcodess/tiny-browse";
// 1. A known reference page: plain HTTP, no Chrome, no search budgetconst r = await webFetch(
{ urls: ["https://kubernetes.io/docs/reference/kubectl/quick-reference/"], max_tokens: 30000 },
{ mode: "http", timeoutMs: 15_000 },
);
// 2. Otherwise one search, reading the top 2 results, sharing a warm Chrome if one runsconst s = await webSearch(
{ query: "kubectl rollout history command", read: 2, max_tokens: 3000 },
{ timeoutMs: 15_000, useServer: "auto" },
);
// a "blocked" error is never retried: whatcmd pauses its searches for 15 minutes
abridged from whatcmd/src/browse.ts
Set it up in a minute
Install, check your browser, add one line to your local agent.
Install with npm install -g @shubhamcodess/tiny-browse, or skip it: your local agent can run it with npx.
Check with tiny-browse doctor. It finds your browser and starts it once.
Connect your local agent. tiny-browse config <client> prints the exact snippet.
Ask something current. Your local agent gets web_search and web_fetch.
Requires Node.js 22+ and Chrome, Chromium, Edge or Brave. No browser? Use --no-chrome.
import { webSearch } from"@shubhamcodess/tiny-browse";
const { results, pages, markdown } = await webSearch({
query: "node.js stream backpressure",
read: 2, // open and read the top 2 results
max_tokens: 4000, // hard limit on the whole answer
});
for (const r of results) console.log(r.rank, r.title, r.url);
A web search and page reading tool for local AI agents and Node.js, built for agents that run on your own machine. It searches Google in the Chrome you already have, reads the best results and returns clean Markdown inside a hard token budget. It ships as one npm package that is both an MCP server (tools web_search and web_fetch) and a library (webSearch, webFetch, createClient).
Do I need an API key or an account?
No. There is no search API and no cloud service involved. tiny-browse drives a browser on your own computer, so nothing is billed and no key is needed.
Which local agents does it work with?
Any MCP client: Claude Code, Claude Desktop, GitHub Copilot in VS Code, Cursor, Windsurf, Codex, Gemini CLI, Cline and local agents you build yourself, on any model: Ollama and other local models included. tiny-browse config <client> prints the setup for claude-code, claude-desktop, cursor, vscode, codex or generic.
Does it download a browser?
No. It uses an installed Chrome, Chromium, Edge or Brave, in a separate profile of its own, never your everyday profile. Without any browser, the no-Chrome mode (--no-chrome, or mode: "http" in the library) reads pages over plain HTTP; Google is skipped and pages that need JavaScript come back thin.
Will Google block it?
It can, depending on your network. tiny-browse keeps strict request budgets (for Google: 3 a minute, 20 an hour, 100 a day, shared by every tiny-browse process on the computer) and pauses an engine after a CAPTCHA, while DuckDuckGo and Bing take over. Running tiny-browse login once usually helps. Reading pages is not affected.
How does max_tokens work?
It is a hard limit on the whole answer, counted with a model-agnostic estimate. Pages are split into sections by heading and packed in order of relevance to the query (or to focus). When a page is cut short, the result includes a cursor that continues it.
Can I use it from my own code, without MCP?
Yes. npm install @shubhamcodess/tiny-browse, then import webSearch and webFetch. Each call starts what it needs and shuts it down before it returns, so a short-lived CLI exits straight away; createClient() keeps one Chrome warm across calls. whatcmd uses it exactly this way.
What errors can it throw?
Every error is a TinyBrowseError with a code: chrome_not_found, timeout, blocked, network, private_address, aborted or invalid_input. An empty result list is not an error, and webFetch only throws when no page at all could be read; partial failures are listed in failed. The docs show how to handle each code.
Is it safe to point my local agent at the open web?
tiny-browse refuses local and private network addresses, including requests made by pages inside Chrome, reads pages without your cookies, and wraps every page in untrusted-content markers so your local agent can tell web text from instructions. The HTTP server binds to 127.0.0.1 and requires a token for anything else.
Does it read PDFs or work on Windows?
Not yet. PDF support is not implemented, and it is tested on macOS and Linux only; Windows is untested.
Built in the open
One maintainer, MIT licence, issues read by a human.
Shubham Prakash
Full Stack Developer · AI
maker of tiny-browse and whatcmd
Built so a local agent can read the web without a cloud API or a 300 MB browser download.