---
name: flq
description: >-
  Fetch and read web pages as lean, token-efficient text instead of raw HTML.
  Use whenever you need the CONTENT of a URL — documentation, articles, API
  references, changelogs, a page the user linked — rather than its markup. flq
  strips HTML to headings, prose, lists, tables, and code, cutting 70–90% of the
  tokens raw HTML would cost. Available both as MCP tools (fetch_page,
  fetch_pages, crawl_site, head) and as a `flq` CLI. Prefer it over a raw HTTP
  fetch + manual HTML parsing for any human-readable page. Not for SPAs /
  JavaScript-rendered content (no headless browser) or for downloading binaries.
---

# flq — read the web without wasting tokens

flq turns an HTML page into `.flq`: a compact text format that tokenizes tight
and reads clean. Reach for it any time the goal is to *understand the content of
a page*, not to fetch bytes.

## When to use which tool

| Goal | Tool / command |
| --- | --- |
| Read one page | `fetch_page(url)` — CLI: `flq URL` |
| Read several pages at once (compare, gather) | `fetch_pages(urls)` — CLI: `flq A B C` |
| Explore a whole docs site / section | `crawl_site(url, depth, max_pages)` — CLI: `flq URL --depth 1 --max-pages 10` |
| Just check status / headers (is it up? content-type?) | `head(url)` — CLI: `flq URL -I` |

Both the MCP tools and the CLI share the same extraction engine and options.
Use the MCP tools when they're connected; fall back to the `flq` CLI over a
shell when they aren't.

## Narrow the output — don't fetch more than you need

The single biggest token win is asking only for the blocks you care about:

- **Code samples only** → `filter: "code"` (CLI `-f code`). Ideal for "show me
  how to call X" against API docs.
- **Structure / outline** → `filter: "headings"` to map a long page before
  drilling in.
- **Data** → `filter: "tables"`.
- **Combine** → `"tables,code"` (CLI `-f tables,code`).
- **Find a section** → `grep: "install"` returns only matching body lines.
- **Scope to one region** → `select: "article.post"` (CSS selector) skips nav /
  sidebars / boilerplate.
- **Hard token cap** → `max_tokens: 2000` truncates cleanly on a block boundary
  and flags `truncated`.

Filter values: `headings`, `code`, `tables`, `links`, `img`, `text`. Links and
images are off by default (enable with `links` / `img`).

## Output format

```
title: Page Title
url: https://example.com
lang: en
desc: meta description
---
# heading
body text
- list item
  - nested item
> quote
@ https://link | link text      (only with filter "links")
! https://img.png | alt text    (only with filter "img")
table[3]{name,price}:
Widget,1200
Gadget,500
Doohickey,300
```

Prose stays markdown (LLMs parse it natively). Tables declare field names once,
then stream rows as CSV. When a filter is set, the frontmatter is dropped and
only matching blocks are returned.

## Typical workflows

- **Answer a question from docs**: `fetch_page(url)`, or `filter: "code"` when
  the user wants the call/snippet. If the page is huge, `filter: "headings"`
  first to find the right section, then `select` or `grep` into it.
- **Research across sources**: `fetch_pages([...])` to pull several pages in one
  call and compare.
- **Learn an unfamiliar library site**: `crawl_site(url, depth=1, max_pages=10)`
  to sweep same-host pages, then dig into the relevant ones.

## Gotchas

- **No JavaScript.** flq uses no headless browser; SPA / client-rendered pages
  come back thin or empty. Check with `flq URL --raw | head`; if the content
  isn't in the HTML source, flq can't extract it.
- **Same-host crawl only.** `crawl_site` follows links on the seed URL's host.
- **CLI stdout is content; MCP stdout is JSON-RPC.** In `--mcp` mode, only
  JSON-RPC goes to stdout (logs go to stderr) — never mix.
- **Blocked by UA?** Some sites reject default agents; pass `-A "..."` in CLI
  mode.

## CLI quick reference

```sh
flq URL                      # one page
flq URL -f code              # code blocks only
flq URL -g "install"         # grep body lines
flq URL --select "main"      # scope by CSS selector
flq URL --max-tokens 2000    # token budget
flq URL -j                   # JSON: {title,url,body,tokens,truncated}
flq URL --depth 1            # crawl same-host links
flq URL -I                   # response headers (like curl -I)
curl -s URL | flq -          # HTML from stdin
```

See `docs/mcp.md` in the flq repo for the full MCP tool reference and Claude
Code setup (`claude mcp add flq -- flq --mcp`).
