@agentrhq/webcmd 0.3.4 → 0.4.0

package/README.md

@@ -1,4 +1,4 @@
-<img width="2056" height="765" alt="ChatGPT Image Jul 15, 2026, 12_14_45 PM" src="https://github.com/user-attachments/assets/5bcba7ee-588c-4839-9927-4f151055cdf6" />
+<img width="1280" height="640" alt="Webcmd — stop paying agents to rediscover the web" src="docs/readme-hero.png" />
 
 
 <p align="center">
@@ -8,7 +8,7 @@
   <a href="https://www.npmjs.com/package/@agentrhq/webcmd">
     <img alt="NPM downloads" src="https://img.shields.io/npm/dt/@agentrhq/webcmd.svg?style=for-the-badge&color=1E88E5&labelColor=000000">
   </a>
-  <a href="https://docs.webcmd.dev">
+  <a href="https://webcmd.dev/docs">
     <img alt="Documentation" src="https://img.shields.io/badge/docs-webcmd.dev-7C3AED.svg?style=for-the-badge&labelColor=000000">
   </a>
   <a href="https://github.com/agentrhq/webcmd/blob/main/LICENSE">
@@ -37,236 +37,71 @@ On top of live browser control, WebCMD adds 3 layers of learnings. Each layer co
 | 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. |
 
+## Demo
 
-## Quick Start
+https://github.com/user-attachments/assets/04eceadc-d398-4303-984d-ae3197bfa664
 
-### 1. Install Webcmd
+## Quick Start
 
-Webcmd requires **Node.js >= 20**.
+Webcmd requires Node.js 20+.
 
 ```bash
-node --version
 npm install -g @agentrhq/webcmd
-```
-
-### 2. Verify the browser runtime
-
-```bash
-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
-
-```bash
-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
-
-```bash
-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:
-
-```bash
-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:
-
-```bash
-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:
-
-```bash
-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.
-
-## Add skills (also refreshes existing links)
-
-Add Webcmd skills to your agent environment:
-
-```bash
 webcmd skills add
 ```
 
-The command asks whether to add 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`.
-
-Remove Webcmd skill symlinks from all supported global and current-project locations with `webcmd skills remove`. Pass `--path ./my-skills` to include a custom directory.
-
-### Which skill to use
-
-| Skill | When to use |
-|-------|-------------|
-| [`webcmd-usage`](./skills/webcmd-usage/SKILL.md) | Orient an agent to Webcmd commands, formats, strategies, plugins, and external CLIs. |
-| [`webcmd-browser`](./skills/webcmd-browser/SKILL.md) | Drive a real browser ad hoc: inspect, click, type, extract, network, tabs, waits. |
-| [`webcmd-adapter-author`](./skills/webcmd-adapter-author/SKILL.md) | Write or extend a reusable site adapter. |
-| [`webcmd-autofix`](./skills/webcmd-autofix/SKILL.md) | Repair an adapter after selectors, APIs, or response shapes drift. |
-| [`webcmd-browser-sitemap`](./skills/webcmd-browser-sitemap/SKILL.md) | Use recorded site knowledge while driving a browser task. |
-| [`webcmd-sitemap-author`](./skills/webcmd-sitemap-author/SKILL.md) | Capture or update reusable sitemap knowledge for future agents. |
-| [`smart-search`](./skills/smart-search/SKILL.md) | Route search and research requests to the right adapter. |
-
-The common agent workflow is:
-
-```bash
-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.
+When prompted, choose a supported harness such as Codex or Claude, or enter a custom skills path.
 
-## Live Browser Interaction
+In your agent harness, load or tag `webcmd-usage`, then describe the outcome you want.
 
-`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:
-
-```bash
-webcmd browser <session> open https://example.com
+```text
+Use webcmd to research the latest discussions about browser automation across Hacker News and Reddit, then return a concise comparison with source links.
 ```
 
-### 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:
+## What You Can Ask
 
