agentrhq · ankitranjan7 · Aug 11, 2026 · Aug 11, 2026 · Aug 11, 2026 · Aug 11, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -0,0 +1,17 @@
+{
+  "$schema": "https://www.schemastore.org/claude-code-marketplace.json",
+  "name": "webcmd",
+  "description": "Turn websites, browser sessions, desktop apps, and local tools into deterministic CLI surfaces for humans and AI agents.",
+  "owner": {
+    "name": "AgentRHQ",
+    "url": "https://github.com/agentrhq"
+  },
+  "plugins": [
+    {
+      "name": "webcmd",
+      "description": "Webcmd CLI, browser, search, authoring, sitemap, and repair skills. Requires the @agentrhq/webcmd npm CLI.",
+      "source": "./",
+      "category": "productivity"
+    }
+  ]
+}
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -0,0 +1,18 @@
+{
+  "name": "webcmd",
+  "version": "0.6.0",
+  "description": "Turn websites, browser sessions, desktop apps, and local tools into deterministic CLI surfaces for humans and AI agents.",
+  "author": {
+    "name": "AgentRHQ",
+    "url": "https://github.com/agentrhq"
+  },
+  "homepage": "https://webcmd.dev/docs",
+  "repository": "https://github.com/agentrhq/webcmd",
+  "license": "Apache-2.0",
+  "keywords": [
+    "webcmd",
+    "browser-automation",
+    "cli",
+    "agent-skills"
+  ]
+}
diff --git a/README.md b/README.md
@@ -57,7 +57,33 @@ Fetch and follow https://raw.githubusercontent.com/agentrhq/webcmd/main/start.md
 
 ### Manual
 
