browser-search: a three-tool skill that gives AI agents a search, browse and bypass chain

The gap browser-search is aimed at: agents that search but cannot read

An agent with a search API can find URLs. It often cannot open them. The README frames this bluntly, comparing a browsing agent to a thief in a balaclava walking into a police academy: protections block it, challenge it, reject it. The stated fix is to stop treating the agent as an intruder and give it tools that clear the door.

The target user is narrow and identifiable. You are running an agent framework that supports skills or instruction files, OpenCode, Claude Code, Cursor or OpenClaw are named, and you want web access without buying a search API subscription or a scraping service. The README's pitch is zero cost, unlimited usage, everything on your own machine. That is a self-hosting pitch, not a convenience pitch, and it should be read that way.

The secondary claim is about hallucination. The README says the skill enforces exclusive use of deterministic scripts, so the model cannot get the command wrong or misinterpret the output. That is really a claim about interface design: give the model a fixed command surface and a fixed output shape, and there is less room for it to invent an answer. Whether that eliminates hallucination is a much larger claim than whether it reduces command-level errors.

Three tools, one escalation ladder, and where the control actually sits

The architecture is a pipeline with a fallback. SearXNG is the metasearch layer, described as multi-source and returning JSON, and it handles the search phase in milliseconds according to the README. Camofox is a browser exposed through a REST API, used for what the README calls the roughly 90% of standard sites. CloakBrowser is the stealth browser, invoked when a site is protected.

The flow the README gives is: search with SearXNG, browse the results with Camofox, escalate to CloakBrowser if the site is protected. The escalation is described as automatic, with the agent choosing the tool and zero human intervention. CloakBrowser's role is specific: the README says it detects Cloudflare, Akamai, DataDome, Imperva, PerimeterX and DDoS-Guard challenges and waits for them to resolve before extracting content.

The division of labour is the interesting part. Search is cheap and fast, browsing is heavier, and stealth browsing is heaviest. By routing only protected sites to CloakBrowser, the skill avoids paying the stealth cost on every request. That is a sensible design, and it is also where the weakest link lives: the decision to escalate depends on Camofox correctly reporting that it was blocked. If Camofox returns a partial page instead of an error, the agent may never escalate, and the failure is silent rather than loud.

Installation: npx skills add, Docker for SearXNG, and the version pins that matter

The README does not reproduce a full command transcript in the portion available here, so the exact install sequence should be read from the repository itself. What the material does establish is the shape of setup. The skill is installed through npx skills add, which is the command named in the v3.1.1 release note. Node.js 20 or newer is required, per the badge in the README.

SearXNG and the browser components run through Docker and npm, according to the README's benefits section. SearXNG needs to be reachable and configured to return JSON, since the skill's search phase depends on that output format. Camofox needs its REST API listening. CloakBrowser is the component with the most fragile dependency chain: v3.1.0 updated CloakBrowser to 0.5.5 and Playwright Core to 1.62.1, and v3.1.1 was released the same day as the repository's last push to fix CloakBrowser setup after npx skills add.

That release history is the most useful signal in the material. A setup bug that survived into a patch release means the install path is the part most likely to break on your machine. If you are evaluating this, run the install and confirm CloakBrowser launches before you touch the SKILL.md. The README also notes that SKILL.md is plain text and editable, which is the intended customization point, so the skill is not a sealed package.

The anti-bot claims are the ones to verify, not the ones to repeat

The README states that CloakBrowser applies 58 C++ source-level patches and scores 0.9 on reCAPTCHA v3, described as human-level and server-verified, clearing Cloudflare, Turnstile, DataDome, Akamai, Imperva, PerimeterX and DDoS-Guard. Those numbers come from the project's own documentation. Nothing in the supplied material shows how the score was measured, on what date, against which challenge configuration, or whether it holds across regions and IP ranges.

This matters because anti-bot detection is adversarial and moves. A score measured at one point says little about behaviour six months later, and the README itself treats the tool set as replaceable, saying that when better tools emerge, updating SKILL.md is all it takes to swap them in. That is an honest admission that the bypass layer has a shorter shelf life than the orchestration layer.

