← Back to Skills Marketplace
Headless Brave Browser
by
Franklin Kelechi
· GitHub ↗
· v0.2.0
771
Downloads
2
Stars
2
Active Installs
1
Versions
Install in OpenClaw
/install brave-headless
Description
Headless web search and content extraction via the Brave Search API. Features exponential-backoff retry, circuit breaker fault isolation, bounded-concurrency...
README (SKILL.md)
brave-search
Headless web search and content extraction via the Brave Search API.
Setup
Run once before first use:
cd \x3Cskill-root>
npm ci
Required environment variable:
export BRAVE_API_KEY="your-key-here"
Get a free API key at brave.com/search/api.
Usage
Search
node scripts/search.js "query" # Basic (5 results)
node scripts/search.js "query" -n 10 # Up to 20 results
node scripts/search.js "query" --content # Include page content
node scripts/search.js "query" -n 3 --content # Combined
node scripts/search.js "query" --json # Newline-delimited JSON
node scripts/search.js --help # Full options + env vars
Extract page content
node scripts/content.js https://example.com/article
node scripts/content.js https://example.com/article --json
node scripts/content.js https://example.com/article --max-length 8000
Output format (plain text)
--- Result 1 ---
Title: Page Title
URL: https://example.com/page
Snippet: Description from Brave Search
Content:
# Page Title
Extracted markdown content...
--- Result 2 ---
...
Pass --json to get one JSON object per line instead, suitable for piping.
Exit codes
| Code | Meaning |
|---|---|
0 |
Success |
1 |
Invalid input or configuration error |
2 |
Page had no extractable content (content.js) |
130 |
Interrupted (SIGINT) |
Configuration (environment variables)
All behaviour is configurable without touching code:
| Variable | Default | Description |
|---|---|---|
BRAVE_API_KEY |
— | Required. Brave Search subscription token |
LOG_LEVEL |
info |
debug · info · warn · error · silent |
LOG_JSON |
false |
Emit logs as newline-delimited JSON to stderr |
FETCH_TIMEOUT_MS |
15000 |
Per-page fetch timeout |
SEARCH_TIMEOUT_MS |
10000 |
Brave API call timeout |
MAX_CONTENT_LENGTH |
5000 |
Max chars of extracted content |
MAX_RETRY_ATTEMPTS |
3 |
Retry attempts on transient errors |
RETRY_BASE_DELAY_MS |
500 |
Base delay for exponential backoff |
RETRY_MAX_DELAY_MS |
30000 |
Backoff delay cap |
CONCURRENCY_LIMIT |
3 |
Parallel page fetches when --content is set |
CB_FAILURE_THRESHOLD |
5 |
Consecutive failures before circuit opens |
CB_RESET_TIMEOUT_MS |
60000 |
Circuit breaker reset window |
All variables are validated at startup — misconfigured runs fail immediately with a descriptive list of every bad value rather than crashing mid-execution.
Architecture
See references/ARCHITECTURE.md for a full module breakdown.
scripts/
├── search.js ← Search CLI entry point
├── content.js ← Content extraction CLI entry point
├── content-fetcher.js ← HTTP fetch + Readability + DOM fallback
├── config.js ← Schema-validated env config
├── circuit-breaker.js ← Fault isolation (CLOSED → OPEN → HALF_OPEN)
├── retry.js ← Exponential backoff with full jitter
├── concurrency.js ← Bounded parallel execution pool
├── utils.js ← htmlToMarkdown, smartTruncate, parseURL
├── logger.js ← Structured leveled logger → stderr
└── errors.js ← Typed error hierarchy
Usage Guidance
This skill appears to be what it says: a Node.js CLI that calls the Brave Search API and fetches page HTML to extract Markdown. Before installing: (1) Verify the skill source (the SKILL.md references a GitHub repo—confirm that matches the registry package) and only use a trusted BRAVE_API_KEY. (2) Be aware 'npm ci' will install and write dependencies to disk and could run package install scripts; inspect package-lock.json and dependency provenance if you require stricter supply-chain controls. (3) Content extraction issues: the tool will make outbound HTTP(S) requests to arbitrary URLs (both Brave API and target pages), so run it in a network-restricted or sandboxed environment if you want to avoid accidental access to internal services. (4) Limit secrets: only provide BRAVE_API_KEY and avoid giving other credentials to the environment where you run the skill. (5) If you need higher assurance, run the tool in an isolated container, review the included source files, and pin/verify dependency checksums before npm install.
Capability Analysis
Type: OpenClaw Skill
Name: brave-headless
Version: 0.2.0
The OpenClaw skill 'brave-headless' is designed for headless web search and content extraction using the Brave Search API. All code and documentation align with this stated purpose. The skill makes legitimate network requests to the Brave API and user-specified/search-result URLs for content fetching. It uses `jsdom` for HTML parsing but does not enable script execution, mitigating a common vulnerability. Input URLs are validated to prevent unsupported protocols. There is no evidence of data exfiltration, malicious execution, persistence mechanisms, obfuscation, or prompt injection attempts in the `SKILL.md` or code. Dependencies are standard and appropriate for the functionality.
Capability Assessment
Purpose & Capability
Name/description match the implementation: the code calls the Brave Search API using BRAVE_API_KEY, fetches page HTML, runs Readability/jsdom/turndown to extract Markdown, and exposes the documented CLI. Declared binaries (node, npm), node dependencies, and env var needs align with the stated functionality.
Instruction Scope
SKILL.md and the scripts confine behavior to searching the Brave API and fetching/parsing target web pages. However, content extraction will perform HTTP(S) requests to arbitrary URLs provided by the user or returned by Brave results — this can reach internal/intranet endpoints if the host running the skill has such network access (SSRF-style exposure). Logs go to stderr and stdout is reserved for output, which is appropriate.
Install Mechanism
Installation uses npm packages (@mozilla/readability, jsdom, turndown, etc.) via npm (package.json + package-lock present). These are mainstream libraries and the install path is a normal npm workflow, but 'npm ci' will write dependencies to disk and run any package lifecycle scripts present in dependencies — a moderate risk compared with an instruction-only skill. No arbitrary URL downloads or extract-from-unknown-host steps were found.
Credentials
Only BRAVE_API_KEY is required as a secret credential; other environment variables control timeouts, logging, and limits. The requested credential is proportional and necessary for Brave API access. The code does not access other undeclared secrets or config paths.
Persistence & Privilege
Skill is not always-enabled and does not request permanent platform-wide privileges. It does not modify other skills or system settings. Autonomous invocation remains possible (platform default), but there's no sign the skill escalates that capability.
How to Use
- Make sure OpenClaw is installed (local or Docker)
- Run the install command in chat:
/install brave-headless - After installation, invoke the skill by name or use
/brave-headless - Provide required inputs per the skill's parameter spec and get structured output
Version History
v0.2.0
- Adds structured leveled logging and improved configuration validation with environment variables.
- Introduces exponential-backoff retry, circuit breaker fault isolation, and bounded-concurrency parallel page fetching.
- Implements smart paragraph-boundary truncation for extracted content.
- Enhances CLI with new options for output format, concurrency, and content extraction.
- Requires Node.js 20+ and npm; runs on macOS and Linux.
- Misconfigured environment variables now cause immediate, descriptive startup errors.
Metadata
Frequently Asked Questions
What is Headless Brave Browser?
Headless web search and content extraction via the Brave Search API. Features exponential-backoff retry, circuit breaker fault isolation, bounded-concurrency... It is an AI Agent Skill for Claude Code / OpenClaw, with 771 downloads so far.
How do I install Headless Brave Browser?
Run "/install brave-headless" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.
Is Headless Brave Browser free?
Yes, Headless Brave Browser is completely free (open-source). You can download, install and use it at no cost.
Which platforms does Headless Brave Browser support?
Headless Brave Browser is cross-platform and runs anywhere OpenClaw / Claude Code is available (macos, linux).
Who created Headless Brave Browser?
It is built and maintained by Franklin Kelechi (@kelexine); the current version is v0.2.0.
More Skills