Webcmd

Self-learning browser infra for AI agents.

WebCMD learns the navigational context of websites as agents use them, then compiles that knowledge into deterministic commands for faster, cheaper, more reliable browser automation. The goal is simple: stop making agents rediscover the same sites on every run and cut browser-agent token spend by up to 90%.

On top of live browser control, WebCMD adds 3 layers of learnings. Each layer collapses cost and variance for the layer above it.

| Layer | Scenario | What Webcmd Helps With | | --- | --- | --- | | 1. Live browser control | The site is unfamiliar. | Use webcmd browser to inspect, click, type, extract, capture network calls, and complete the task in a real browser. | | 2. Sitemap memory | The site is familiar, but the action space is not fully known. | Capture an agent-facing sitemap of observed pages, states, actions, workflows, APIs, pitfalls, and fallback paths. | | 3. CLI authoring | The action space is known, but the path is still too variable for one fixed sequence. | Explicitly author a reusable webcmd <site> adapter with structured output, so future agents spend tokens on the task instead of navigation. | | 4. Extend existing CLIs | The workflow is deterministic enough to stop browsing. | Extend the webcmd <site> adapter with a tailored command so the workflow runs instantly with the least amount of tokens. |

Quick Start

1. Install Webcmd

Webcmd requires Node.js >= 20.

node --version
npm install -g @agentrhq/webcmd

2. Verify the browser runtime

webcmd doctor

doctor checks the Webcmd browser bridge: daemon status, browser runtime installation, profile selection, and a live connectivity probe. Pure public adapters and local passthrough commands do not need a green browser check, but COOKIE, INTERCEPT, UI, and webcmd browser workflows do.

3. Discover commands

webcmd list
webcmd list -f json
webcmd reddit --help
webcmd reddit hot --help

webcmd list -f json is the source of truth for agents. It emits one row per command with the site, command name, arguments, output columns, browser requirement, and strategy.

4. Run your first command

webcmd hackernews top --limit 5
webcmd reddit popular --limit 5
webcmd pubmed search "agentic browser automation" --limit 5 -f json

For Humans

Use Webcmd directly when you want a reliable command instead of a live browser session:

webcmd list
webcmd <site> --help
webcmd <site> <command> --help
webcmd <site> <command> -f yaml

The everyday surface is intentionally small:

• webcmd list shows every registered adapter and external command.
• webcmd <site> <command> ... runs a built-in, plugin, or private adapter.

For example:

webcmd hackernews top --limit 10
webcmd reddit subreddit programming --limit 10
webcmd twitter whoami

Adapter commands are tagged by strategy:

| Strategy | What it means | |----------|---------------| | PUBLIC | No browser or login. Webcmd can call a public endpoint or page directly. | | COOKIE | Uses the logged-in Webcmd browser profile for authenticated reads. | | INTERCEPT | Uses the browser to capture a signed or stateful request before replaying it. | | UI | Drives the page UI directly. | | LOCAL | Talks to a local app, service, or CLI surface. |

Output formats are consistent across adapters:

webcmd hackernews top -f table
webcmd hackernews top -f json
webcmd hackernews top -f yaml
webcmd hackernews top -f md
webcmd hackernews top -f csv

Agents usually want -f json; humans usually want table (default) or yaml.

For AI Agents

Webcmd is designed to be driven by coding agents such as Codex, Claude Code, Cursor, and similar tools.

Install skills (also refreshes existing installs)

Install Webcmd skills into your agent environment:

webcmd skills install

The installer asks whether to install globally or locally, then asks for the coding agent (agents, codex, claude) or a custom skills path. For scripts, pass flags such as --scope project --provider codex or --path ./my-skills.

Which skill to use

