Tap Web

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:

Decision flow:

1. Check for a site script first: tap site list / tap site search <query>
2. If you just need readable content: tap fetch <url>
3. 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

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 "me@example.com" @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