Skip to content
Back to search

fatsearch

fats: web pages and PDFs → small cached Markdown outlines for AI agents. CLI + local MCP. Bring your own Oxylabs / Bright Data key.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/fatsearch--fatsearch/badge.svg)](/listings/fatsearch--fatsearch)

HTML

<a href="/listings/fatsearch--fatsearch"><img src="/api/listings/fatsearch--fatsearch/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 269 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <a href="https://fatsearch.com"><img src="docs/assets/banner.png" alt="FATSEARCH: the ripgrep of web searching for AI agents." width="800"></a>
  3. Reads the pages your agent's built-in fetch can't (JS pages, PDFs) through your own provider key,<br>
  4. kept on disk as clean Markdown, navigated by outline and ids.
  5. <br>
  6. [![crates.io](https://img.shields.io/crates/v/fatsearch?style=flat-square&label=crates.io&color=f0883e&labelColor=161b22)](https://crates.io/crates/fatsearch)
  7. [![npm](https://img.shields.io/npm/v/fatsearch?style=flat-square&label=npm&color=f0883e&labelColor=161b22)](https://www.npmjs.com/package/fatsearch)
  8. [![release](https://img.shields.io/github/v/release/fatsearch/fatsearch?style=flat-square&label=release&color=3fb950&labelColor=161b22)](https://github.com/fatsearch/fatsearch/releases/latest)
  9. [![license](https://img.shields.io/badge/license-MIT%20%2F%20Apache--2.0-79c0ff?style=flat-square&labelColor=161b22)](LICENSE-MIT)
  10. <br>
  11. <img src="docs/assets/race.svg" alt="Same question, same answer: FATSEARCH puts 1,384 tokens in the agent's context, Firecrawl puts the whole page, 112,517." width="900">
  12. same question · same answer · 81× less context<br>
  13. **That's the point.**
  14. </div>
  15. <br>
  16. ## Every page your agent reads costs you this
  17. <div align="center">
  18. | <sub>Wikipedia · Rust · model input at $2 / M tokens (Claude Sonnet 5.5, 2026-10-19)</sub> | Tokens in context | Fetch | Model bill |
  19. |:--|--:|--:|--:|
  20. | Firecrawl | 112,517 | 1 credit | $0.23 |
  21. | Bright Data Unlocker | 103,625 | 1 request | $0.21 |
  22. | Oxylabs Web API | 102,609 | 1 request | $0.21 |
  23. | Tavily Extract | 97,504 | 0.2 credit | $0.20 |
  24. | Jina Reader | 94,415 | free | $0.19 |
  25. | **FATSEARCH** | **918** | **$0** | **$0.002** |
  26. </div>
  27. Your agent gets a short outline. It reads **one section** when it needs depth, not the whole page.<br>
  28. Menus, cookie banners, navigation, footer links, tracking scripts: gone.<br>
  29. Prices, dates, numbers: kept <sub>(loss guard counts every one)</sub>.
  30. > [!TIP]
  31. > The "free" fetch costs **~100×** more at the model. And it stays in context, every turn after.
  32. <br>
  33. ## Your key never touches the chat
  34. `fats setup <provider>` opens a one-time key form on `127.0.0.1`, behind a random token, for 30 minutes.<br>
  35. You paste the key there in your browser, so it stays out of the chat, the model's context and the agent's logs.<br>
  36. The form refuses a POST from another origin; the key is checked live, saved with mode 0600, sent only to its provider.
  37. ```console
  38. $ fats setup decodo
  39. = setup decodo · waiting for the key at http://127.0.0.1:59802/k/e0c8baba7a5b058947f4fdab97dabb05/decodo · 30 min · $0
  40. tell the user (never ask for the key in chat):
  41. 1. open https://dashboard.decodo.com/web-data/playground (no account yet: https://dashboard.decodo.com/register)
  42. 2. Copy the API key shown on the Web Data playground. Do NOT paste it in this chat.
  43. 3. open http://127.0.0.1:59802/k/e0c8baba7a5b058947f4fdab97dabb05/decodo , paste the key, press Save
  44. then: fats setup (when the user says done; end your turn, do not poll · checks it, $0)
  45. link dead (30 min passed)? run fats setup decodo again and give the user the new line 3
  46. ```
  47. `fats setup` shows a form still waiting (`! form_waiting decodo · 23 min left · <its URL>`) or one whose time ran
  48. out (`! form_expired decodo · the link the user got is dead → fats setup decodo · new link, same 3 steps`).
  49. Over SSH (`SSH_CONNECTION` or `SSH_TTY` set) one more line says how to paste the key in a terminal there.
  50. <br>
  51. ## On hard pages
  52. `fats` tries plain HTTP first (free). If the page is a JS shell, a captcha, or a wall,
  53. it climbs to your providers: cheapest first, hedged, with cost tracking on every call.
  54. ```console
  55. $ fats https://www.nytimes.com/ dry:true
  56. nytimes.com/ fetch plain → oxy (after a captcha) → bd ∥ oxyjs after 5s → new u1 · up to $0.0040
  57. $ fats stats
  58. u1 rust-lang.org · Rust Programming Language · plain 230ms $0.0000 · 1.2ktok
  59. u2 en.wikipedia.org · Rust (programming language… · plain 558ms $0.0000 · 40.9ktok
  60. ```
  61. <sub>`fats stats` is the marketing: real numbers, not claims.</sub>
  62. **38 hard pages** <sub>social · news · shops · travel · classifieds · search · one run each</sub>
  63. | answer in the returned text, within | 1 s | 10 s | 20 s | 60 s |
  64. |:--|:-:|:-:|:-:|:-:|
  65. | **FATSEARCH 0.2.0** <sub>2026-10-21</sub> | 12 | 19 | 19 | **35** <sub>/38</sub> |
  66. | Firecrawl <sub>2026-10-16</sub> | 0 | 22 | 24 | 24 |
  67. | Tavily <sub>2026-10-16</sub> | 9 | 17 | 18 | 19 |
  68. <sub>FATSEARCH reads more of the hard pages; Firecrawl and Tavily are faster on the pages they do read (same pages, medians: 23.7 s vs 4.9 s, 23.7 s vs 1.0 s). Readers ran on different days. [Method and every row →](docs/benchmarks.md#results-hard-pages-time-to-an-answer) · the table above: [one page, six readers →](docs/benchmarks.md#one-page-six-readers)</sub>
  69. **Tested in agents** <sub>FATSEARCH 0.1.3 · Claude Code 2.1.280, one run each, 2026-10-19</sub>
  70. - 51 tasks, FATSEARCH MCP vs Firecrawl MCP: 50/51 vs 51/51 right · $15.06 vs $53.48 per 1k tasks · median 5.3 s vs 6.7 s · slowest tenth 43.8 s vs 21.5 s. [Details →](https://fatsearch.com/benchmarks/)
  71. - Claude Code's WebFetch got 403 on npm, Medium and G2; FATSEARCH read all three. [Details →](https://fatsearch.com/benchmarks/)
  72. - One Wikipedia page, open-source readers: FATSEARCH 1,384 tokens to the answer; mcp-server-fetch, Crawl4AI, mcp-searxng and self-hosted Firecrawl 75k–117k for the whole page. [Details →](https://fatsearch.com/benchmarks/)
  73. - Full tables, losses included: [docs/benchmarks.md](docs/benchmarks.md#tested-in-agents-claude-code-51-tasks-fatsearch-mcp-vs-firecrawl-mcp-2026-10-19)
  74. <br>
  75. ## Get started
  76. <div align="center">
  77. | <sub>1 · INSTALL</sub> | <sub>2 · KEYS <i>(optional)</i></sub> | <sub>3 · PLUG IN</sub> |
  78. |:-:|:-:|:-:|
  79. | `brew install fatsearch/tap/fatsearch` | `fats setup` | `claude mcp add --scope user fats -- fats mcp` |
  80. <sub>or &nbsp;`curl -fsSL https://fatsearch.com/install.sh | sh`&nbsp; · &nbsp;Windows: `npm i -g fatsearch`&nbsp; · &nbsp;`cargo install --locked fatsearch`&nbsp; · &nbsp;[every host →](docs/installation.md)</sub>
  81. </div>
  82. > [!NOTE]
  83. > The package is `fatsearch`; the command is `fats` (like `ripgrep` → `rg`). Homebrew, npm and the install
  84. > script also add `fatsearch` as a second name for it; `cargo install` adds only `fats`.
  85. > **No account needed.** Without a provider key, `fats` reads what a plain request gets; web search needs an Oxylabs or Bright Data key.
  86. > With **any one key** ([Oxylabs](https://dashboard.oxylabs.io/en/registration), [Bright Data](https://brightdata.com/cp/start) or [Decodo](https://dashboard.decodo.com/register)) it renders and unblocks pages through that provider.
  87. <br>
  88. ## Setup
  89. **You, at a terminal:** run `fats setup`. It is a menu (↑↓ Enter): the free fetch and each provider with its
  90. state, then Settings (agent connection, cache, stats, telemetry). Pick a provider, paste its key (shown as `•` and a count), and
  91. `fats` checks it live before it saves it. `fats setup oxy` jumps
  92. straight to one (also `bd`, `decodo`, `gh`).
  93. **Your agent, or no terminal:** the agent runs `fats setup oxy` (or `bd`, `decodo`, `gh`). It prints the
  94. provider's dashboard link and a one-time form on `127.0.0.1`, open for 30 minutes. The agent gives you the URL;
  95. you paste the key into the form in your browser, never into the chat ([what it prints](#your-key-never-touches-the-chat)).
  96. Then the agent runs `fats setup` to check it ($0).
  97. Keys go to `auth.json` in the key dir (mode 0600) and are sent only to their provider. **`auth.json` is the one
  98. key source:** `fats` never sends a key from the environment, so the key you saved is the key every call uses
  99. (`fats` shows each one's last 4 characters: `keys oxy …6XBR · bd none · decodo none · gh none · auth.json`). On
  100. a machine without a browser (CI, SSH), pipe the key in: `printf %s "$KEY" | fats setup oxy` checks it and saves
  101. it. Keys already exported: run `fats setup import-env` once: it checks them, copies them in where no key is
  102. saved, and never replaces a saved one. Replacing a key keeps the old file as `auth.json.bak` (0600).
  103. | Provider | Key | Page, no JS | Page, rendered | Web search |
  104. |:--|:--|--:|--:|--:|
  105. | free (plain HTTP, your IP) | none | $0 | — | — |
  106. | [Oxylabs](https://dashboard.oxylabs.io/en/registration) Web API | `fats setup oxy` (import: `OXYLABS_WEB_API_KEY`) | $0.0010 | $0.0015 | $0.0010 |
  107. | [Bright Data](https://brightdata.com/cp/start) Web Unlocker | `fats setup bd` (import: `BRIGHTDATA_API_KEY`; zone `BRIGHTDATA_UNLOCKER_ZONE`) | — | $0.0015 | $0.0015 |
  108. | [Decodo](https://dashboard.decodo.com/register) Web Data API | `fats setup decodo` (import: `DECODO_AUTH_TOKEN`) | $0.0010 | $0.0015 | — |
  109. | GitHub (`fats gh`) | `fats setup gh` copies the `gh` CLI's token (import: `GH_TOKEN`) | $0 | — | — |
  110. <sub>List prices per page, the ones `dry:true` and `fats stats` use. Oxylabs and Bright Data spend can be checked
  111. with `fats account`; Decodo has no usage read for this key, so its `$` is the list price, never reconciled.</sub>
  112. **Turn one off** without losing its key: `fats setup oxy off`, back with `fats setup oxy on`.
  113. **The free fetch is your own connection:** one request per page from your IP, at most one start per site per
  114. second; a page waits its turn rather than buying a provider call. Providers use their own IPs and have no pace.
  115. `fats setup free off` sends every page to a provider instead, so every page costs.
  116. <br>
  117. ## MCP
  118. **One tool. One string. Same commands.**
  119. ```sh
  120. fats setup mcp claude # or codex, cursor: fats adds itself
  121. claude mcp add --scope user fats -- fats mcp # Claude Code
  122. codex mcp add fats -- fats mcp # Codex
  123. {"mcpServers": {"fats": {"command": "fats", "args": ["mcp"]}}} # Cursor, Desktop, …
  124. ```
  125. <sub>The tool is `fats(cmd)` and its card is ~60 tokens. An agent that knows `fats u1#3` knows the whole tool.<br>
  126. MCP Registry: `mcp-name: io.github.fatsearch/fats`</sub>
  127. <br>
  128. ## Commands
  129. | Command | Does |
  130. |:--|:--|
  131. | `fats <url>` | fetch → clean → outline, cached as `u1` |
  132. | `fats u1#3` | read section 3 |
  133. | `fats u1 price` | filter inside the page |
  134. | `fats u1 links` · `fats l4` | numbered links · follow one |
  135. | `fats rust async runtime` | web search → results as ids |
  136. | `fats gh rust markdown` | GitHub repos by stars |
  137. | `fats ./report.pdf` | local file, one section per page |
  138. | `fats stats` | every fetch: provider, ms, cost, tokens |
  139. | `… dry:true` | what would run, what it would cost |
  140. <sub>mods &nbsp;<samp>limit:20 &nbsp;country:de &nbsp;js:true &nbsp;wait:30 &nbsp;fresh:true</samp> &nbsp;· &nbsp;one screen of all of it: `fats help` &nbsp;· &nbsp;how to use it well: `fats guide`</sub>
  141. <br>
  142. ## For agents
  143. The agent skill is versioned in this repo ([skills/fatsearch/SKILL.md](skills/fatsearch/SKILL.md)): how to read
  144. pages without flooding context, and how to install, connect and verify `fats` when it is missing.
  145. ```sh
  146. npx skills add fatsearch/fatsearch # Agent Skills standard: Claude Code, Codex, Cursor, Copilot, Gemini CLI, …
  147. gh skill install fatsearch/fatsearch # the same through GitHub CLI ≥ 2.90
  148. ```
  149. An agent without either CLI reads it pinned to a release:
  150. `https://raw.githubusercontent.com/fatsearch/fatsearch/v0.2.5/skills/fatsearch/SKILL.md`.
  151. That way the agent sees versioned text it can review, and nothing it runs comes from a website.
  152. Docs as plain Markdown for agents: [fatsearch.com/llms.txt](https://fatsearch.com/llms.txt).
  153. <br>
  154. ## Telemetry
  155. FATSEARCH shares anonymous usage stats so we can fix what breaks. It never shares what you read or search.
  156. - **Never sent:** URLs, searches, page text, files, API keys, your IP address, any id.
  157. - **Sent:** fatsearch version, OS, which package (npm, Homebrew, cargo…), commands used, errors,
  158. which providers worked, crashes in our code.
  159. See exactly what's sent with `fats telemetry show`. Turn it off in `fats setup → Settings → Telemetry`,
  160. with `fats setup telemetry off`, `FATS_TELEMETRY=0` or `DO_NOT_TRACK=1`. Details: [docs/telemetry.md](docs/telemetry.md)
  161. <br>
  162. <div align="center">
  163. <kbd> 17–21 MB </kbd> binary &nbsp;&nbsp; <kbd> 4 ms </kbd> start &nbsp;&nbsp; <kbd> 5 ms </kbd> cached read &nbsp;&nbsp; <kbd> $0 </kbd> plain pages &nbsp;&nbsp; <kbd> $0.001–0.0065 </kbd> hard pages (three keys)
  164. <sub>17 MB (macOS arm64) to 21 MB (Linux x86_64) · 4 ms native; the npm shim adds Node's ~40 ms<br>no daemon · no browser · anonymous usage stats (off: `fats setup telemetry off` · `FATS_TELEMETRY=0` · `DO_NOT_TRACK=1`) · [every run →](docs/benchmarks.md)</sub>
  165. </div>
  166. <br>
  167. <details>
  168. <summary><b>What it doesn't do (yet)</b></summary>
  169. <br>
  170. - `match:near` / `match:topic`: needs a local model
  171. - OCR for scanned PDFs → `! no_text`
  172. - DOCX / XLSX → `! not_in_v1 zip`
  173. - OS keychain: keys live in `auth.json` (mode 0600)
  174. - Remote MCP: stdio only
  175. - Logins: a page behind a login stays behind it
  176. Each prints a `!` row explaining what's missing and what to do. **Never silence.**
  177. </details>
  178. <br>
  179. <div align="center">
  180. <a href="https://fatsearch.com"><b>fatsearch.com</b></a>
  181. <br><br>
  182. <sub>
  183. <a href="docs/reference.md">reference</a> ·
  184. <a href="docs/benchmarks.md">benchmarks</a> ·
  185. <a href="CHANGELOG.md">changelog</a> ·
  186. <a href="SECURITY.md">security</a> ·
  187. <a href="CONTRIBUTING.md">contributing</a>
  188. <br><br>
  189. MIT or Apache-2.0, at your option.
  190. </sub>
  191. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.