Show HN: WebCap – Reusable web capabilities for AI agents

Script-first web capabilities for AI agents. Run in-page scripts, save workflows as reusable capabilities, and generate AI-native userscripts.

Web-Capability is a local-first browser automation toolkit for agents. It lets agents inspect real browser tabs, run reusable in-page scripts, save successful workflows for later command-line use, and turn natural-language browser requests into AI-native userscripts.

Agents interact with Web-Capability through the web-cap

CLI. The CLI manages the required local runtime automatically, so users do not need a separate startup command.

Install the Web Cap skill with the

skills

CLI:

npx skills add edgestorage/web-cap

The skill includes the

web-cap

CLI installation and connection-check workflow for agents. - Install the Web Cap browser extension:

• Open the Web Cap Releasespage. - Download the Chrome extension zip asset, named like *chrome*.zip

. - Unzip the downloaded extension asset.

• Open chrome://extensions

in Chrome. - Enable Developer mode.

• Drag the unzipped extension folder into the extensions page.
• Open the Web Cap extension details and enable Allow User Scripts

.

• Open the

Check that the CLI can see the browser runtime:

web-cap session-status

Run a reusable script from web-cap-hub to summarize the comments on the first five Hacker News posts from the current page with less page exploration, fewer tokens, and faster execution.

Hide the Top live games

block on YouTube Gaming with one sentence, and keep it hidden on future visits.

For agent workflows, the Web Cap skill provides the recommended CLI setup path. To install the CLI directly, use npm:

npm install -g web-capability

The installed command is web-cap

:

web-cap --help
web-cap session-status

• Browser extension runtime for real Chromium-based browser tabs.
• Command-line interface for script execution, registration, tab creation, and user handoff observation.
• Playwright-style page helpers for common operations such as inspect, wait, click, fill, query, and text reading.
• Local script registry for reusable browser workflows.
• AI-native userscript generation for persistent, page-specific browser changes.
• Browser tab creation and event watching commands for agent workflows.
• Local-first state storage by default.

Web Cap can run reusable capability scripts from a local .web-cap/

directory. The shared Web Cap Hub repository collects ready-to-use scripts for common websites and provides examples for writing new site-specific workflows.

To reuse scripts from the hub:

git clone https://github.com/edgestorage/web-cap-hub.git
cd web-cap-hub

web-cap session-status
web-cap script-execute \
  --tab-id <tab-id> \
  --script-file .web-cap/github.com/read-repository-summary.js \
  --input '{"owner":"edgestorage","repo":"web-cap"}'

See the Web Cap Hub README for the current script collection and contribution guidelines.

Many browser automation tools expose a fixed set of direct actions: click this selector, fill that input, read this text, take a screenshot. Web Cap takes a script-first approach instead.

Agents can run JavaScript inside the page with Playwright-style helpers and register useful scripts as reusable browser skills. This makes Web Cap better suited for workflows where an agent needs to inspect page structure, adapt to product-specific UI, and turn a successful operation into something it can run again later.

Web Cap is not designed to make agents rediscover the same browser workflow every time. Its core value is turning verified browser operations into reusable scripts and reusable workflows.

For recurring pages and tasks, agents can reuse stable workflows instead of repeatedly reading the page, planning each step, finding the right controls, and recovering from mistakes. This can improve accuracy and execution speed while reducing token usage and time spent on repeated browser exploration.

In this sense, Web Cap works well as a browser capability layer for Codex, Claude Code, or other local agent tools: the model can focus on understanding goals and making decisions, while stable browser operations are handled by local reusable automation.

Compared with action-first browser tools, Web Cap focuses on:

• In-page execution, so scripts can work directly with the DOM and page state.
• Reusable capabilities, so successful scripts can be saved and run again.
• Playwright-style page helpers for page inspection and interaction.
• Optional post-execution observation, so script runs can return evidence about what changed on the page when evidence collection is enabled.
• Local persistence, so agent-learned workflows can survive beyond a single run.
• CLI access, so agents can use the same browser capabilities from normal command-line workflows.

Web Cap can observe the page around script execution when evidence collection is enabled. It snapshots visible elements before a script runs, tracks DOM mutations while it runs, then snapshots changed areas afterward and returns a visible-elements diff with added

, removed

, and updated

items. Execution evidence can also include browser-side events such as opened tabs, URL changes, reloads, scroll changes, managed clicks, keyboard input, and script calls.

That means an agent does not only get a script's declared JSON result. It can also inspect what the browser visibly did after the script, which is useful for verification, recovery, and deciding whether a newly successful script should be registered as a reusable capability.

• Page targeting: script definitions include target sites, URL patterns, page hints, tags, type, status, and version, so agents can select the right capability and avoid running a script on the wrong page.
• Two script types: read

scripts inspect or extract page state, whileact

scripts operate on the page or trigger browser-side changes. - User handoff observation: wait-events

waits while a user completes a browser action, then streams the resulting interaction path as JSON Lines. Use it when an agent has reached a step that requires user action and needs the observed clicks, input/change/submit activity, URL changes, or state to infer what the user did next. - Local execution history: inline scripts are tracked locally with status and result metadata. Temporary script ids remain callable while they are in the latest local history entries.

• Success-gated registration: --register

only persists a script when its execution result includesok: true

, which helps keep the reusable script registry clean. - Tab-aware execution: commands can target a specific --tab-id

, while default execution follows the active connected browser tab.

This roadmap outlines the planned development directions for Web Cap and Web Cap Hub.

Provide quick installation and download support for reusable scripts.

