Core Usage

Site Adapters

To read "structured data from site X," the cheapest path is to skip snapshot + click. Before you open, page through, and click your way across GitHub / Reddit / Bilibili, check whether a ready-made site adapter exists — a small community-written JS snippet that hits the site's own JSON API directly from your logged-in tab and hands you clean structured data in one shot. No clicking, no scraping, no screenshots.

What it is

A site adapter is a community-written JS function: it calls the site's own JSON API directly from your currently logged-in tab and returns clean, structured data. Essentially it's a packaged, per-site eval — except you don't have to write it yourself, and you don't have to reverse-engineer each site's endpoints.

Because it runs inside the tab you're already logged into and makes requests as you, feeds that require a session — like bilibili/feed or twitter/… — read fine too. That's exactly what hand-crafting URLs or anonymous scraping can't do.

ℹ️ Relationship to eval

If you already know how to use eval to hit a site's internal API, a site adapter is that same code distilled into a command — maintained by the community and organized per site. You skip the grunt work once, and everyone else gets to reuse it.

How to use it

Four actions: pull the pack once (update), see what's installed (list), see how a given adapter is called (info), and run it (site <name>/<cmd>).

bash

$ chrome-use site update                            # one-time: pull the adapter pack (count grows with bb-sites)
$ chrome-use site list                              # what's installed (github/issues, reddit/search…)
$ chrome-use site info github/issues                # an adapter's params + which domain it runs on
$ chrome-use site github/issues owner/repo --json   # run → JSON (navigates there for you)

site update: pulls the whole adapter set from the bb-sites community pack. Only needed once; after that chrome-use keeps it in sync automatically (see "Auto-triggering" below).
site list: lists every <name>/<cmd> installed locally, e.g. github/issues, reddit/search.
site info <name>/<cmd>: shows which params an adapter declares and which domain it runs on — check this before calling, and you'll know what to pass.
site <name>/<cmd> [args] --json: actually runs it. Add --json for one line of parseable structured output.

With --json, that last command returns the site's own data, already cleaned into a parseable structure (excerpted and indented below):

what site github/issues epiral/bb-sites --json returns

{
  "success": true,
  "data": {
    "domain": "github.com",
    "origin": "https://github.com/",
    "result": {
      "count": 30,
      "repo": "epiral/bb-sites",
      "state": "open",
      "issues": [
        {
          "number": 85,
          "title": "feat(youtube/transcript): migrate to API-based subtitles",
          "author": "kerrmoulton",
          "state": "open",
          "is_pr": true,
          "comments": 0,
          "labels": [],
          "created_at": "2026-06-16T07:54:47Z",
          "url": "https://github.com/epiral/bb-sites/pull/85"
        }
        // … 29 more with the same shape; count is the total returned
      ]
    }
  },
  "error": null
}

✅ info first, then run

When you're not sure what params an adapter needs, run site info <name>/<cmd> first to see its declared params and target domain, then pass them accordingly. Cheaper than blindly running once and reading the error.

Params and navigation

Adapter params are filled positionally in declaration order; to override one by name, use --key value. The two forms mix freely: positional args fill the slots, and --key pins a specific override.

positional vs --key override

# positional args fill in declaration order
$ chrome-use site github/issues owner/repo --json

# --key overrides by name (order doesn't matter)
$ chrome-use site reddit/search --query "chrome-use" --sort new --json

When it runs, it navigates to the domain the adapter declares — and if your current tab is already on that domain, it reuses the current tab instead of opening a new one. The request still happens inside the tab you're logged into, so signed-in feeds like bilibili/feed or twitter/… return normally (why they do is covered under "What it is" above).

ℹ️ It navigates for you

You don't have to open the target site manually first. site <name>/<cmd> navigates to the adapter's domain and then executes; but you do need to be already logged in to that site for logged-in feeds to be readable.

Auto-triggering — see it, use it

You don't have to remember which sites have adapters. chrome-use keeps the adapter pack in sync automatically (on first use + weekly), and when you open / navigate / snapshot a page whose domain has adapters, it proactively hints you:

a line on stderr: 💡 site adapters for <domain>;
a siteAdapters: {domain, commands} field in --json output.

auto-hint · stderr

$ chrome-use open https://github.com/epiral/bb-sites
# … as the page opens, a line pops up on stderr:
💡 site adapters for github.com: github/issues, github/pulls, github/repo …

✅ See the hint, prefer the site <name>/<cmd> it lists

When you see 💡 site adapters for <domain>, don't snapshot + click to read the data — just use the site <name>/<cmd> it names: cheaper, more reliable, and already installed. You also don't need to run site update yourself first — just use the command it gives you.

ℹ️ Exception on a fresh environment

Only on a brand-new environment where the adapter pack hasn't been pulled yet might naming a site <name>/<cmd> report "not installed." In that case run site update once and re-run the command.

When to use it vs extract --schema vs snapshot

There's often more than one path to the same page of data. Site adapters are the first choice for structured data from a known site; fall back down the ladder when no suitable adapter exists. The table below helps you pick.

Your situation	Use	Why
Structured data from a known site (GitHub issues, Reddit/HN search, Bilibili / Twitter feeds), especially once logged in	`chrome-use site <name>/<cmd>`	Hits the site's JSON API directly, runs as you, skips snapshot + click — cheapest and most reliable
Structured data from any page with no community adapter — tables, search results, feed rows, dashboards	`extract --schema '{rows,fields}'`	Give it a shape, get clean JSON in one call — no writing eval, no dumping the whole page's HTML
You need to reason over it with a model, or need `@ref`s to interact	`snapshot -i --json`	A structured snapshot with stable refs — readable and drives follow-up click / type
A one-off extraction needing a custom shape with special logic	`eval --stdin`	Write JS directly in the page's MAIN world — most flexible (an adapter is just this, distilled)

ℹ️ Cheapest to most expensive

Roughly: site adapter → extract --schema → snapshot/eval loop. If there's an adapter, use it; no adapter but a regular shape, use extract --schema; only when neither fits fall back to the usual manual snapshot / eval loop. For the full picture of data extraction, see Extracting Data.

Source and license

Adapters come from the bb-sites community pack. chrome-use fetches and executes them at runtime — this repo does not bundle or redistribute any adapter code, and site update fetches the latest version from upstream each time.

ℹ️ Fetched at runtime, not built in

Because adapters are maintained upstream by the community and fetched only at runtime, the command set you see changes as bb-sites updates; site list reflects the version you synced to locally this time.

Next steps

Site adapters are the cheapest tier of data extraction; the methods below cover the rest.

🧪 Extracting Data

No adapter? eval for a custom shape, or extract --schema in one step.

📖 Reading Pages

snapshot for a structured view with stable @refs — readable and drives interaction.

🔎 Finding Elements

When the snapshot is too big, use find to pin the target precisely.