-Refer to the [Quickstart](https://webcmd.dev/docs/quickstart) docs for step-by-step manual setup.
+Webcmd requires Node.js 20.6+.
+
+```bash
+npm install -g @agentrhq/webcmd
+```
+
+The npm package ships the Webcmd core and browser commands, but no site
+adapters. Search the plugin catalog and explicitly install the adapter you
+need:
+
+```bash
+webcmd plugin search <site> -f json
+webcmd plugin install <installSource-from-search>
+```
+
+```bash
+webcmd skills add
+```
+
+When prompted, choose Claude, Codex, another supported harness, or a custom
+skills path.
+
+In your agent harness, load or tag `webcmd-usage`, then describe the outcome you want.
+
+```text
+Use webcmd to research the latest discussions about browser automation across Hacker News and Reddit, then return a concise comparison with source links.
+```
 
 ## What You Can Ask
 

diff --git a/docs/agents/claude-code.md b/docs/agents/claude-code.md
@@ -18,7 +18,18 @@ Fetch and follow https://raw.githubusercontent.com/agentrhq/webcmd/main/start.md
 * Claude Code (`claude`), installed globally or in the project
 * A browser runtime; confirm with `webcmd doctor` before browser work
 
-### Install and configure
+### Install the plugin
+
+```bash
+claude plugin marketplace add agentrhq/webcmd
+claude plugin install webcmd@webcmd
+```
+
+This installs all seven bundled Webcmd skills. Do not also add those skills with `webcmd skills add`; running both leaves two copies that can sit at different versions.
+
+Plugin updates are version-gated, not commit-gated. Run `claude plugin update webcmd@webcmd` to pick up a new release; it is separate from `webcmd update`, which upgrades only the npm CLI.
+
+### Install and configure without the plugin
 
 Install Webcmd and its skills:
 
@@ -34,30 +45,47 @@ Restart Claude Code (or start a new session) after installing skills.
 
 ### Override default tools
 
-Claude Code ships two native web tools — `WebFetch` (fetch a URL) and `WebSearch` (search). Both are permission-gated by default. Deny them so Claude Code cannot fall back to them while Webcmd is its web surface. Add to the user or project settings file (`.claude/settings.json` in the project, or `~/.claude/settings.json`):
+Claude Code ships two native web tools — `WebFetch` (fetch a URL) and `WebSearch` (search) — both permission-gated by default.
+
+Deny `WebFetch`. It is lossy by design: a small, fast model runs an extraction prompt against the page and Claude receives that model's answer, not the page. Webcmd returns the real content. Add to the user or project settings file (`.claude/settings.json` in the project, or `~/.claude/settings.json`):
 
 ```json
 {
   "permissions": {
-    "deny": ["WebFetch", "WebSearch"]
+    "deny": ["WebFetch"]
   }
 }
 ```
 
-Alternatively, pass the flag per invocation:
+Or per invocation:
 
 ```bash
-claude --disallowedTools WebFetch WebSearch
+claude --disallowedTools WebFetch
 ```
 
+**Keep `WebSearch`.** It returns result titles and URLs without fetching the pages, which is exactly the step Webcmd does not cover — Webcmd has no search index. Let Claude Code search, then let Webcmd read what it finds.
+
+If the desktop app's Browser pane is in use, its tools are MCP-named (`mcp__Claude_Browser__*`) and can be denied the same way:
+
+```json
+{
+  "permissions": {
+    "deny": ["WebFetch", "mcp__Claude_Browser__*"]
+  }
+}
+```
+
+Only deny those if the user does not use the Browser pane for their own app — it is wired into the local dev loop. There is also a `browserExternalPageTools: "disabled"` setting, but it applies to managed settings only.
+
 Denying these tools does not affect the Bash tool, which is how `webcmd` is driven.
 
 ### Troubleshooting
 
 | Symptom | What to try |
 | --- | --- |
 | `webcmd doctor` is red | Fix the browser runtime first; browser commands depend on it. |
-| Skills not loading in Claude Code | Run `webcmd skills add` with the `claude` provider, then restart `claude`. |
+| Skills not loading in Claude Code | Run `webcmd skills add` with the `claude` provider, then restart `claude`. With the plugin, run `claude plugin install webcmd@webcmd` and restart. |
+| Skill text looks out of date | `webcmd update` upgrades only the CLI. Run `claude plugin update webcmd@webcmd` to refresh plugin skills. |
 | Claude Code still uses `WebFetch` / `WebSearch` | Confirm `permissions.deny` lists both in the active settings file, then restart `claude`. |
 | `claude` requires permission prompts for `webcmd` | The Bash tool still asks before non-approved commands; run `claude --dangerously-skip-permissions` or allow the shell command if you accept the risk. |
 | Browser sessions stop working after idle | Ask the agent to open a fresh session or re-bind with `tabs` and `bind --page`. |

diff --git a/docs/agents/codex-cli.md b/docs/agents/codex-cli.md
@@ -20,7 +20,29 @@ Fetch and follow https://raw.githubusercontent.com/agentrhq/webcmd/main/start.md
 
 ### Install and configure
 
-Install Webcmd and its skills:
+Pick one of the two paths below. Do not use both — the plugin already carries the skills, and installing them again leaves duplicates.
+
+#### Plugin (recommended)
+
+Add the marketplace and install the plugin:
+
+```bash
+codex plugin marketplace add agentrhq/webcmd
+```
+
+```bash
+codex plugin add webcmd@webcmd
+```
+
+`codex plugin add` takes `PLUGIN@MARKETPLACE`, or a bare plugin name with `-m webcmd`. Pin a version with `codex plugin marketplace add agentrhq/webcmd --ref <tag>`.
+
+The same flow is available in the TUI: run `/plugins`, choose **Add plugin marketplace**, and enter `agentrhq/webcmd` or `https://github.com/agentrhq/webcmd`.
+
+The plugin bundles all seven Webcmd skills, and installs the npm CLI on first use if `webcmd` is missing. Start a new task after installing.
+
+Useful follow-ups: `codex plugin list`, `codex plugin remove webcmd`, `codex plugin marketplace upgrade`. All accept `--json`.
+
+#### Manual
 
 ```bash
 npm install -g @agentrhq/webcmd
@@ -34,23 +56,33 @@ Restart Codex (or start a new session) after installing skills.
 
 ### Override default tools
 
-Codex CLI's native web tool is `web_search`, controlled by the top-level `web_search` setting in `~/.codex/config.toml`. Set it to `"disabled"` to remove the tool so Codex relies on Webcmd for web work:
+**Nothing to disable.** Codex CLI has no fetch tool and no browser tool, so Webcmd does not displace anything — it adds the surface Codex is missing. Codex drives it through the shell tool.
+
+Its one web tool is `web_search`, set by the top-level `web_search` key in `~/.codex/config.toml`. **Keep it enabled.** Webcmd has no search index of its own, and search is how a question becomes URLs for Webcmd to read.
+
+One change is worth recommending. `web_search` defaults to `"cached"`, an OpenAI-maintained index with no external web access, so results can be stale. Switching to `"live"` pairs better with Webcmd:
 
 ```toml
-web_search = "disabled"
+web_search = "live"
 ```
 
-Do not rely on the CLI flag `--dangerously-allow-web-search`; it only gates the tool and does not replace Webcmd's browser surface. Note that `web_search` defaults to `"cached"` (results from an OpenAI-maintained index without external web access) unless overridden.
+Accepted values are `"disabled"`, `"cached"` (default), `"indexed"`, and `"live"`. Ask before changing it — `"live"` means real network egress from the user's machine.
+
+If the user has installed a browser or scraping MCP server, that does overlap with Webcmd. Individual MCP tools are denied per server:
 
-The setting removes only the search tool; it does not affect the shell tool, which is how `webcmd` is driven.
+```toml
+[mcp_servers.some_browser_mcp]
+disabled_tools = ["navigate", "screenshot"]
+```
 
 ### Troubleshooting
 
 | Symptom | What to try |
 | --- | --- |
 | `webcmd doctor` is red | Fix the browser runtime first; browser commands depend on it. |
 | Skills not loading in Codex | Run `webcmd skills add` with the `agents` provider, then restart `codex`. |
-| Codex still uses `web_search` | Confirm `web_search = "disabled"` in `~/.codex/config.toml`, then restart `codex`. |
+| Search results look stale | `web_search` defaults to `"cached"`. Set `web_search = "live"` in `~/.codex/config.toml`, then restart `codex`. |
+| `web_search` was disabled and search stopped working | Expected. Set it back to `"live"` or `"cached"` — Webcmd does not replace search. |
 | `webcmd` not found in Codex shell | Confirm `webcmd` is on the PATH Codex uses; restart after installing the CLI. |
 | Browser sessions stop working after idle | Ask the agent to open a fresh session or re-bind with `tabs` and `bind --page`. |
 

diff --git a/docs/agents/cursor.md b/docs/agents/cursor.md
@@ -33,37 +33,49 @@ For a project-scoped setup, copy the `webcmd-*` skill folders into the project's
 
 ### Override default tools
 
-Cursor's agent ships two native web tools: **Browser** (navigate, click, screenshot running apps) and **Web** (search and fetch external documentation). Cursor has no single config key that removes them, so replace them with an always-applied rule that forces Webcmd usage.
+Cursor's agent ships two native web tools:
 
-Add `.cursor/rules/webcmd-browser.mdc`:
+* **Web** — generates search queries and performs web searches. This is Cursor's search tool. **Keep it on** (Settings has a "Web Search Tool" toggle); Webcmd has no search index of its own.
+* **Browser** — navigate, click, type, scroll, screenshot, plus console logs and network traffic. It has dev-server awareness for localhost but can navigate anywhere on the web, so it is the tool that overlaps with Webcmd.
+
+Cursor has no config key that removes the Browser tool for individual users, so steer it with an always-applied rule. Add `.cursor/rules/webcmd-browser.mdc`:
 
 ```markdown
 ---
-description: Use Webcmd for all browser automation instead of Cursor's built-in Browser and Web tools.
+description: Use Webcmd for the open web; keep Cursor's Browser tool for the local dev loop.
 globs:
   - "**/*"
 alwaysApply: true
 ---
 
-Do not use your native Browser tool (navigate/click/screenshot) or your Web tool (search/fetch) for browser work.
-
-Use Webcmd instead:
+Use Webcmd for anything on the open web — fetching, authenticated
+third-party sites, multi-step automation, workflows worth making reusable:
 
 - Check `webcmd list -f json` for an adapter that covers the task; use it first.
 - Otherwise drive a live browser with `webcmd browser <session> ...` via the shell tool.
 - Run `webcmd doctor` first and keep the session lifecycle (`tabs`, `bind`, `snapshot`, `run`, `close`).
 - For login walls, use Webcmd's human handoff; never type passwords, OTPs, cookies, or credentials.
+
+Use the native Browser tool only for the app being edited: localhost dev server,
+console and network triage, visual checks after a change.
+
+Keep using the Web tool to search. Webcmd reads the pages that search finds.
 ```
 
-The `alwaysApply: true` rule is injected into every Cursor session, so the agent does not fall back to its native Browser/Web tools. You can also set the Browser Automation dropdown in the agent window to **Off** so the built-in browser is not attached at all.
+The `alwaysApply: true` rule is injected into every Cursor session.
+
+Note that the rule is guidance, not a block. Cursor's Browser Automation has been reported to enable itself when a prompt mentions "browser", and the user-level switch to turn it off has come and gone across releases — so expect the agent to reach for it occasionally even with the rule in place.
+
+**Full override (opt-in).** If the user never debugs local apps through Cursor's browser, drop the Browser paragraph from the rule and set Browser Automation to **Off** in the agent window. On Team and Enterprise plans an admin can also toggle browser features in the Settings Dashboard under MCP Configuration, or restrict the agent to an origin allowlist.
 
 ### Troubleshooting
 
 | Symptom | What to try |
 | --- | --- |
 | `webcmd doctor` is red | Fix the browser runtime first; browser commands depend on it. |
 | Skills not surfacing in Cursor | Confirm the `webcmd-*` skill folders are under `.cursor/skills/`, `.agents/skills/`, or `~/.agents/skills/`, then restart Cursor. |
-| Cursor still uses its Browser/Web tools | Confirm `.cursor/rules/webcmd-browser.mdc` has `alwaysApply: true`, and set Browser Automation to Off. |
+| Cursor uses its Browser tool for external sites | Confirm `.cursor/rules/webcmd-browser.mdc` has `alwaysApply: true`; for a hard block, set Browser Automation to Off. |
+| Browser Automation turns itself back on | Known behaviour — a prompt mentioning "browser" can re-enable it. Avoid the word, or turn it off in the agent window. |
 | `webcmd` not found in Cursor shell | Confirm `webcmd` is on the PATH the Cursor shell uses; restart Cursor after installing the CLI. |
 | Browser sessions stop working after idle | Ask the agent to open a fresh session or re-bind with `tabs` and `bind --page`. |
 

diff --git a/docs/agents/hermes.md b/docs/agents/hermes.md
@@ -40,7 +40,23 @@ Hermes then reads `webcmd-usage` and `webcmd-browser` as skills. Restart Hermes
 
 ### Override default tools
 
-Hermes' native browser toolset is `browser` (`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_scroll`, and the rest). Disable it so Hermes does not keep its native browser tools alongside Webcmd:
+Hermes' web surface spans three toolsets:
+
+| Toolset | Tools | What to do |
+| --- | --- | --- |
+| `web` | `web_search`, `web_extract` | Keep enabled for `web_search`; prefer Webcmd over `web_extract` |
+| `browser` | `browser_navigate`, `browser_click`, `browser_type`, `browser_scroll`, `browser_press`, `browser_back`, `browser_snapshot`, `browser_vision`, `browser_console`, `browser_get_images`, plus CDP-gated `browser_cdp` and `browser_dialog` | Keep for localhost, route open-web work to Webcmd |
+| `x_search` | `x_search` | Keep — it is search, and it auto-enables whenever xAI credentials are present |
+
+`web_search` lives in `web`, not in `browser`, so disabling `browser` leaves search intact.
+
+**Hermes toggles toolsets, not individual tools.** There is no way to drop `web_extract` while keeping `web_search`, so leave the `web` toolset on and steer the agent with instructions instead. Add this to your Hermes system prompt or project instructions:
+
+> Use Webcmd (`webcmd list`, `webcmd browser <session> ...` via the `terminal` toolset) for anything on the open web: fetching, authenticated third-party sites, multi-step automation. Prefer it over `web_extract`. Use the `browser_*` tools only for the app being edited — localhost dev server, console and network triage, visual checks. Keep using `web_search` and `x_search` to find URLs.
+
+Also check the `computer_use` toolset. It drives the whole desktop rather than a browser, so it overlaps with Webcmd whenever it is aimed at a website. Disable it if the user does not need desktop control.
+
+**Full override (opt-in).** If the user never debugs local apps through Hermes' browser, disable the toolset outright:
 
 ```bash
 hermes tools disable browser
@@ -56,8 +72,6 @@ agent:
 
 Recommended: use `hermes tools disable browser` so the terminal toolset stays available.
 
-Note: Hermes' `browser` toolset statically bundles `web_search`, so disabling `browser` also removes `web_search` from every session. `web_extract` and the rest of the `web` toolset are unaffected. That is acceptable here: Webcmd's `smart-search` skill and adapters cover search, so Hermes should rely on Webcmd for browser work and search.
-
 Do not disable the `terminal` toolset — that is how Hermes runs `webcmd`.
 
 ### Troubleshooting
@@ -66,8 +80,10 @@ Do not disable the `terminal` toolset — that is how Hermes runs `webcmd`.
 | --- | --- |
 | `webcmd doctor` is red | Fix the browser runtime first; browser commands depend on it. |
 | Skills not loading in Hermes | Confirm `skills.external_dirs` includes `~/.agents/skills`, restart Hermes, and check skill discovery. |
-| Hermes still uses `browser_*` tools | Confirm `agent.disabled_toolsets` includes `browser`, then restart Hermes. |
-| `web_search` missing after disabling `browser` | Expected: Hermes bundles `web_search` inside the `browser` toolset. Use Webcmd's `smart-search` skill or adapters instead. |
+| Hermes uses `browser_*` for open-web work | Remind it in the system prompt that Webcmd handles the open web; for a hard block, add `browser` to `agent.disabled_toolsets` and restart Hermes. |
+| `web_search` missing after disabling `browser` | Unexpected — `web_search` is in the `web` toolset. Confirm `web` is still enabled with `hermes tools`. |
+| Search disappeared after disabling `web` | Expected: `web_search` and `web_extract` share one toolset. Re-enable `web` and steer the agent with instructions instead. |
+| `x_search` appeared on its own | Expected: it auto-registers when `XAI_API_KEY` or Grok OAuth is configured. Leave it — it is search. |
 | `webcmd` not found in Hermes terminal | Confirm `webcmd` is on the host PATH that Hermes' `terminal` toolset uses; non-interactive shells may skip shell init files. |
 | Browser sessions stop working after idle | Ask the agent to open a fresh session or re-bind with `tabs` and `bind --page`. |