There is also a policy question the README does not address. A stealth browser that waits out Cloudflare and DataDome challenges is, by design, defeating controls a site operator chose to deploy. The README presents this as walking through doors rather than sneaking, which is a framing choice, not an argument. If your use case involves sites whose terms prohibit automated access, the tooling makes that easier to do and does not make it permissible. That judgement sits with you, not with the skill file.

What browser-search is not: a hosted service, and not a drop-in for a search API

The obvious alternative for many teams is a hosted search API plus a managed scraping or browser service. The difference is not subtle. A hosted search API gives you an endpoint, a key, a quota and someone to call when it breaks. browser-search gives you three services to run, no quota and no one to call. The README's framing of zero cost and unlimited usage is accurate in the sense that nothing is metered, but the cost moves to operations: Docker containers to keep alive, a SearXNG instance to configure, and a stealth browser whose dependencies shift under you.

For a single developer on a workstation, that trade is often good. For a team that needs predictable throughput and an incident response path, running your own SearXNG and Camofox instances means you own the failure modes. The README's claim that it was built and tested on a Raspberry Pi is a statement about resource footprint, and it suggests low hardware requirements, but it says nothing about concurrent load or sustained operation.

There is also a category difference. A search API returns ranked results and stops. browser-search continues into the page, extracts content, and escalates when blocked. If your agent only needs titles and snippets, the browsing and stealth layers are dead weight you are still maintaining.

Licence, maintenance and what the release cadence tells you

browser-search is MIT-licensed, which permits commercial use, modification and redistribution provided the copyright notice and licence text are retained. That covers the skill itself. It does not cover the three underlying tools, which carry their own licences, and it does not tell you anything about the legal status of scraping a particular site. Check the licences of SearXNG, Camofox and CloakBrowser separately if you plan to redistribute a bundle.

Maintenance cost is concentrated in the dependency chain rather than the skill logic. The release notes show this pattern: v3.1.0 was a dependency update bumping CloakBrowser to 0.5.5 and Playwright Core to 1.62.1, and v3.1.1 was a fix for CloakBrowser setup after the npx install. Two of the three most recent releases are about keeping the browser layer working, not about adding capability. If you adopt this, budget for periodic dependency churn on the stealth browser, and expect to re-test the install path after upgrades rather than assuming it is stable.

The SKILL.md being plain text is the mitigating factor. Orchestration changes are cheap because you edit a text file. Browser-engine changes are not, because they come from upstream projects with their own release schedules.

Who should run this, and the three checks before you commit

Adopt it if you already operate Docker and Node.js 20 or newer, you want search and page extraction handled by one instruction file, and you are comfortable owning the uptime of three local services. The escalation design is genuinely useful: routing only protected sites to the stealth browser keeps the common case fast, and keeping the orchestration in editable plain text means you can adapt it without forking a codebase.

Skip it if you need a managed endpoint with a support contract, if your environment prohibits stealth browser automation, or if your agent only needs search results and never opens pages. In those cases the Camofox and CloakBrowser layers add maintenance without adding value.

Before committing, verify three things against your own deployment. First, that your SearXNG instance returns JSON from its search endpoint, since the search phase depends on that format. Second, that Camofox's REST API responds on the port you configured. Third, that the CloakBrowser setup completes after npx skills add, which is precisely the failure v3.1.1 was released to fix. Run the install on the machine you intend to use, not a development laptop, because the Playwright Core 1.62.1 pin and the browser binaries are the parts most likely to differ across platforms.

Editorial conclusion

Adopt browser-search if you already run Docker and Node.js 20 or newer, want search and browsing handled by one skill file, and are willing to own three self-hosted services instead of paying per query. Do not adopt it if you need a hosted endpoint with an SLA, or if you cannot run a stealth browser in your environment for policy reasons. Before installing, verify three things: that SearXNG returns JSON at your instance's search endpoint, that Camofox answers on its REST port, and that CloakBrowser's Playwright Core 1.62.1 pin resolves on your platform. The v3.1.1 release exists specifically because CloakBrowser setup broke after npx skills add, so run that install path first and confirm the fix before wiring the skill into a production agent.

Official sources

1. Johell1NS/browser-search on GitHub
2. License: MIT
3. Project website
4. README
5. Releases