tap-web

name	tap-web
metadata	{"author":"vaayne/tap","version":"v0.4.8"}
description	Access websites, search the web, and extract clean content using the `tap` CLI. Supports structured site scripts, readable page extraction, and browser automation for tabs, screenshots, forms, cookies, JavaScript evaluation, and network capture. Use for web lookup, page reading, content extraction, browser interaction, authenticated sessions, request interception, or CDP-connected desktop apps.

tap-web

Install

# Install tap CLI (includes embedded skill)
curl -fsSL https://raw.githubusercontent.com/vaayne/tap/main/scripts/install.sh | sh

# Install/update the skill to default location (~/.config/tap/skills/tap-web/)
tap skill install

# Or install to custom path (for agent use)
tap skill install --path /custom/path/to/skills/tap-web

# Or via environment variable
TAP_SKILL_DIR=/custom/path/to/skills/tap-web tap skill install

⚠️ Version Check: The installed skill's metadata.version should match tap --version. If they differ after installing or upgrading tap, run tap skill install again. If you use a custom install location, rerun it with the same --path or TAP_SKILL_DIR.

Before accessing any site, check $XDG_CONFIG_HOME/tap/site-notes/{domain}.md for saved knowledge. Update after learning. See references/site-notes.md.

Pick the right tool

Start simple and escalate only when needed:

Tier	Tool	Use for
1	tap site	Structured data from known sites
2	tap fetch	Clean readable content from a URL
3	tap browser	Interaction, auth, screenshots, network capture

Decision flow:

1. Check for a site script first: tap site list / tap site search <query>
2. For X/Twitter content, try FxEmbed scripts first (twitter/fxembed-status, twitter/fxembed-search, twitter/fxembed-profile-*) before browser or fetch. For long-form X articles, use tap site twitter/fxembed-status id=<tweet-id> format=markdown -f raw.
3. If you just need readable content: tap fetch <url>
4. If you need interaction/auth/network: tap browser ...

Quick reference

# Site scripts
tap site list
tap site search <query>
tap site info <script>
tap site sync
tap site run <site/action> [key=value]
tap site <site/action> [key=value]

# Content extraction
tap fetch <url>
tap fetch --json <url>
tap fetch -b <url>

# Browser context
tap status [--json]
tap attach chrome
tap attach chrome --browser-url http://localhost:9222
tap attach chrome --port-file ~/Library/Application\ Support/Google/Chrome/DevToolsActivePort
tap attach status [--json]
tap attach clear

# Browser workflow
tap browser open <url>
tap browser open <url> --new-tab
tap browser open <url> --show
tap browser tabs [--json]
tap browser switch <tab-id>
tap browser close-tab [tab-id]
tap browser status [--json]

# Page actions
tap browser text [selector]
tap browser evaluate <js>
tap browser screenshot [--output <path>]
tap browser pdf [--output <path>]
tap browser snapshot [--interactive] [-f json]
tap browser click <selector|@eN>
tap browser type <selector|@eN> <text>
tap browser fill <selector|@eN> <value> [<selector|@eN> <value> ...] [--submit <selector|@eN>]
tap browser hover <selector>
tap browser scroll [selector]
tap browser select <selector|@eN> <value>
tap browser wait <selector>
tap browser keypress <key>
tap browser dialog

# Page state / network
tap browser forms
tap browser cookies get|set|clear
tap browser network wait --url-pattern "*/api/*" --body
tap browser network log --resource-type XHR,Fetch --timeout 30s
tap browser network intercept --block --url-pattern "*.ads.*"
tap browser network clear

Browser-backed flags

Flag	Use when
-b, --browser	Force browser execution for site / fetch
--show	Need a visible browser for auth or manual interaction
--wait <dur>	Need a fixed post-navigation delay
--wait-selector <sel>	Wait for a specific element
--wait-js <expr>	Wait for a JS condition
--timeout <dur>	Limit execution time
--browser-url <url>	One-shot DevTools override
--profile-dir <path>	One-shot profile override
--lp, --lightpanda	Fast JS rendering without Chrome auth flows

Compatibility aliases exist, but prefer the names above.

Preferred auth flow

Do not use tap login.

Use:

tap attach chrome
tap browser open https://example.com/login --show

Then reuse that same browser context with tap site -b, tap fetch -b, and later tap browser ... commands.

tap attach chrome owns an internal proxy daemon for the attached browser. If that attached state goes stale, normal commands fail explicitly and should be repaired with tap attach chrome, not by switching contexts implicitly.

Context resolution

Browser-backed commands resolve context in this order:

1. explicit --browser-url / --profile-dir
2. persisted default context from tap attach ...
3. managed local default browser context

If an attached context becomes unreachable, tap marks it stale and fails explicitly. It does not silently switch to another browser/account context.

Snapshot refs

When CSS selectors are unstable or unknown, capture a semantic snapshot and reuse its refs:

tap browser snapshot --interactive -f json
tap browser click @e3
tap browser type @e1 "hello"
tap browser fill @e1 "[e-mail]" @e2 "secret" --submit @e4
tap browser select @e5 "us"

Rules:

• Refs like @e1 come from the latest snapshot for the current tab.
• Refs are only valid for the same page document.
• After navigation, reload, or major page updates, re-run tap browser snapshot before using old refs.
• Mixed fills are safe: selector-based fills complete before a ref-based --submit @eN click is dispatched.

Efficiency rules

Never dump full HTML unless there is no cheaper path.

Preferred order:

1. Site script
2. tap fetch
3. tap browser network wait --body
4. tap browser snapshot for semantic interactive discovery
5. tap browser text
6. targeted tap browser evaluate
7. screenshot

References

• browser.md
• network.md
• script-development.md
• site-notes.md