Provide Firefox browser extension support.

Reduce dependency on the Node.js and npm environment, and explore simpler installation, build, and distribution paths.

Provide an in-browser AI chat entry point that connects to local tools such as Codex and Claude Code for actual execution.

Move heavier TypeScript compilation-related responsibilities from the browser extension to the client to reduce extension size and complexity.

Agent
   |
   | CLI command
   v
Web Cap CLI
   |
   v
Managed local runtime
   |
   | WebSocket
   v
Browser extension
   |
   v
Real browser tab

The browser extension connects to the local runtime and executes commands against normal browser tabs. Agents call the CLI, and the CLI handles runtime startup and connection details automatically.

extension/

• browser extension entrypoints and runtime code.lib/

• CLI, local runtime, script registry, and orchestration logic.shared/

• shared protocol, script schema, and validation helpers.skills/

• Agent Skills installable with theskills

CLI.tests/

• Vitest coverage for CLI, runtime behavior, browser command contracts, and extension helpers.scripts/

• project utilities and generated-runtime helpers.

• Node.js 20 or newer

• pnpm 9.x

• A Chromium-based browser for the current extension runtime

Install dependencies:

pnpm install

Start the extension development build:

pnpm dev

Load the generated extension from WXT's output directory, then open a normal http

or https

page.

Run the source CLI during development:

pnpm cli session-status

A typical agent flow is:

• Use script-execute

to run script code against the connected browser. - Add --register

toscript-execute

when a successful inline script should become reusable.

Execute script code in the selected browser tab. Scripts receive one object argument and return one JSON object.

script-execute

accepts optional execution settings such as --timeout-ms

, --script-file

, --input-file

, --no-evidence

, and --register

. During execution, scripts can use the injected Playwright-style page

helper. --register

saves the inline script only after execution succeeds with ok: true

.

Web Cap also includes commands such as browser-new-tab

, session-status

, and wait-events

for agent workflows that need tab control, or need to wait for a user to complete a browser step and inspect the resulting action path.

Scripts are JavaScript functions with JSON-compatible inputs and outputs:

export default async function (input) {
  const title = await page.title();
  const text = await page.locator(input.selector).textContent();

  return {
    ok: true,
    title,
    text,
  };
}

The runtime injects a Playwright-style page

helper while the script executes. Common APIs include page.locator(...)

, page.getByRole(...)

, locator.click()

, locator.fill()

, locator.textContent()

, and locator.waitFor()

.

For controlled multi-page scripts, cap.goto(url, nextInput)

navigates to url

and reruns the same script with exactly nextInput

as the next input

. Page/script state is lost across the navigation, so pass every cross-page field you need, such as step

, index

, urls

, and accumulated results

, through nextInput

explicitly.

Run a one-off script:

web-cap script-execute \
  --tab-id 1 \
  --script "export default async function (input) { return { ok: true, input }; }" \
  --input '{"hello":"world"}' \
  --timeout-ms 30000

Use files for larger payloads:

web-cap script-execute \
  --tab-id 1 \
  --script-file ./script.js \
  --input-file ./input.json \
  --no-evidence

Common CLI commands:

web-cap session-status
web-cap script-execute --tab-id 1 --script-file ./script.js --input-file ./input.json --register
web-cap browser-new-tab --url https://example.com --active true
web-cap wait-events --duration-ms 10000

For local source development, replace web-cap

with pnpm cli

.

JSON-producing commands print compact single-line JSON by default. Use --pretty

to print formatted JSON for visual inspection.

Persistent CLI configuration is managed with web-cap config

and stored in local state. Useful options include:

Key	Default	Example	Effect
evidence
common
web-cap config set evidence events,visibleElements
Controls script execution evidence. Use common , all , or a comma-separated list of events and visibleElements . Pass --no-evidence to script-execute to disable evidence for one run.
mouseTrajectorySimulation
false
web-cap config set mouseTrajectorySimulation true
When enabled, browser-level managed mouse clicks send a multi-step movement path before press/release.
activateTabOnScriptExecute
false
web-cap config set activateTabOnScriptExecute true
Activates the target tab before script execution.

evidence

can also be passed per request through options.evidence

when using script_execute

.

Web Cap stores local state under ~/.web-cap/

by default. Set WEB_CAP_STATE_DIR

to use another directory.

Local state includes registered scripts, recent script execution metadata, and browser session information needed by CLI commands.

Build the browser extension:

pnpm build

Build the npm CLI package:

pnpm build:npm

After building the npm package, the web-cap

executable is available at dist/cli.js

:

node dist/cli.js --help

Create extension zip packages:

pnpm zip
pnpm lint
pnpm typecheck
pnpm test
pnpm build

The repository includes a build workflow at .github/workflows/build.yml

. It runs lint, typecheck, and tests, then uploads browser extension build artifacts and an npm package tarball.

When a version tag matching v*

is pushed, the workflow also creates a GitHub Release and uploads the browser extension zip files as release assets.

• The extension targets normal http

andhttps

pages. - The current runtime is primarily validated on Chromium-based browsers; Firefox compatibility is still planned work.

• Restricted browser pages such as chrome://

are intentionally out of scope. - Scripts execute in-page and rely on the injected Playwright-style page

helper. - Manual validation with a loaded browser extension is recommended before release.

Issues and pull requests are welcome. For larger changes, please open an issue first so the implementation direction can be discussed.

Before sending a pull request, run:

pnpm lint
pnpm typecheck
pnpm test
pnpm build

Apache License 2.0. See LICENSE.

source & further reading

github.com — original article