| Skill | When to use | |-------|-------------| | webcmd-usage | Orient an agent to Webcmd commands, formats, strategies, plugins, and external CLIs. | | webcmd-browser | Drive a real browser ad hoc: inspect, click, type, extract, network, tabs, waits. | | webcmd-adapter-author | Write or extend a reusable site adapter. | | webcmd-autofix | Repair an adapter after selectors, APIs, or response shapes drift. | | webcmd-browser-sitemap | Use recorded site knowledge while driving a browser task. | | webcmd-sitemap-author | Capture or update reusable sitemap knowledge for future agents. | | smart-search | Route search and research requests to the right adapter. |

The common agent workflow is:

webcmd list -f json
webcmd <site> <command> -f json
webcmd <site> <command> --trace retain-on-failure -f json

Start with adapters. Fall back to webcmd browser only when no adapter covers the task or you are teaching Webcmd a new site flow.

Live Browser Interaction

webcmd browser gives agents a stable, structured interface to a real browser. Every command takes a session name immediately after browser — the session is required, so webcmd browser tab list without one is an error:

webcmd browser <session> open https://example.com

Tabs and page IDs

webcmd browser work open <url> and webcmd browser work tab new [url] both return a page ID in the page field:

$ webcmd browser work open https://reddit.com
{
  "url": "https://reddit.com",
  "page": "page-1783484232033-8"
}

Use webcmd browser work tab list to inspect all tabs — each entry carries its page ID (id/page), the owning session (adapter sessions appear as site:<name>), and whether it is the currently selected tab. Pass --tab <pageId> to route a single command to a specific tab:

webcmd browser work open https://example.com --tab page-1783484232033-8

tab new creates a tab without changing the session's default tab; only tab select <pageId> promotes a tab to the default for later untargeted commands in the same session.

Useful browser primitives include:

| Area | Commands | |------|----------| | Navigation | open, back, wait, scroll, close | | Inspection | state, find, get, frames, screenshot, extract | | Interaction | click, type, fill, select, keys, hover, focus, check, uncheck, upload, drag | | Network | network, network --detail <key>, network --filter <fields> | | Tabs | tab list, tab new, tab select, tab close, bind, unbind | | Adapter work | init, verify, analyze |

Every interaction command returns structured data: match count, target identity, confidence level, and machine-readable errors. That contract is why agents can recover from mild DOM drift instead of guessing.

Profiles

Named profiles let Webcmd keep separate browser identities:

webcmd profile list
webcmd profile rename <context-id> work
webcmd profile use work
webcmd --profile work browser work state

If multiple browser profiles are connected and no default is selected, Webcmd asks you to choose rather than guessing.

Built-in Commands

Webcmd ships a large adapter registry. The list changes over time, so use webcmd list -f json for the current surface. Highlights include:

| Site/App | Example commands | |----------|------------------| | hackernews | top, new, best, ask, show, jobs, search, read, user | | reddit | hot, popular, search, subreddit, read, user, comment, save, upvote, subscribe | | linkedin | search, people-search, jobs-preferences, job-detail, profile-read, posts, inbox, safe-send | | twitter | trending, search, timeline, tweets, post, profile, bookmarks, notifications, follow, unfollow | | tiktok | search, explore, user, creator-videos, notifications, follow, comment, like, save | | amazon | search, product, offer, bestsellers, new-releases, movers-shakers, discussion | | pubmed | search, article, author, citations, clinical-trial, journal, mesh, related, review | | chatgpt | ask, send, new, read, history, detail, image, deep-research-result, model | | claude | ask, send, new, read, history, detail, status | | gemini | ask, new, image, deep-research, deep-research-result, models | | notebooklm | list, open, summary, source-list, source-get, source-fulltext, generate-audio, generate-slides |

Current registry size is generated from cli-manifest.json; this README intentionally lists highlights, not a frozen catalog.

External CLI Hub

Webcmd can expose existing command-line tools through the same discovery and invocation surface:

webcmd external install gh
webcmd external register my-tool \
  --binary my-tool \
  --install "npm i -g my-tool" \
  --desc "My internal CLI"
webcmd external list

