{
  "markdown": "# Webpilot\n\n[![npm](https://img.shields.io/npm/v/h17-webpilot)](https://www.npmjs.com/package/h17-webpilot)\n[![Socket Badge](https://socket.dev/api/badge/npm/package/h17-webpilot)](https://socket.dev/npm/package/h17-webpilot)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)\n[![Node](https://img.shields.io/node/v/h17-webpilot)](https://www.npmjs.com/package/h17-webpilot)\n[![Publish](https://github.com/hugopalma17/webpilot/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/hugopalma17/webpilot/actions/workflows/npm-publish.yml)\n\nWebpilot is a browser tool.\n\nIt launches a real Chromium-based browser with a local extension runtime, exposes a WebSocket protocol, and lets a user, script, or LLM drive that browser through the same command surface.\n\n**The primary interface is the live DOM — not screenshots.** `discover`, `html`, and `q` give you real page structure, real selectors, and real handles. Screenshots exist as a fallback for when layout or visual rendering is the actual question. For everything else, read the DOM.\n\n**The primary CLI workflow is `webpilot start`, then `webpilot -c ...` commands.** The interactive REPL exists for manual testing and debugging; scripts and agents should prefer one-shot commands.\n\nWhat Webpilot does:\n- starts and controls a real browser — no CDP, no detectable debugging port\n- exposes the live DOM directly: navigation, element discovery, querying, interaction, cookies\n- provides configurable cursor, click, typing, and scroll behavior\n- works from the CLI, raw WebSocket, Node, or an MCP adapter\n\nWhat Webpilot does not do:\n- decide what to do next\n- ship a tuned human profile\n- ship site strategy, retries, or route doctrine\n\nThe user or LLM decides the workflow. Webpilot provides the browser runtime and commands.\n\n## Install\n\n```bash\nnpm install -g h17-webpilot\n```\n\n## Quick Start\n\n### 1. Start\n\n```bash\nwebpilot start\n```\n\nIf no config exists, the first run will detect installed browsers, ask you to choose one, and generate `~/h17-webpilot/config.js`.\n\nUse `webpilot start -d` for an append-only session log (`~/h17-webpilot/webpilot.log` by default).\n\n### Recommended Browser Setup\n\nIf you want to browse normally while Webpilot is automating in parallel, use a dedicated Chromium-family browser for Webpilot and keep your everyday browser separate. A clean split is Helium, Chromium, Edge, or Vivaldi for Webpilot; Chrome (or your normal browser) for you. That way Webpilot owns its browser binary, profile, and process tree while your personal browser remains independent.\n\nIn `~/h17-webpilot/config.js`, point `browser` at the dedicated Webpilot browser and keep `profile` dedicated to Webpilot. Example macOS Helium config:\n\n```javascript\nmodule.exports = {\n  browser: \"/Applications/Helium.app/Contents/MacOS/Helium\",\n  profile: \"~/h17-webpilot/profile\",\n};\n```\n\nIf you are not browsing manually at the same time, using the same browser install with Webpilot's dedicated profile is fine.\n\n### 2. Use the tool\n\n```bash\nwebpilot -c go example.com\nwebpilot -c discover\nwebpilot -c click h1\nwebpilot -c wait h1\nwebpilot -c html\nwebpilot -c cookies load ./cookies.json\n```\n\nUse the same loop every time:\n1. inspect\n2. act\n3. verify\n\n## CLI\n\n```bash\nwebpilot -c go example.com      # single command, preferred for scripts/agents\nwebpilot                        # manual/debug REPL\nwebpilot start                  # launch browser + WS server\nwebpilot start -d               # launch with session logging\nwebpilot stop                   # stop running server\n```\n\nCore commands:\n- `go <url>`: navigate\n- `discover`: list interactive elements with handles\n- `q <selector>` / `query <selector>`: query elements\n- `wait <selector>`: wait for a selector\n- `click <selector|handleId>`: safe click\n- `type [selector|handleId] <text>`: target the element, focus it, then type with the configured public profile\n- `clear <selector>`: clear an input\n- `key <name>` / `press <name>`: send a key\n- `sd [px] [selector]` / `su [px] [selector]`: scroll\n- `html`: read page HTML\n- `ss`: save a screenshot — use when layout or visual rendering is the question, not DOM structure\n- `cookies`: dump cookies\n- `cookies load <file>`: load cookies from a JSON array file\n- `frames`: list frames\n\nSingle commands can be passed as one quoted command string or as trailing argv after `-c`:\n\n```bash\nwebpilot -c \"type el_2 hello world\"\nwebpilot -c type el_2 hello world\nwebpilot -c .http go https://example.com\n```\n\nQuote typed text only when quote characters are part of the text you want typed. In the interactive REPL, `.http` toggles response-event printing for the rest of that CLI session. For one-shot commands, prefix the command with `.http` because each `-c` invocation is its own client process; this is most useful around navigation/page-load commands.\n\nRaw mode stays available:\n\n```bash\nwebpilot -c 'human.click {\"selector\": \"button[type=submit]\"}'\nwebpilot -c '{\"action\": \"dom.getHTML\", \"params\": {}}'\n```\n\n## WebSocket Protocol\n\nConnect to `ws://127.0.0.1:7331` and send JSON:\n\n```json\n{ \"id\": \"1\", \"action\": \"tabs.navigate\", \"params\": { \"url\": \"https://example.com\" } }\n```\n\nThe server requires the per-run token written to `~/h17-webpilot/token`. Pass it as a query parameter on the connection URL, for example `ws://127.0.0.1:7331/?token=<token>`. The CLI and Node API read and attach this token for you. The bundled runtime extension reads the same per-run token from a generated extension-private `token.json` and bypasses extension resource caches when it loads that file. See the Security model section below.\n\nCapability groups:\n- `tabs`\n- `dom`\n- `human`\n- `cookies`\n- `events`\n- `framework`\n\nFull reference: `protocol/PROTOCOL.md`\n\n## Node API\n\nThe Node API is a wrapper over the same WebSocket protocol.\n\n```javascript\nconst { startWithPage } = require('h17-webpilot');\n\nconst { page } = await startWithPage();\nawait page.navigate('https://example.com');\nawait page.query('h1');\nawait page.click('h1');\nawait page.waitFor('body');\n```\n\nUseful methods:\n- `navigate(url)` / legacy `goto(url)`\n- `query(selector)` / legacy `$(selector)`\n- `queryAll(selector)` / legacy `$$(selector)`\n- `waitFor(selector)` / legacy `waitForSelector(selector)`\n- `read()` / legacy `content()`\n- `click(...)` / legacy `humanClick(...)`\n- `type(...)` / legacy `humanType(...)`\n- `scroll(...)` / legacy `humanScroll(...)`\n- `clearInput(...)` / legacy `humanClearInput(...)`\n- `pressKey(key)`\n- `configure(config)` / legacy `setConfig(config)`\n\n## Config\n\nConfig is loaded from `~/h17-webpilot/config.js` (or `config.json`). Override with `--config <path>`.\n\nPublic config is split into:\n- `framework`: runtime behavior, debug toggles, handle retention\n- `human`: cursor, click, typing, scroll, and avoid rules\n\nThe public package exposes a lot of knobs on purpose. The user decides how much to tune. The package does not ship a strong profile.\n\nExample:\n\n```javascript\nmodule.exports = {\n  framework: {\n    debug: {\n      cursor: true,\n      sessionLogPath: '~/h17-webpilot/webpilot.log',\n    },\n  },\n  human: {\n    calibrated: false,\n    profileName: 'public-default',\n    cursor: {\n      spreadRatio: 0.16,\n      jitterRatio: 0,\n      stutterChance: 0,\n      driftThresholdPx: 0,\n      overshootRatio: 0,\n    },\n    click: {\n      thinkDelayMin: 35,\n      thinkDelayMax: 90,\n      maxShiftPx: 50,\n    },\n    type: {\n      baseDelayMin: 8,\n      baseDelayMax: 20,\n      variance: 4,\n      pauseChance: 0,\n      pauseMin: 0,\n      pauseMax: 0,\n    },\n  },\n};\n```\n\nAuth/session bootstrap example:\n\n```javascript\nmodule.exports = {\n  browser: \"/Applications/Chromium.app/Contents/MacOS/Chromium\",\n  boot: {\n    cookiesPath: \"./cookies.json\",\n    commands: [\n      \"go https://hugopalma.work\",\n      \"cookies load ./cookies.json\",\n      { action: \"framework.getConfig\", params: {} }\n    ],\n  },\n};\n```\n\n`boot.cookiesPath` loads a cookie jar before commands run.\n`boot.commands` accepts:\n- command strings like the CLI shorthands\n- `cookies load <file>` entries\n- raw objects: `{ action, params, tabId? }`\n\nThese defaults do not represent a human profile:\n- typing is very fast\n- overshoot is off\n- jitter is off\n- drift is off\n\nThey are there to show what is configurable. The package does not ship your final values.\n\n## Tested Browsers\n\nTested browsers:\n- Helium\n- Chromium\n- Google Chrome\n\n### Linux Desktop Display\n\nWebpilot launches normal Chromium with an unpacked extension; it does not switch to headless mode. On Linux, if the shell has no `DISPLAY` but `~/.Xauthority` contains a display entry, Webpilot uses the detected desktop display and prints a yellow `[WARN]` showing the `DISPLAY` and `XAUTHORITY` it selected. If no display can be detected, it warns and waits for real readiness to fail instead of claiming the server is ready.\n\n## Security model\n\nWebpilot is a local tool. The browser, the WebSocket server, and the client all run on the same machine, and the server is built to stay that way.\n\n- Loopback only. The WebSocket server binds to `127.0.0.1`, so it does not accept connections from other machines on the network.\n- Per-run token. Each `webpilot start` generates a fresh token, writes it to `~/h17-webpilot/token`, and refuses any WebSocket connection that does not present it. The CLI, the Node API, and the bundled runtime extension read that token automatically. The extension token config is extension-private, fetched with cache bypass, and rotates every run with the local token.\n- Origin rejection. The server rejects WebSocket handshakes that carry a web-page `Origin` header, so a malicious web page cannot reach the server even from the same machine.\n\nTwo behaviors that automated scanners sometimes flag are intentional and central to what the tool does:\n\n- Script execution in the page. The `dom.evaluate` command runs caller-supplied JavaScript in the page. That is the feature. Driving a browser means running code in pages you navigate to. Execution only happens for commands you send over the authenticated local socket.\n- Cookies over the socket. The `cookies` command reads browser cookies and returns them over the WebSocket. The endpoint is the local `127.0.0.1` server described above, not a remote host. Nothing is sent off the machine. Cookie access exists so you can save and restore your own sessions.\n\nIf you run an old version, upgrade. The token, loopback bind, and Origin rejection were added together. See SECURITY.md for how to report issues.\n\n## Limits\n\n- Defaults are for demonstration and development, not for behavior parity.\n- The browser tool does not decide workflows.\n- The user or LLM still has to choose selectors, waits, retries, and verification steps.\n- `dom.evaluate` may hit CSP restrictions on some sites. DOM reading and interaction still work through the isolated content-script path.\n\n## Skill Usage\n\n`SKILL.md` explains how an LLM should use Webpilot as a browser tool.\n\n## License\n\nApache 2.0\n",
  "bytes": 10956,
  "sha": "0cfd11a5226da52445256e7d687292e344ceb63add0c0c1766d711c94eafb420",
  "repo_slug": "hugopalma17/webpilot",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_hugopalma17_webpilot_d7f95255/readme"
}