-```bash
-$ webcmd browser work open https://reddit.com
-{
-  "url": "https://reddit.com",
-  "page": "page-1783484232033-8"
-}
-```
+- “Use webcmd to research agentic browser automation on PubMed and return the title, authors, publication date, abstract, and URL for each result.”
+- “Use webcmd to find active AI infrastructure companies in the YC company directory and return the company, batch, description, location, profile URL, and source links. Keep it read-only.”
+- “Use webcmd to look up parts on Grainger by part number and return price, stock, minimum order quantity, lead time, and product URL.”
+- “Use webcmd with my logged-in `work` profile to summarize unread LinkedIn messages from the last seven days and return the sender, subject or opening text, received time, and conversation URL.”
+- “Repair `webcmd reddit popular --limit 10` and keep returning the title, subreddit, score, comment count, and URL.”
+- “Use webcmd to check Grainger part prices and SAP Ariba purchase-order status, then return a combined summary.”
 
-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:
+## See It in Action: X → CLI
 
-```bash
-webcmd browser work open https://example.com --tab page-1783484232033-8
+```text
+Use webcmd with my logged-in `social` profile to collect my recent X bookmarks and return the author, text, and URL.
 ```
 
-`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:
-
-```bash
-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`](./cli-manifest.json); this README intentionally lists highlights, not a frozen catalog.
-
-## External CLI Hub
+The agent explores the X workflow once using the logged-in profile.
+It creates a stable command that returns the requested bookmark fields.
+Later agents reuse that command instead of repeating browser exploration; learn the pattern in [X → CLI](https://webcmd.dev/docs/x-session-cli).
 
-Webcmd can expose existing command-line tools through the same discovery and invocation surface:
+## Where Webcmd Works
 
-```bash
-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
-```
+Beyond website adapters, Webcmd can work through authenticated browser sessions, APIs, desktop apps, and local tools.
 
-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`.
+| Group | Supported surfaces | Representative outcomes |
+| --- | --- | --- |
+| research and communities | Hacker News, Reddit, PubMed | Compare current discussions, find primary research, and return concise summaries with source links. |
+| social and professional | X/Twitter, LinkedIn, TikTok | Collect bookmarks, monitor public posts, or research people and creators with a named profile when needed. |
+| AI tools | ChatGPT, Claude, Gemini, NotebookLM | Retrieve conversations, research outputs, notebooks, and generated materials from the tools you already use. |
+| shopping and bookings | Amazon, Blinkit, Zepto, BigBasket, District, Practo | Compare products, availability, prices, appointments, events, and delivery options. |
 
-## Plugins
+This list is illustrative; ask your agent to use webcmd to discover what is currently available.
 
-Plugins let you install third-party adapter packs without patching the core registry:
+## Learn More
 
-```bash
-webcmd plugin install github:user/repo
-webcmd plugin list -f json
-webcmd plugin update --all
-webcmd plugin uninstall <name>
-webcmd plugin create <name>
-```
+Webcmd Cloud can run supported commands and browser sessions on hosted infrastructure. It is in active development and is not yet stable.
 
-`plugin create` prompts for the author's display name and GitHub handle. For non-interactive use, pass `--author-name <name>` and `--author-handle <handle>`.
+- [Prompt Cookbook](https://webcmd.dev/docs/agent-prompts)
+- [How Webcmd Works](https://webcmd.dev/docs/concepts)
+- [Local or Cloud](https://webcmd.dev/docs/local-or-cloud)
+- [Publish a Community Plugin](https://webcmd.dev/docs/publish-community-plugin)
+- [X → CLI](https://webcmd.dev/docs/x-session-cli)
+- [Command Surface](https://webcmd.dev/docs/cli-reference)
 
-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/`](./plugins/) and are advertised through [`webcmd-plugin.json`](./webcmd-plugin.json).
+## Community
 
 <!-- webcmd-community-plugins:start -->
 ### Community plugins
@@ -276,69 +111,9 @@ Use plugins for private company workflows, community adapters, or experiments th
 | [`skyscanner`](./plugins/skyscanner/) | Skyscanner flight search commands for Webcmd | [Rishabh](https://github.com/rishabhraj36) |
 <!-- webcmd-community-plugins:end -->
 
-## 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.
-
-```bash
-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:
-
-```js
-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/`](./clis/), while community upstream adapters live as plugins under [`plugins/`](./plugins/). For the full authoring workflow, install and use [`webcmd-adapter-author`](./skills/webcmd-adapter-author/SKILL.md).
-
-## 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 directory for agent skill managers. |
-| `.agents/skills/` | Common workspace-local skills directory. |
-
-## 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
-
-```bash
-npm install
-npm test
-npm run typecheck
-npm run build
-```
+## Contributing
 
-Release engineering, Conventional Commits, CI, and npm publishing notes live in [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## License