Taprun

Your scraper is broken right now. You just don't know it yet.

Homepage  |  Blog  |  140+ Skills  |  中文

---

Taprun is local-first browser automation that runs in your browser, not someone else's cloud. Point it at any site; your agent inspects the page once, compiles a deterministic program, and replays it forever — zero AI tokens at runtime, same result every call. Your cookies and login sessions never leave your machine — by architecture, not policy. Works with Claude Code, Cursor, Cline, Windsurf, and any MCP host. Runs in real Chrome (login sessions) or headless Playwright. Health contracts catch silent failures. Structural state diffs tell you exactly what changed. tap doctor detects breakage before your data goes stale — not three days later.

Forge:    AI inspects the site → compiles a .tap.js program       (one-time cost)
Run:      The program executes instantly, same result every time   ($0, zero AI)
Monitor:  tap doctor checks health contracts + structural state diffs  (catches breakage)
Heal:     AI reads diagnostics and patches the program            (only when needed)

MCP is the authoring layer. tap.run is the execution layer. AI participates during forge (one-time). Execution is pure code — zero tokens, deterministic output. 140+ pre-built skills across 68+ sites — Reddit, GitHub, Hacker News, LinkedIn, Twitter, YouTube, Producthunt, and more — or forge your own from any URL. One binary, zero dependencies.

Use cases: AI agent browser automation · scheduled web scraping · structured data extraction · content monitoring · login-required site automation · multi-site data pipelines · reliability monitoring for long-running agents.

Get Started

1. Install

Zero-install via npx (any machine with Node):

npx -y @taprun/cli --version

The first run downloads the matching platform binary (~30MB) and caches it. Subsequent calls are instant.

Permanent install via curl (macOS / Linux):

curl -fsSL https://taprun.dev/install.sh | sh

Platform	Download
macOS (Apple Silicon)	tap-macos-arm64
macOS (Intel)	tap-macos-x64
Linux	tap-linux-x64
Windows	tap-windows-x64.exe

2. Connect to Your AI Agent

Works with Claude Code, Cursor, Windsurf, or any MCP-compatible agent — no extension needed:

{ "mcpServers": { "tap": { "command": "npx", "args": ["-y", "@taprun/cli", "mcp", "start"] } } }

Or auto-configure all installed agents:

tap mcp connect

3. Go

tap github/trending              # GitHub trending repos
tap hackernews/hot               # Hacker News front page
tap weibo/hot                    # 微博热搜
tap xiaohongshu/search --keyword "AI"  # 小红书搜索

Or just ask your AI agent:

You:   What's trending on GitHub today?
Agent: Here are today's top repos — React compiler hit 734 stars...

You:   Forge a tap for Douban top 250 movies
Agent: Done. Run `tap douban/top250` anytime — $0 per run.

Optional: Chrome Extension (for login-required sites)

Most taps work without login. For sites that need your session (Xiaohongshu, Zhihu, etc.), install the Chrome Extension from the Chrome Web Store.

Optional: Embed in your agent code (TypeScript / Python)

Skip MCP — call Tap directly from your own loop:

import { run, doctor, forge } from "@taprun/sdk";
const rows = await run("hackernews/top");

from taprun import run, doctor, forge
rows = run("hackernews/top")

Compile from a browser-use trajectory at zero LLM tokens:

from taprun import forge
forge(trajectory=agent.history, site="example", name="dashboard")

Packages: @taprun/sdk (npm) · taprun (PyPI).

Have an existing Playwright / Puppeteer / Stagehand script?

Don't rewrite. Convert with one of the open-source adapters — drop your existing source in, get a Tap-compatible .tap.json plan out:

# Existing Playwright script (47M weekly npm downloads — most likely the one you have)
npm install @taprun/from-playwright @taprun/spec
node -e "import('@taprun/from-playwright').then(m => console.log(m.playwrightToTap(require('fs').readFileSync('tests/login.spec.ts','utf8'), {site:'example', name:'login'})))"

# Or scaffold a new starter from scratch
npx create-tap-script github/trending https://github.com/trending

Adapter	Source format	Coverage
@taprun/from-playwright	.ts/.js Playwright tests	8 page.* APIs (goto/click/fill/type/press/waitForSelector/waitForTimeout/screenshot)
@taprun/from-puppeteer	.ts/.js Puppeteer scripts	7 page.* APIs + page.keyboard.press
@taprun/from-stagehand	.ts/.js Stagehand scripts	Hybrid: deterministic page.* mapped to plan ops; NL act/extract/observe flagged allowUnverifiable for honest doctor verdicts
create-tap-script	(none — scaffolder)	Generates a starter .tap.json envelope from <site>/<name> <url>

