UI Scout — Website UI research for AI agents

UI Scout collects website screenshots and structured page evidence so your AI agent can turn real references into design inspiration and a build-ready brief.

Give it a URL list and a research goal. Get a bundle on disk with screenshots, structured per-page data, and a generated agent-prompt.md your AI agent (Claude Code, Cursor, Lovable, v0, Codex…) can read directly. No paid LLM calls.

Requirements

• Node.js 22+ (CI builds and publishes on Node 24)
• ~170 MB free disk for Playwright Chromium (installed automatically on first install)

Quick start

npm install -g ui-scout
# postinstall downloads Playwright Chromium with a progress bar; no extra steps.

ui-scout research \
  --input my-urls.txt \
  --goal "Homepage inspiration for a B2B SaaS analytics product"

# Output lands in runs/<today>-<input-stem>/
# Open the folder in Claude Code / Cursor and tell your agent:
#   "Read agent-prompt.md and follow the instructions."

No global install? Use npx ui-scout research … instead — first run triggers the same one-time Chromium download.

Want a ready-made URL list to try? The bundled examples live inside the installed package; copy one out:

cp "$(npm root -g)/ui-scout/examples/saas-homepages.txt" ./saas-homepages.txt

Or grab them from the examples/ folder in this repo.

What you get

A per-run bundle on disk:

runs/<runId>/
  manifest.json          # structured data for every captured page
  summary.txt            # human-readable run summary
  agent-prompt.md        # paste-ready prompt for your AI agent
  screenshots/
    001-stripe-com-home.desktop.png
    002-...
  pages/
    001-stripe-com-home.json     # title, meta, headings, CTAs, tags
    001-stripe-com-home.txt      # normalized visible text
  logs/
    capture.log
    failures.json

How to use the bundle with your AI agent

1. Open the run folder in any filesystem-and-vision-capable agent (Claude Code, Cursor, Lovable, v0).
2. Tell the agent: Read agent-prompt.md and follow the instructions.
3. The prompt asks the agent to produce a design research brief that covers: Fit Assessment → Summary → Common Patterns → Strong Examples → What to Borrow → What to Avoid → Recommended Direction → Build Brief (with a paste-ready coding-agent prompt).

The prompt explicitly tells the agent: cite specific page IDs, prefer synthesis over commentary, treat screenshots as ground truth.

URL input format

Plain text. One URL per line. Comments and directives supported:

# Bare URLs work as-is.
https://stripe.com/

# Per-line type override (free-form vocabulary).
https://linear.app/pipelines [type=feature]

# Per-line type + tags.
https://linear.app/settings [type=settings] [tags=authenticated,internal]

# Block directive — applies to URLs until the next blank line.
[tags=authenticated]
https://linear.app/settings
https://linear.app/settings/billing

See docs/bundle-format.md for the full bundle spec and docs/prompts.md for prompt-writing notes.

CLI

ui-scout research \
  --input <file>                    # required
  --goal "<text>"                   # required
  [--output <dir>]                  # default: runs/<YYYY-MM-DD>-<input-stem>/
  [--name <slug>]                   # alternative: runs/<slug>/
  [--viewport desktop,mobile]       # default: desktop
  [--concurrency <n>]               # default: 3
  [--timeout <ms>]                  # default: 30000
  [--limit <n>]                     # default: unlimited
  [--headed]                        # default: headless

Non-empty run folder is never overwritten — delete it or pass a different --name.

Examples

Three bundled URL files, each with a ready-to-copy goal string in examples/README.md:

• examples/saas-homepages.txt — B2B SaaS homepages
• examples/pricing-pages.txt — pricing pages from the same set
• examples/docs-landings.txt — developer-tool docs entry points

Library mode (per-app capture)

Library mode is UI Scout's original capability: config-driven per-app capture with auth, multi-viewport, flows, masking, and a static gallery. It is still fully operational and unchanged.

See docs/library-mode.md for setup, configs, flow actions, and the gallery viewer.

What's not included

• Built-in LLM summarization or vision analysis — the agent is yours, not ours.
• Vector embeddings or semantic visual search.
• URL discovery / autonomous web search.
• Stealth plugins or anti-detection (real Chrome User-Agent only; ~20% failure budget on bot-protected sites is policy).
• Research-mode authentication (library mode still has its auth flow).
• Figma plugin, multi-user collaboration, cloud sync.

Roadmap

• Research-mode authentication (storage-state bridge from library mode)
• Optional LLM-assisted auto-tagging (additive to heuristics)
• Shortlist / pinned-favorites in manifest
• Research-mode gallery (static HTML for browsing a bundle)
• Visual similarity search across runs
• Competitor-comparison mode (run-vs-run diff)

See docs/ui-scout-mvp-plan.md §Post-MVP Roadmap for the full list.

Releasing

Publishing is automated via .github/workflows/publish.yml. It fires on any vX.Y.Z tag push.

One-time setup: add an NPM_TOKEN repo secret (npm "Automation" token, granular access to ui-scout).

To cut a release:

npm version patch        # or: minor / major — bumps package.json, commits, creates tag
git push --follow-tags   # push commit + tag; GitHub Action takes it from there

The workflow checks out the tag, runs npm ci and npm run build, reconciles the package.json version with the tag if they drifted, and runs npm publish --access public. Watch progress in the repo's Actions tab.