webcmd gh pr list --limit 5
webcmd docker ps

Built-in external entries include common tools such as gh, docker, vercel, wrangler, obsidian, longbridge, ntn, tg, discord, and wx. User overrides live in ~/.webcmd/external-clis.yaml.

Plugins

Plugins let you install third-party adapter packs without patching the core registry:

webcmd plugin install github:user/repo
webcmd plugin list -f json
webcmd plugin update --all
webcmd plugin uninstall <name>
webcmd plugin create <name>

plugin create prompts for the author's display name and GitHub handle. For non-interactive use, pass --author-name <name> and --author-handle <handle>.

Use plugins for private company workflows, community adapters, or experiments that are not ready for the built-in registry. This repo is also a plugin monorepo: community plugins promoted here live under plugins/ and are advertised through webcmd-plugin.json.

Community plugins

| Plugin | Description | Author | | --- | --- | --- | | skyscanner | Skyscanner flight search commands for Webcmd | Rishabh |

Writing Adapters

When a site is not covered yet, author a reusable adapter instead of leaving an agent to spend tokens clicking through the same browser flow every time.

webcmd browser init <site>/<command>
webcmd validate <site>/<command>
webcmd verify <site>/<command> --smoke
webcmd browser work verify <site>/<command>

Adapter files import the public Webcmd registry/error APIs:

import { cli, Strategy } from '@agentrhq/webcmd/registry';
import { CommandExecutionError } from '@agentrhq/webcmd/errors';

Private adapters can live in ~/.webcmd/clis/<site>/<command>.js; bundled upstream adapters live in clis/, while community upstream adapters live as plugins under plugins/. For the full authoring workflow, install and use webcmd-adapter-author.

Configuration

| Variable | Default | Description | |----------|---------|-------------| | WEBCMD_PROFILE | none | Browser runtime profile alias/context ID to use when multiple profiles are available. | | WEBCMD_WINDOW | command-specific | foreground or background browser window mode. | | WEBCMD_BROWSER_CONNECT_TIMEOUT | 45 | Seconds to wait for the browser bridge. | | WEBCMD_BROWSER_COMMAND_TIMEOUT | 60 | Seconds to wait for one browser command. | | WEBCMD_CDP_ENDPOINT | none | Manual CDP endpoint for remote browsers or Electron apps. | | WEBCMD_CDP_TARGET | none | Filter CDP targets by URL substring. | | WEBCMD_CACHE_DIR | ~/.webcmd/cache | Browser state and network capture cache. | | WEBCMD_VERBOSE | false | Enable verbose logs. Also enabled by -v. |

Common paths:

| Path | Purpose | |------|---------| | ~/.webcmd/ | User-level Webcmd state. | | ~/.webcmd/clis/ | Private adapters. | | ~/.webcmd/cache/browser-network/ | Cached browser network captures. | | ~/.webcmd/external-clis.yaml | User external CLI registry entries. | | ~/.agents/skills/ | Common global skills install target for agent skill managers. | | .agents/skills/ | Common workspace-local skills install target. |

Troubleshooting

• Browser bridge is unavailable: run webcmd doctor -v and follow the daemon/profile/runtime hint it prints.
• Multiple profiles are connected: run webcmd profile list, then webcmd profile use <name> or pass --profile <name>.
• Authenticated adapter returns empty or unauthorized: log into the target site in the Webcmd-managed browser profile, then retry.
• A site changed and an adapter fails: rerun with --trace retain-on-failure -f json, inspect the trace summary, and use webcmd-autofix.
• A browser target is stale: run webcmd browser <session> state again and use the fresh numeric ref or locator.
• Node errors on startup: Webcmd requires Node.js >= 20. Check node --version.

Development

npm install
npm test
npm run typecheck
npm run build

Release engineering, Conventional Commits, CI, and npm publishing notes live in CONTRIBUTING.md.

License

Released under the terms in LICENSE.