The format itself is documented at @taprun/spec (TypeScript types + W3C Annotation MUST-validator + JSON Schema 2020-12 + 10-fixture conformance suite). Plan-v1 reference: taprun.dev/spec/plan-v1. Source for all five packages: packages/.

What Can You Do?

Read — Extract data from any website

tap reddit/hot                   # Reddit front page
tap bilibili/trending            # Bilibili trending
tap arxiv/search --keyword "LLM" # arXiv papers

Write — Operate any website

tap xiaohongshu/publish --title "My Note" --images photo.jpg
tap zhihu/publish --title "My Article" --content "..."

Watch — Monitor changes

tap watch github/trending --every 5m

Compose — Chain like Unix pipes

tap github/trending | tap filter --field stars --gt 500 | tap table

Forge — Create new automations with AI

tap forge "get Hacker News top stories"           # BYOK Claude / GPT
tap forge https://news.ycombinator.com            # API detected — compiled without AI

Bring your own model — works with Claude, OpenAI, DeepSeek, or any OpenAI-compatible endpoint including local Ollama / LM Studio for fully offline forge:

tap config set ai.baseUrl http://localhost:11434/v1
tap config set ai.key ollama
tap config set ai.model llama3.1
tap forge "scrape arxiv recent papers"            # 0 bytes leave your machine

How It Works

                        ┌─ Chrome      (your real browser sessions)
You → AI → Taprun ──────┤─ Playwright  (headless, server, CI/CD)
     compile            └─ macOS       (native desktop apps)

1. You describe what you want (natural language or URL)
2. AI compiles it into a .tap.js program — plain JavaScript, version-controlled
3. Taprun runs the program on any of three runtimes — forever, at $0

Every successful compilation makes the next one faster. 140+ community skills mean your agent already knows 68+ websites.

Community Skills

tap-skills — 140+ skills, open source.

Category	Examples
Trending	GitHub, Hacker News, Reddit, Product Hunt, Bilibili, Zhihu, Weibo, Xiaohongshu
Search	arXiv, Reddit, X, Zhihu, Weibo, Xiaohongshu, Bilibili, Medium
Read	Zhihu threads, Bilibili videos, Xiaohongshu notes, WeRead books
Write	X posts, Xiaohongshu notes, Zhihu articles, Dev.to, LinkedIn
Monitor	Price tracking, stock data, competitor analysis

tap doctor    # Health check — catches silent failures before your data goes stale
tap update    # Install / update all skills
tap list      # See everything available

How Taprun Compares

	Taprun	AI Browser Agents	Traditional Scrapers
AI cost per run	$0 (compile once)	Tokens every run	Free
Accuracy	Deterministic	Varies per run	Deterministic
Silent failure detection	Health contracts + structural state diff	None	None
Breakage diagnostics	tap doctor — exact diff of what changed	None	Manual spot checks
Detection risk	Low (real browser sessions)	High	High
Runtimes	3 (Chrome + Playwright + macOS)	1	1
Code inspectable	.tap.js — git diff, debug, version	Black box / ephemeral	Fragile scripts
MCP native	Yes (authoring layer only — execution is zero tokens)	No	No

Local-first by architecture

Taprun runs in your browser, not someone else's cloud. The Chrome extension reuses your live login sessions; cookies, auth tokens, and credentials never leave your machine. This is a structural choice, not a marketing claim:

Concern	Cloud-first browser SDKs	Taprun (local-first)
Where do logged-in cookies live?	On the cloud vendor's servers	Only in your local browser
What does the AI see?	The full session + your data	Only the page DOM during forge time
Compliance with noindex / robots.txt / TOS	Vendor signs ToS for you	Your account, your terms
Internal / intranet sites	Need VPN tunneling	Just open the page
Decommission risk	Vendor goes down → your scrapers stop	Local code keeps running

Layer	Protection
Sandbox	Programs run with zero permissions — no file, network, or system access
Static Analysis	CI blocks dangerous patterns before they reach users
Local-only	Your data, sessions, and API keys never leave your machine — architecturally

See SECURITY.md for the full threat model.

Contributing

The easiest way to contribute: forge a new tap. One .tap.js file is all it takes.

See CONTRIBUTING.md for details.

Roadmap

• 140+ community skills across 68+ sites
• 3 runtimes — Chrome, Playwright, macOS
• Unix pipes — tap A | tap B
• Watch mode — monitor changes over time
• Doctor — health contracts, fingerprint diffs, automatic diagnostics for broken taps
• One-command setup — tap mcp connect configures all AI agents
• Android runtime
• iOS runtime
• Concurrency control — deterministic coordination for M agents operating shared accounts in parallel

Support

• GitHub Discussions — Q&A, ideas, show & tell
• [email protected] — licensing, private feedback, consulting
• Issues — bug reports

License

Chrome Extension & docs: MIT. Community skills: MIT.

Star History

Star History Chart