@tangle-network/browser-agent-driver
Advanced tools
LLM-driven browser agent and bad CLI for UI automation, testing, and evaluation
General-purpose agentic browser automation. Completes real user outcomes on any website — search, extract, fill forms, compare prices, navigate complex UIs.
# CLI installer — installs the `bad` command, downloads Chromium, adds PATH (Node.js 20+)
curl -fsSL https://raw.githubusercontent.com/tangle-network/browser-agent-driver/main/scripts/install.sh | sh
# or via npm
npm install -g @tangle-network/browser-agent-driver
npx playwright install chromium
# as a library
pnpm add @tangle-network/browser-agent-driver
pnpm add -D playwright
Do not install the unscoped bad package from npm. It is unrelated to Tangle. The bad command is installed by @tangle-network/browser-agent-driver.
# Run a task
bad run --goal "Find the cheapest flight from NYC to London on Jan 15" \
--url https://www.google.com/travel/flights
# With vision (screenshot-based decisions)
bad run --goal "Compare MacBook Air prices" --url https://apple.com \
--observation-mode hybrid
# Test suite from case file
bad run --cases ./my-tests.json --concurrency 4
import { chromium } from 'playwright'
import { PlaywrightDriver, BrowserAgent } from '@tangle-network/browser-agent-driver'
const browser = await chromium.launch({ channel: 'chrome' })
const page = await browser.newPage()
const driver = new PlaywrightDriver(page)
const agent = new BrowserAgent({
driver,
config: {
model: 'gemini-2.5-flash',
provider: 'google',
observationMode: 'hybrid', // vision + DOM
plannerEnabled: true, // plan-then-execute
},
})
const result = await agent.run({
goal: 'Find the top 3 trending repositories on GitHub',
startUrl: 'https://github.com/trending',
})
console.log(result.success, result.reason)
await browser.close()
Goal → DOM Planner (1 LLM call with screenshot)
→ N deterministic steps (click, type, fill, navigate)
→ If deviation: vision per-action loop
→ Observe (a11y tree + screenshot + SoM labels)
→ LLM decides action (ref-based, coordinate, or label)
→ Execute + verify expected effect
→ Recovery on failure (strategy shift, form reset retry, search fallback)
→ Goal verification (LLM or fast-path with script evidence)
→ Complete with structured result
Recovery is automatic: cookie consent, modal blockers, A-B-A-B oscillation loops, form field resets, date picker stalls, and CAPTCHA challenges are handled before the agent continues.
@ref IDs). Observation modes: dom (fastest), vision, hybrid (most reliable).channel: 'chrome', real TLS/JA3 fingerprint), Patchright (CDP leak patches), Bezier mouse humanization, fingerprint hardening (webdriver, WebGL, canvas noise, screenX/Y), 99+ analytics domains blocked. Unblocks most Cloudflare/Akamai WAF setups with zero configuration.{ captcha: { enabled: true, maxAttempts: 5 } }.{ parallelTabs: { enabled: true, maxTabs: 3 } }.planner / executor / verifier / supervisor) across openai, anthropic, google, claude-code, codex-cli, zai-coding-plan, cli-bridge, sandbox-backend. Roles fall back to the main model when not configured.Vision-powered design quality analysis with closed-loop improvement:
bad design-audit --url https://your-app.com # audit any URL
bad design-audit --url https://your-app.com --pages 10 # multi-page crawl, systemic detection
bad design-audit --url http://localhost:3000 --evolve claude-code --project-dir ~/my-app # auto-fix
Reports rank Top Fixes by ROI — the highest-leverage changes scored by (impact * blast / effort).
A built-in MetaMask workflow for teams testing DeFi apps — a deliberate specialization, not the general-purpose path:
pnpm wallet:setup # download MetaMask
pnpm wallet:onboard # automate first-run wizard
pnpm wallet:anvil # start Anvil mainnet fork (100 ETH + 10 WETH + 10k USDC)
pnpm wallet:validate # run wallet test suite
Supports connect, swap, supply workflows across Uniswap, Aave, SushiSwap, 1inch. See the wallet guide.
Create bad.config.ts (or .js, .mjs) in your project root:
import { defineConfig } from '@tangle-network/browser-agent-driver'
export default defineConfig({
model: 'gemini-2.5-flash',
provider: 'google',
observationMode: 'hybrid',
plannerEnabled: true,
headless: true,
concurrency: 4,
maxTurns: 30,
outputDir: './test-results',
})
Auto-detected by CLI and SDK. CLI flags override config values.
The default provider is credential-aware: with no explicit provider, bad uses OpenAI when OPENAI_API_KEY is set and otherwise falls back to the keyless claude-code provider. The bench-validated default model is gemini-2.5-flash (Google) — see Benchmarks. Key options:
| Option | Default | Description |
|---|---|---|
provider | credential-aware | openai if OPENAI_API_KEY set, else claude-code |
model | per-provider | LLM model (gemini-2.5-flash is the bench-validated choice) |
observationMode | 'dom' | 'dom', 'vision', or 'hybrid' |
plannerEnabled | false | Plan-then-execute mode |
maxTurns | 30 | Max turns per task |
proxy | — | Proxy URL (also BAD_PROXY_URL env) |
models | — | Per-role model overrides |
See Configuration Reference for all options.
bad run [options] # Run tasks
bad snapshot --url <url> # Headless accessibility-tree dump (no LLM)
bad design-audit [options] # Design quality analysis
bad view <run-dir> # Open session viewer
bad competitive [options] # Head-to-head framework comparison
Full flag reference (run modes, execution profiles, auth sessions, adaptive model routing): docs/guides/cli.md.
import {
BrowserAgent,
PlaywrightDriver,
SteelDriver,
TestRunner,
MultiActorSession,
defineConfig,
DesignAuditor,
detectCaptcha,
solveCaptcha,
type AgentConfig,
type Scenario,
type AgentResult,
} from '@tangle-network/browser-agent-driver'
Runnable recipes live in examples/: SDK quickstart, authoring a bench task, replay-cache CI, the GitHub Action, and shareable run videos.
Current bench (2026-10-11, gemini-2.5-flash, headless, external oracle, 5-task competitive corpus × 3 reps + n=5 variance arm): 15/15 main + 10/10 arm, $0.0223/run, 17.9s wall, 30% replay-cache hit rate. browser-use on the same corpus: 12/15 @ $0.0126/run. Cost ratio 1.8×, accepted asymptote 1.3–1.6× (1.0× would sacrifice extraction accuracy and the replay moat). Replay-cache reruns cost ~10–20% of a live run with zero decide calls. Full methodology: docs/bench-2026-10-11-hillclimb-program.md; competitive evaluation: docs/COMPETITIVE-EVAL.md.
Run it:
pnpm bench:compete
The agent loop is decoupled from the browser via the Driver interface:
// Local Playwright (default)
const driver = new PlaywrightDriver(page)
// Steel cloud browser (anti-bot, residential proxies, CAPTCHA)
const driver = await SteelDriver.create({
apiKey: process.env.STEEL_API_KEY,
sessionOptions: { useProxy: true, solveCaptcha: true },
})
// Any Driver implementation works
const agent = new BrowserAgent({ driver, config })
- uses: tangle-network/browser-agent-driver/.github/actions/design-audit@main
with:
url: ${{ steps.deploy.outputs.preview_url }}
pages: 5
fail-on-score-below: '6.5'
evolve: claude-code
Posts Top Fixes as a PR comment, uploads the full report as an artifact, optionally fails on score regressions.
bad view audit-results/stripe.com-1775502457141
Web UI with per-turn screenshots, action JSON, reasoning, element highlights. A run's report.json is also a complete trace that renders into a shareable video via run-capsule — see examples/run-capsule.md.
Agents integrating Browser Agent should start from the live manifest at https://browser.tangle.tools/llms.txt. The same discovery manifest (llms.txt + tangle-agent.json) ships in the npm package under discovery/.
Use the canonical admitted local signoff for frozen installation, type-checked build, architecture/release-plan checks and browser-enabled integration qualification. It runs against the exact committed revision; paid benchmarks remain separately authorized experiments.
Publishing is automated via Changesets + OIDC trusted publishing: add a changeset with pnpm changeset, merge the release PR, npm publish fires with provenance attestation.
Dual-licensed under MIT and Apache 2.0. See LICENSE.
FAQs
LLM-driven browser agent and bad CLI for UI automation, testing, and evaluation
The npm package @tangle-network/browser-agent-driver receives a total of 0 weekly downloads. As such, @tangle-network/browser-agent-driver popularity was classified as not popular.
We found that @tangle-network/browser-agent-driver demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Threat Research
Malicious Firefox extensions mimic Phantom, Jupiter, and Bitget wallets to steal recovery phrases and private keys, with one fetching its payload remotely.
Product
Socket Threat Intel now shows which malware campaigns were blocked or detected in your organization, with links to scans and Firewall events.
Security News
Fixes for eMudhra and Brotli are out. Getting them everywhere they’re needed means tracking down bundled libraries, runtimes, and certificate stores.