From 45e0556141ab81c659fc68a482275571e12bc9bc Mon Sep 17 00:00:00 2001 From: Ankit Ranjan Date: Tue, 11 Aug 2026 14:58:04 +0530 Subject: [PATCH 01/13] docs: route web work to Webcmd instead of blanket-disabling native tools Section 4 of start.md told every harness to disable its native browser tools. That is honest for narrow fetch/search tools, which Webcmd covers end to end, but wrong for full browser toolsets like Cursor's Browser, Hermes' browser_*, and OpenClaw's browser: those are wired into the local dev loop and do things Webcmd does not target. Split the table into Replace (disable) and Route (keep, with a routing rule), state the boundary as integration rather than capability, and keep full-disable as an explicit opt-in. Also resolves the contradictory "disable any web-search tool / do not disable builtin web search tool" sentence. Co-Authored-By: Claude Opus 5 --- docs/agents/cursor.md | 23 ++++++++++++++++------- docs/agents/hermes.md | 12 +++++++++--- docs/agents/openclaw.md | 15 +++++++++++---- start.md | 36 ++++++++++++++++++++++++++---------- 4 files changed, 62 insertions(+), 24 deletions(-) diff --git a/docs/agents/cursor.md b/docs/agents/cursor.md index 6b13914..b90814c 100644 --- a/docs/agents/cursor.md +++ b/docs/agents/cursor.md @@ -33,29 +33,37 @@ 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, and they get different treatment — see [the routing rule](../../start.md#the-routing-rule). -Add `.cursor/rules/webcmd-browser.mdc`: +Webcmd replaces **Web** (search and fetch external documentation) outright. **Browser** (navigate, click, screenshot running apps) is wired into Cursor's dev loop, so keep it for localhost work and route open-web work to Webcmd. + +Cursor has no config key that removes either tool, so use 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: Route open-web work to Webcmd; 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. +Do not use your native Web tool (search/fetch). Use Webcmd instead. -Use Webcmd instead: +Use Webcmd for anything on the open web — research, 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 ...` 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. ``` -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. + +**Full override (opt-in).** If you never debug local apps through Cursor's browser, drop the last paragraph of the rule and set the Browser Automation dropdown in the agent window to **Off** so the built-in browser is not attached at all. ### Troubleshooting @@ -63,7 +71,8 @@ The `alwaysApply: true` rule is injected into every Cursor session, so the agent | --- | --- | | `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 Web tool instead of Webcmd | Confirm `.cursor/rules/webcmd-browser.mdc` has `alwaysApply: true`. | +| Cursor uses its Browser tool for external sites | Restate the routing rule; for a hard block, set Browser Automation to Off. | | `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 index bfb42d8..12d0e25 100644 --- a/docs/agents/hermes.md +++ b/docs/agents/hermes.md @@ -40,7 +40,13 @@ 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' native browser toolset is `browser` (`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_scroll`, and the rest). It is a full browser stack wired into Hermes' dev loop, so the default is to route rather than disable — see [the routing rule](../../start.md#the-routing-rule). + +Add this to your Hermes system prompt or project instructions: + +> Use Webcmd (`webcmd list`, `webcmd browser ...` via the `terminal` toolset) for anything on the open web: research, fetching, authenticated third-party sites, multi-step automation. Use the `browser_*` tools only for the app being edited — localhost dev server, console and network triage, visual checks. + +**Full override (opt-in).** If you never debug local apps through Hermes' browser, disable the toolset outright: ```bash hermes tools disable browser @@ -56,7 +62,7 @@ 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. +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 — Webcmd's `smart-search` skill and adapters cover search. Do not disable the `terminal` toolset — that is how Hermes runs `webcmd`. @@ -66,7 +72,7 @@ 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. | +| Hermes uses `browser_*` for open-web work | Restate the routing rule in the system prompt; for a hard block, add `browser` to `agent.disabled_toolsets` and 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. | | `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`. | diff --git a/docs/agents/openclaw.md b/docs/agents/openclaw.md index 2525697..8d19b60 100644 --- a/docs/agents/openclaw.md +++ b/docs/agents/openclaw.md @@ -34,17 +34,23 @@ Restart the Gateway (or start a new session) after installing skills. ### Override default tools -OpenClaw's built-in web tools are `web_search`, `web_fetch`, `browser`, `browser_visual`, and `search_news`. Deny the ones that overlap with Webcmd in the Gateway config (`~/.openclaw/openclaw.json`) so OpenClaw relies on Webcmd for browser work: +OpenClaw's built-in web tools split into two groups — see [the routing rule](../../start.md#the-routing-rule). + +Webcmd replaces the fetch and search tools outright. Deny them in the Gateway config (`~/.openclaw/openclaw.json`): ```json { "tools": { - "deny": ["web_search", "web_fetch", "browser", "browser_visual"] + "deny": ["web_search", "web_fetch", "x_search", "search_news"] } } ``` -`search_news` only covers news queries; deny it too if you want all web access through Webcmd. The Gateway watches the config file and applies changes automatically. Denying these tools does not affect the `exec` tool, which is how `webcmd` is driven. +Keep `browser` and `browser_visual`. They are wired into OpenClaw's dev loop, so use them for the app being edited — localhost dev server, console and network triage, visual checks — and route open-web work to Webcmd. State that split in your OpenClaw system prompt or project instructions. + +The Gateway watches the config file and applies changes automatically. Denying these tools does not affect the `exec` tool, which is how `webcmd` is driven. + +**Full override (opt-in).** If you never debug local apps through OpenClaw's browser, add `"browser"` and `"browser_visual"` to the deny list so all web access goes through Webcmd. ### Troubleshooting @@ -52,7 +58,8 @@ OpenClaw's built-in web tools are `web_search`, `web_fetch`, `browser`, `browser | --- | --- | | `webcmd doctor` is red | Fix the browser runtime first; browser commands depend on it. | | Skills not loading in OpenClaw | Run `webcmd skills add` with the `agents` provider, then restart the Gateway. | -| OpenClaw still uses its native web tools | Confirm `tools.deny` lists the tool IDs in `~/.openclaw/openclaw.json`; the Gateway hot-reloads config. | +| OpenClaw still uses `web_search` / `web_fetch` | Confirm `tools.deny` lists the tool IDs in `~/.openclaw/openclaw.json`; the Gateway hot-reloads config. | +| OpenClaw uses `browser` for external sites | Restate the routing rule; for a hard block, add `browser` and `browser_visual` to `tools.deny`. | | `webcmd` not found in OpenClaw exec | Confirm `webcmd` is on the PATH the Gateway's `exec` tool 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/start.md b/start.md index 2da5064..a3cbb73 100644 --- a/start.md +++ b/start.md @@ -66,22 +66,38 @@ Using the Webcmd skill installed in the previous step, complete this task: Do not hand-write a one-off script from memory. Follow the skill guidance, run the task end to end, and close any browser session you open. Success means returning five real stories with titles and URLs. -### 4. Override default tools +### 4. Route web work to Webcmd -Open the *Override default tools* section on the matching per-agent page under `docs/agents/`. Disable the agent's native browser tools so Webcmd is used instead: +Open the *Override default tools* section on the matching per-agent page under `docs/agents/`. Harnesses get one of two treatments. -| Harness | Native tools Webcmd replaces | Page | +**Replace** — narrow fetch and search tools. Webcmd covers these end to end (adapters plus the `smart-search` skill), so disable them and let Webcmd be the harness's web surface. + +| Harness | Tools to disable | Page | | --- | --- | --- | -| Cursor | `Browser`, `Web` | [cursor.md](docs/agents/cursor.md#override-default-tools) | -| OpenCode | `webfetch`; `websearch` when enabled | [opencode.md](docs/agents/opencode.md#override-default-tools) | | Claude Code | `WebFetch`, `WebSearch` | [claude-code.md](docs/agents/claude-code.md#override-default-tools) | | Codex CLI | `web_search` | [codex-cli.md](docs/agents/codex-cli.md#override-default-tools) | -| Hermes Agent | `browser` + `web` toolsets (`browser_*`, `web_search`, `web_extract`) | [hermes.md](docs/agents/hermes.md#override-default-tools) | -| Pi | none (optional `pi-skills`) | [pi.md](docs/agents/pi.md#override-default-tools) | -| OpenClaw | `web_search`, `web_fetch`, `x_search`, `browser` | [openclaw.md](docs/agents/openclaw.md#override-default-tools) | -| Other Coding Agents | native web fetch / browser tools | see instructions below | +| OpenCode | `webfetch`, `websearch` | [opencode.md](docs/agents/opencode.md#override-default-tools) | + +**Route** — full browser toolsets. These do more than Webcmd targets: they are wired into the local dev loop, attaching to a running dev server and surfacing console errors, network activity, and screenshots of the app under edit. Do not disable them by default. Apply the routing rule below instead. + +| Harness | Native browser toolset | Also disable (Replace tools) | Page | +| --- | --- | --- | --- | +| Cursor | `Browser` | `Web` | [cursor.md](docs/agents/cursor.md#override-default-tools) | +| Hermes Agent | `browser_*` | — (bundles `web_search`; see page) | [hermes.md](docs/agents/hermes.md#override-default-tools) | +| OpenClaw | `browser`, `browser_visual` | `web_search`, `web_fetch`, `x_search`, `search_news` | [openclaw.md](docs/agents/openclaw.md#override-default-tools) | +| Pi | none (optional `pi-skills`) | — | [pi.md](docs/agents/pi.md#override-default-tools) | + +#### The routing rule + +Use **Webcmd** for the open web: research and fetching, authenticated third-party sites, multi-step automation, anything worth turning into a reusable adapter. Webcmd owns auth profiles, human handoff, token-compact snapshots, and the adapter registry. + +Use the **harness's native browser tool** for the app you are editing: localhost dev server, console and network triage, visual checks after a change. It is attached to the dev loop; Webcmd is not. + +This is a question of integration, not capability — `webcmd browser run` can drive localhost too. Routing by task domain means neither surface has to be crippled. + +If your harness is not listed above, apply the same split: disable a plain fetch or search tool, keep a full browser toolset and state the routing rule in the harness's system prompt or rules file. Leave custom tools and skills untouched. If the harness has neither kind of tool, no override is needed. -If your harness is not listed above, disable any default built-in browser tool or web-search tool so the agent uses Webcmd instead. Do not disable builtin web search tool and keep custom tools and skills untouched. If the harness has none of these tools, no override is needed. +**Full override (opt-in).** If you never debug local apps through the harness browser and want the token savings, disable the native browser toolset as well and use Webcmd for everything. Each per-agent page documents how. ### 5. Finish From 0c00a03790906ebaa20a08ad694c5151dc612093 Mon Sep 17 00:00:00 2001 From: Ankit Ranjan Date: Tue, 11 Aug 2026 15:04:02 +0530 Subject: [PATCH 02/13] docs: ask before disabling tools, and cover user-installed ones Agents fetch start.md and follow it verbatim, so section 4 has to say who makes the call: the agent proposes, the user confirms. Retitle to "Override installed tools" and add a section for tools the user installed themselves (Playwright/Puppeteer MCPs, scraping or search MCPs, custom web-fetch skills), which compete with Webcmd the same way built-ins do. Co-Authored-By: Claude Opus 5 --- start.md | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/start.md b/start.md index a3cbb73..76dcbf5 100644 --- a/start.md +++ b/start.md @@ -66,11 +66,17 @@ Using the Webcmd skill installed in the previous step, complete this task: Do not hand-write a one-off script from memory. Follow the skill guidance, run the task end to end, and close any browser session you open. Success means returning five real stories with titles and URLs. -### 4. Route web work to Webcmd +### 4. Override installed tools -Open the *Override default tools* section on the matching per-agent page under `docs/agents/`. Harnesses get one of two treatments. +Do not change the user's tool configuration yourself. Work out what should change, then **present it to the user and ask them to confirm** before anything is disabled. Tool configuration is theirs; a harness that silently loses its browser tools is a bad surprise. -**Replace** — narrow fetch and search tools. Webcmd covers these end to end (adapters plus the `smart-search` skill), so disable them and let Webcmd be the harness's web surface. +Phrase it as a recommendation with a reason, not as a requirement. For example: + +> Webcmd now covers web fetching and search for this project, and it does a better job than the built-in tools — adapters return exact fields, sessions render real pages with logged-in profiles, and snapshots cost fewer tokens. I'd suggest disabling `WebFetch` and `WebSearch` so I don't fall back to them. Want me to make that change? + +Open the *Override default tools* section on the matching per-agent page under `docs/agents/` for the exact config edit. Harnesses get one of two treatments. + +**Replace** — narrow fetch and search tools. Webcmd covers these end to end (adapters plus the `smart-search` skill), so recommend disabling them and let Webcmd be the harness's web surface. | Harness | Tools to disable | Page | | --- | --- | --- | @@ -95,9 +101,20 @@ Use the **harness's native browser tool** for the app you are editing: localhost This is a question of integration, not capability — `webcmd browser run` can drive localhost too. Routing by task domain means neither surface has to be crippled. -If your harness is not listed above, apply the same split: disable a plain fetch or search tool, keep a full browser toolset and state the routing rule in the harness's system prompt or rules file. Leave custom tools and skills untouched. If the harness has neither kind of tool, no override is needed. +If your harness is not listed above, apply the same split: recommend disabling a plain fetch or search tool, and keep a full browser toolset with the routing rule stated in the harness's system prompt or rules file. If the harness has neither kind of tool, no override is needed. + +#### Other installed tools + +The tables above cover tools the harness ships with. Users often have others installed that overlap with Webcmd — a Playwright or Puppeteer MCP server, a browser-automation MCP, a scraping or search MCP, a custom web-fetch skill. Two or more of these competing for the same task is how an agent ends up picking the wrong surface. + +Check what is actually connected in this environment, list anything that overlaps, and apply the same split when you present it: + +- Overlaps with fetch/search or general web automation → recommend disabling it, and say why Webcmd is the better fit for this project. +- Serves a purpose Webcmd does not (drives the local dev server, a bespoke internal tool, project-specific skills) → leave it alone and say so. + +Never disable a user-installed tool without asking, and never touch project-specific custom tools or skills. If you are unsure whether something overlaps, list it and let the user decide. -**Full override (opt-in).** If you never debug local apps through the harness browser and want the token savings, disable the native browser toolset as well and use Webcmd for everything. Each per-agent page documents how. +**Full override (opt-in).** If the user never debugs local apps through the harness browser and wants the token savings, they can disable the native browser toolset as well and use Webcmd for everything. Each per-agent page documents how — offer it, do not assume it. ### 5. Finish From d81c79d7303f49eef3aca1113453d6072d354d49 Mon Sep 17 00:00:00 2001 From: Ankit Ranjan Date: Tue, 11 Aug 2026 15:09:21 +0530 Subject: [PATCH 03/13] docs: trim section 4 to a table and two lines Co-Authored-By: Claude Opus 5 --- docs/agents/cursor.md | 6 ++---- docs/agents/hermes.md | 4 ++-- docs/agents/openclaw.md | 6 ++---- start.md | 48 ++++++++--------------------------------- 4 files changed, 15 insertions(+), 49 deletions(-) diff --git a/docs/agents/cursor.md b/docs/agents/cursor.md index b90814c..16f1dc2 100644 --- a/docs/agents/cursor.md +++ b/docs/agents/cursor.md @@ -33,9 +33,7 @@ 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, and they get different treatment — see [the routing rule](../../start.md#the-routing-rule). - -Webcmd replaces **Web** (search and fetch external documentation) outright. **Browser** (navigate, click, screenshot running apps) is wired into Cursor's dev loop, so keep it for localhost work and route open-web work to Webcmd. +Cursor's agent ships two native web tools, and they get different treatment. Webcmd replaces **Web** (search and fetch external documentation). **Browser** (navigate, click, screenshot running apps) is attached to Cursor's dev server, so keep it for localhost work. Cursor has no config key that removes either tool, so use an always-applied rule. Add `.cursor/rules/webcmd-browser.mdc`: @@ -72,7 +70,7 @@ The `alwaysApply: true` rule is injected into every Cursor session. | `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 uses its Web tool instead of Webcmd | Confirm `.cursor/rules/webcmd-browser.mdc` has `alwaysApply: true`. | -| Cursor uses its Browser tool for external sites | Restate the routing rule; for a hard block, set Browser Automation to Off. | +| Cursor uses its Browser tool for external sites | Confirm the rule file says to use Webcmd for the open web; for a hard block, set Browser Automation to Off. | | `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 index 12d0e25..ad7bffe 100644 --- a/docs/agents/hermes.md +++ b/docs/agents/hermes.md @@ -40,7 +40,7 @@ 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). It is a full browser stack wired into Hermes' dev loop, so the default is to route rather than disable — see [the routing rule](../../start.md#the-routing-rule). +Hermes' native browser toolset is `browser` (`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_scroll`, and the rest). It is attached to Hermes' local dev server, so keep it enabled by default. Add this to your Hermes system prompt or project instructions: @@ -72,7 +72,7 @@ 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 uses `browser_*` for open-web work | Restate the routing rule in the system prompt; for a hard block, add `browser` to `agent.disabled_toolsets` and restart Hermes. | +| 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` | Expected: Hermes bundles `web_search` inside the `browser` toolset. Use Webcmd's `smart-search` skill or adapters instead. | | `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`. | diff --git a/docs/agents/openclaw.md b/docs/agents/openclaw.md index 8d19b60..6c96a71 100644 --- a/docs/agents/openclaw.md +++ b/docs/agents/openclaw.md @@ -34,9 +34,7 @@ Restart the Gateway (or start a new session) after installing skills. ### Override default tools -OpenClaw's built-in web tools split into two groups — see [the routing rule](../../start.md#the-routing-rule). - -Webcmd replaces the fetch and search tools outright. Deny them in the Gateway config (`~/.openclaw/openclaw.json`): +OpenClaw's built-in web tools split into two groups. Webcmd replaces the fetch and search tools; deny them in the Gateway config (`~/.openclaw/openclaw.json`): ```json { @@ -59,7 +57,7 @@ The Gateway watches the config file and applies changes automatically. Denying t | `webcmd doctor` is red | Fix the browser runtime first; browser commands depend on it. | | Skills not loading in OpenClaw | Run `webcmd skills add` with the `agents` provider, then restart the Gateway. | | OpenClaw still uses `web_search` / `web_fetch` | Confirm `tools.deny` lists the tool IDs in `~/.openclaw/openclaw.json`; the Gateway hot-reloads config. | -| OpenClaw uses `browser` for external sites | Restate the routing rule; for a hard block, add `browser` and `browser_visual` to `tools.deny`. | +| OpenClaw uses `browser` for external sites | Remind it that Webcmd handles the open web; for a hard block, add `browser` and `browser_visual` to `tools.deny`. | | `webcmd` not found in OpenClaw exec | Confirm `webcmd` is on the PATH the Gateway's `exec` tool 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/start.md b/start.md index 76dcbf5..1d94194 100644 --- a/start.md +++ b/start.md @@ -68,53 +68,23 @@ Do not hand-write a one-off script from memory. Follow the skill guidance, run t ### 4. Override installed tools -Do not change the user's tool configuration yourself. Work out what should change, then **present it to the user and ask them to confirm** before anything is disabled. Tool configuration is theirs; a harness that silently loses its browser tools is a bad surprise. +Recommend these changes to the user and ask before applying any of them. Do not edit their tool configuration on your own. -Phrase it as a recommendation with a reason, not as a requirement. For example: +Suggest disabling the harness's built-in fetch and search tools, since Webcmd covers them and returns exact fields from real pages instead of summaries: -> Webcmd now covers web fetching and search for this project, and it does a better job than the built-in tools — adapters return exact fields, sessions render real pages with logged-in profiles, and snapshots cost fewer tokens. I'd suggest disabling `WebFetch` and `WebSearch` so I don't fall back to them. Want me to make that change? - -Open the *Override default tools* section on the matching per-agent page under `docs/agents/` for the exact config edit. Harnesses get one of two treatments. - -**Replace** — narrow fetch and search tools. Webcmd covers these end to end (adapters plus the `smart-search` skill), so recommend disabling them and let Webcmd be the harness's web surface. - -| Harness | Tools to disable | Page | +| Harness | Suggest disabling | Page | | --- | --- | --- | | Claude Code | `WebFetch`, `WebSearch` | [claude-code.md](docs/agents/claude-code.md#override-default-tools) | | Codex CLI | `web_search` | [codex-cli.md](docs/agents/codex-cli.md#override-default-tools) | | OpenCode | `webfetch`, `websearch` | [opencode.md](docs/agents/opencode.md#override-default-tools) | +| Cursor | `Web` | [cursor.md](docs/agents/cursor.md#override-default-tools) | +| OpenClaw | `web_search`, `web_fetch`, `x_search`, `search_news` | [openclaw.md](docs/agents/openclaw.md#override-default-tools) | +| Hermes Agent | `web_search` (bundled in `browser`; see page) | [hermes.md](docs/agents/hermes.md#override-default-tools) | +| Pi | none | [pi.md](docs/agents/pi.md#override-default-tools) | -**Route** — full browser toolsets. These do more than Webcmd targets: they are wired into the local dev loop, attaching to a running dev server and surfacing console errors, network activity, and screenshots of the app under edit. Do not disable them by default. Apply the routing rule below instead. - -| Harness | Native browser toolset | Also disable (Replace tools) | Page | -| --- | --- | --- | --- | -| Cursor | `Browser` | `Web` | [cursor.md](docs/agents/cursor.md#override-default-tools) | -| Hermes Agent | `browser_*` | — (bundles `web_search`; see page) | [hermes.md](docs/agents/hermes.md#override-default-tools) | -| OpenClaw | `browser`, `browser_visual` | `web_search`, `web_fetch`, `x_search`, `search_news` | [openclaw.md](docs/agents/openclaw.md#override-default-tools) | -| Pi | none (optional `pi-skills`) | — | [pi.md](docs/agents/pi.md#override-default-tools) | - -#### The routing rule - -Use **Webcmd** for the open web: research and fetching, authenticated third-party sites, multi-step automation, anything worth turning into a reusable adapter. Webcmd owns auth profiles, human handoff, token-compact snapshots, and the adapter registry. - -Use the **harness's native browser tool** for the app you are editing: localhost dev server, console and network triage, visual checks after a change. It is attached to the dev loop; Webcmd is not. - -This is a question of integration, not capability — `webcmd browser run` can drive localhost too. Routing by task domain means neither surface has to be crippled. - -If your harness is not listed above, apply the same split: recommend disabling a plain fetch or search tool, and keep a full browser toolset with the routing rule stated in the harness's system prompt or rules file. If the harness has neither kind of tool, no override is needed. - -#### Other installed tools - -The tables above cover tools the harness ships with. Users often have others installed that overlap with Webcmd — a Playwright or Puppeteer MCP server, a browser-automation MCP, a scraping or search MCP, a custom web-fetch skill. Two or more of these competing for the same task is how an agent ends up picking the wrong surface. - -Check what is actually connected in this environment, list anything that overlaps, and apply the same split when you present it: - -- Overlaps with fetch/search or general web automation → recommend disabling it, and say why Webcmd is the better fit for this project. -- Serves a purpose Webcmd does not (drives the local dev server, a bespoke internal tool, project-specific skills) → leave it alone and say so. - -Never disable a user-installed tool without asking, and never touch project-specific custom tools or skills. If you are unsure whether something overlaps, list it and let the user decide. +Leave full browser toolsets enabled — Cursor's `Browser`, Hermes' `browser_*`, OpenClaw's `browser`. They are attached to the local dev server, which Webcmd is not. Use them for localhost; use Webcmd for the open web. -**Full override (opt-in).** If the user never debugs local apps through the harness browser and wants the token savings, they can disable the native browser toolset as well and use Webcmd for everything. Each per-agent page documents how — offer it, do not assume it. +The same applies to tools the user installed themselves. A Playwright or Puppeteer MCP, a scraping or search MCP, or a custom web-fetch skill competes with Webcmd for the same tasks — list what you find and ask. Leave project-specific tools and skills alone. ### 5. Finish From 9115f4fe8f8439b7d15a54696c03635932887492 Mon Sep 17 00:00:00 2001 From: Ankit Ranjan Date: Tue, 11 Aug 2026 15:18:51 +0530 Subject: [PATCH 04/13] docs: update tool disabling recommendations in start.md to include browser navigation and exclude search tools --- start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/start.md b/start.md index 1d94194..657ff85 100644 --- a/start.md +++ b/start.md @@ -70,7 +70,7 @@ Do not hand-write a one-off script from memory. Follow the skill guidance, run t Recommend these changes to the user and ask before applying any of them. Do not edit their tool configuration on your own. -Suggest disabling the harness's built-in fetch and search tools, since Webcmd covers them and returns exact fields from real pages instead of summaries: +Suggest disabling the harness's built-in webfetch and broswer navigation tools, since Webcmd covers them and returns exact fields from real pages instead of summaries. Do not replace any search tool. | Harness | Suggest disabling | Page | | --- | --- | --- | From fce047cc67fafb99945b7196e06ae61f6c3b6c91 Mon Sep 17 00:00:00 2001 From: Ankit Ranjan Date: Tue, 11 Aug 2026 15:31:10 +0530 Subject: [PATCH 05/13] docs: fill in the tool-shortlisting rubric in section 4 Co-Authored-By: Claude Opus 5 --- start.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/start.md b/start.md index 657ff85..6102b27 100644 --- a/start.md +++ b/start.md @@ -70,7 +70,25 @@ Do not hand-write a one-off script from memory. Follow the skill guidance, run t Recommend these changes to the user and ask before applying any of them. Do not edit their tool configuration on your own. -Suggest disabling the harness's built-in webfetch and broswer navigation tools, since Webcmd covers them and returns exact fields from real pages instead of summaries. Do not replace any search tool. +Suggest disabling webfetch and browser navigation tools, since Webcmd does these tasks better for several reasons: + +- No 3rd party services — all local execution, so page content and credentials stay on the machine +- Costs less, due to smarter snapshots +- Stealth mode gives better access + +Here is the rubric to shortlist the tools you'll recommend disabling. + +1. **Web fetch** — a builtin that retrieves a URL and hands back a summary or extraction: Claude Code's `WebFetch`, OpenCode's `webfetch`, OpenClaw's `web_fetch`, Cursor's `Web`. +2. **Web search** — a builtin that returns result links without reading the pages: `WebSearch`, `web_search`, `websearch`, `x_search`, `search_news`. +3. **Browser navigation aimed at the open web** — any tool or MCP that drives a browser against external sites: a Playwright or Puppeteer MCP, a browser-automation or scraping MCP, a cloud browser service, a custom web-fetch skill. + +Here are some tools which you should not recommend disabling. + +1. **The harness's own browser attached to the local dev server** — Cursor's `Browser`, Hermes' `browser_*`, OpenClaw's `browser`. These are wired into the dev loop and surface console errors and network activity for the app being edited. Webcmd is not. Use them for localhost; use Webcmd for the open web. +2. **The shell, terminal, or exec tool** — that is how the agent runs `webcmd`. +3. **Project-specific custom tools and skills**, and MCPs that do not touch the web (a database, filesystem, or issue-tracker MCP). + +Check what is actually installed in this environment, not just the table below. List everything that matches the rubric, say which rule each one hit, and let the user decide. | Harness | Suggest disabling | Page | | --- | --- | --- | @@ -82,9 +100,7 @@ Suggest disabling the harness's built-in webfetch and broswer navigation tools, | Hermes Agent | `web_search` (bundled in `browser`; see page) | [hermes.md](docs/agents/hermes.md#override-default-tools) | | Pi | none | [pi.md](docs/agents/pi.md#override-default-tools) | -Leave full browser toolsets enabled — Cursor's `Browser`, Hermes' `browser_*`, OpenClaw's `browser`. They are attached to the local dev server, which Webcmd is not. Use them for localhost; use Webcmd for the open web. - -The same applies to tools the user installed themselves. A Playwright or Puppeteer MCP, a scraping or search MCP, or a custom web-fetch skill competes with Webcmd for the same tasks — list what you find and ask. Leave project-specific tools and skills alone. +Each per-agent page has the exact config edit under *Override default tools*. ### 5. Finish From 43145dc5e097b66ead0b7197e723793a0649325c Mon Sep 17 00:00:00 2001 From: Ankit Ranjan Date: Tue, 11 Aug 2026 16:33:31 +0530 Subject: [PATCH 06/13] docs: update tool disabling rubric and harness configuration table in start.md --- start.md | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/start.md b/start.md index 6102b27..068fe30 100644 --- a/start.md +++ b/start.md @@ -78,29 +78,40 @@ Suggest disabling webfetch and browser navigation tools, since Webcmd does these Here is the rubric to shortlist the tools you'll recommend disabling. -1. **Web fetch** — a builtin that retrieves a URL and hands back a summary or extraction: Claude Code's `WebFetch`, OpenCode's `webfetch`, OpenClaw's `web_fetch`, Cursor's `Web`. -2. **Web search** — a builtin that returns result links without reading the pages: `WebSearch`, `web_search`, `websearch`, `x_search`, `search_news`. -3. **Browser navigation aimed at the open web** — any tool or MCP that drives a browser against external sites: a Playwright or Puppeteer MCP, a browser-automation or scraping MCP, a cloud browser service, a custom web-fetch skill. +1. **Web fetch** — a builtin that retrieves a URL and hands back a summary or extraction. Claude Code's `WebFetch`, OpenCode's `webfetch`, OpenClaw's `web_fetch`, Cursor's `Web`. +2. **Browser Tools** — any tool or MCP that drives a browser against external sites. Hermes has browser_* tools, OpenClaw has one broswer tool, etc. Here are some tools which you should not recommend disabling. -1. **The harness's own browser attached to the local dev server** — Cursor's `Browser`, Hermes' `browser_*`, OpenClaw's `browser`. These are wired into the dev loop and surface console errors and network activity for the app being edited. Webcmd is not. Use them for localhost; use Webcmd for the open web. -2. **The shell, terminal, or exec tool** — that is how the agent runs `webcmd`. -3. **Project-specific custom tools and skills**, and MCPs that do not touch the web (a database, filesystem, or issue-tracker MCP). +1. **Web search** - +2. **Other search tools** - For example x_search tool in hermes -Check what is actually installed in this environment, not just the table below. List everything that matches the rubric, say which rule each one hit, and let the user decide. +**Real world example**: In a hermes environment, when xAI plugin is enabled here is the set of tools which are present: + +webfetch surface +├── Hermes registry +│ ├── web_search — Don't Change +│ ├── web_extract — Disable (if enableď) +│ └── browser_* / … — Disable (if enableď) +└── xAI plugin / server-side (when {type: web_search} exposed) + ├── web_search / web_search_with_snippets — Don't Change + ├── browse_page / open_page — Disable (if enableď) + ├── open_page_with_find — Disable (if enableď) + └── optional: view_image, search_images — Don't Change + + +For instructions on how to disable tools for a specific harness, refer to the documentation for that harness. | Harness | Suggest disabling | Page | | --- | --- | --- | -| Claude Code | `WebFetch`, `WebSearch` | [claude-code.md](docs/agents/claude-code.md#override-default-tools) | +| Claude Code | `WebFetch` | [claude-code.md](docs/agents/claude-code.md#override-default-tools) | | Codex CLI | `web_search` | [codex-cli.md](docs/agents/codex-cli.md#override-default-tools) | -| OpenCode | `webfetch`, `websearch` | [opencode.md](docs/agents/opencode.md#override-default-tools) | +| OpenCode | `webfetch` | [opencode.md](docs/agents/opencode.md#override-default-tools) | | Cursor | `Web` | [cursor.md](docs/agents/cursor.md#override-default-tools) | | OpenClaw | `web_search`, `web_fetch`, `x_search`, `search_news` | [openclaw.md](docs/agents/openclaw.md#override-default-tools) | | Hermes Agent | `web_search` (bundled in `browser`; see page) | [hermes.md](docs/agents/hermes.md#override-default-tools) | | Pi | none | [pi.md](docs/agents/pi.md#override-default-tools) | - -Each per-agent page has the exact config edit under *Override default tools*. +| Other Coding Agents | native web fetch / browser tools | see instructions below | ### 5. Finish From 070876e048b43711af39a09d4993e46e324f05a7 Mon Sep 17 00:00:00 2001 From: Ankit Ranjan Date: Tue, 11 Aug 2026 16:35:35 +0530 Subject: [PATCH 07/13] docs: complete the keep-web-search rubric entry and correct harness tool names Researched the actual fetch/search/browser tools of all seven harnesses. Fixes: Hermes' web_search is in the `web` toolset, not bundled inside `browser`; Codex has no fetch or browser tool at all; Cursor's `Web` is the search tool and `Browser` is the navigation surface; OpenClaw's search tools move to the keep column. Co-Authored-By: Claude Opus 5 --- docs/agents/hermes.md | 4 ++-- start.md | 23 +++++++++++------------ 2 files changed, 13 insertions(+), 14 deletions(-) diff --git a/docs/agents/hermes.md b/docs/agents/hermes.md index ad7bffe..c1137c4 100644 --- a/docs/agents/hermes.md +++ b/docs/agents/hermes.md @@ -62,7 +62,7 @@ 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 — Webcmd's `smart-search` skill and adapters cover search. +Note: `web_search` lives in the separate `web` toolset, not in `browser`, so disabling `browser` leaves search intact. Keep `web_search` — Webcmd has no search index of its own and reads the pages search only names. `web_extract` is the tool in that toolset worth disabling. Do not disable the `terminal` toolset — that is how Hermes runs `webcmd`. @@ -73,7 +73,7 @@ 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 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` | Expected: Hermes bundles `web_search` inside the `browser` toolset. Use Webcmd's `smart-search` skill or adapters instead. | +| `web_search` missing after disabling `browser` | Unexpected — `web_search` is in the `web` toolset. Confirm `web` is still enabled with `hermes tools`. | | `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`. | diff --git a/start.md b/start.md index 068fe30..a6ea3f3 100644 --- a/start.md +++ b/start.md @@ -83,8 +83,8 @@ Here is the rubric to shortlist the tools you'll recommend disabling. Here are some tools which you should not recommend disabling. -1. **Web search** - -2. **Other search tools** - For example x_search tool in hermes +1. **Web search** — a builtin that takes a query and returns result titles and links without reading the pages. Claude Code's `WebSearch`, Codex CLI's `web_search`, OpenCode's `websearch`, OpenClaw's `web_search`, Hermes' `web_search`, Cursor's Web Search Tool. Leave these on. Webcmd has no search index of its own, and a native search tool is the cheapest way to turn a question into URLs. Webcmd takes over from there — it reads the pages the search only names. +2. **Other search tools** — the same reasoning covers scoped search builtins: Hermes' `x_search`, OpenClaw's `x_search` and `search_news`. They return links, not page content. **Real world example**: In a hermes environment, when xAI plugin is enabled here is the set of tools which are present: @@ -102,16 +102,15 @@ webfetch surface For instructions on how to disable tools for a specific harness, refer to the documentation for that harness. -| Harness | Suggest disabling | Page | -| --- | --- | --- | -| Claude Code | `WebFetch` | [claude-code.md](docs/agents/claude-code.md#override-default-tools) | -| Codex CLI | `web_search` | [codex-cli.md](docs/agents/codex-cli.md#override-default-tools) | -| OpenCode | `webfetch` | [opencode.md](docs/agents/opencode.md#override-default-tools) | -| Cursor | `Web` | [cursor.md](docs/agents/cursor.md#override-default-tools) | -| OpenClaw | `web_search`, `web_fetch`, `x_search`, `search_news` | [openclaw.md](docs/agents/openclaw.md#override-default-tools) | -| Hermes Agent | `web_search` (bundled in `browser`; see page) | [hermes.md](docs/agents/hermes.md#override-default-tools) | -| Pi | none | [pi.md](docs/agents/pi.md#override-default-tools) | -| Other Coding Agents | native web fetch / browser tools | see instructions below | +| Harness | Suggest disabling | Keep (search) | Page | +| --- | --- | --- | --- | +| Claude Code | `WebFetch`; Browser pane tools (`mcp__Claude_Browser__*`) | `WebSearch` | [claude-code.md](docs/agents/claude-code.md#override-default-tools) | +| Codex CLI | none — Codex has no fetch or browser tool | `web_search` | [codex-cli.md](docs/agents/codex-cli.md#override-default-tools) | +| OpenCode | `webfetch` | `websearch` | [opencode.md](docs/agents/opencode.md#override-default-tools) | +| Cursor | `Browser` when pointed at external sites | Web Search Tool | [cursor.md](docs/agents/cursor.md#override-default-tools) | +| OpenClaw | `web_fetch`, `browser`, `browser_visual` | `web_search`, `x_search`, `search_news` | [openclaw.md](docs/agents/openclaw.md#override-default-tools) | +| Hermes Agent | `web_extract`, `browser_*`, `computer_use` | `web_search`, `x_search` | [hermes.md](docs/agents/hermes.md#override-default-tools) | +| Pi | none built in — check installed extensions | none built in | [pi.md](docs/agents/pi.md#override-default-tools) | ### 5. Finish From bdcd824758bbbd7649b53f8cce8ee3ea994a8a83 Mon Sep 17 00:00:00 2001 From: Ankit Ranjan Date: Tue, 11 Aug 2026 16:38:37 +0530 Subject: [PATCH 08/13] docs: generalize the web_search entry instead of listing every harness Co-Authored-By: Claude Opus 5 --- start.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/start.md b/start.md index a6ea3f3..b6dc758 100644 --- a/start.md +++ b/start.md @@ -83,7 +83,7 @@ Here is the rubric to shortlist the tools you'll recommend disabling. Here are some tools which you should not recommend disabling. -1. **Web search** — a builtin that takes a query and returns result titles and links without reading the pages. Claude Code's `WebSearch`, Codex CLI's `web_search`, OpenCode's `websearch`, OpenClaw's `web_search`, Hermes' `web_search`, Cursor's Web Search Tool. Leave these on. Webcmd has no search index of its own, and a native search tool is the cheapest way to turn a question into URLs. Webcmd takes over from there — it reads the pages the search only names. +1. **Web search** — a builtin that takes a query and returns result titles and links without reading the pages. Every harness here except Pi ships one, usually named some spelling of `web_search` (`WebSearch`, `websearch`, or a "Web Search" toggle in Cursor). Leave it on: Webcmd has no search index of its own, and search is the cheapest way to turn a question into URLs. Webcmd reads the pages that search only names. 2. **Other search tools** — the same reasoning covers scoped search builtins: Hermes' `x_search`, OpenClaw's `x_search` and `search_news`. They return links, not page content. **Real world example**: In a hermes environment, when xAI plugin is enabled here is the set of tools which are present: @@ -102,15 +102,16 @@ webfetch surface For instructions on how to disable tools for a specific harness, refer to the documentation for that harness. -| Harness | Suggest disabling | Keep (search) | Page | -| --- | --- | --- | --- | -| Claude Code | `WebFetch`; Browser pane tools (`mcp__Claude_Browser__*`) | `WebSearch` | [claude-code.md](docs/agents/claude-code.md#override-default-tools) | -| Codex CLI | none — Codex has no fetch or browser tool | `web_search` | [codex-cli.md](docs/agents/codex-cli.md#override-default-tools) | -| OpenCode | `webfetch` | `websearch` | [opencode.md](docs/agents/opencode.md#override-default-tools) | -| Cursor | `Browser` when pointed at external sites | Web Search Tool | [cursor.md](docs/agents/cursor.md#override-default-tools) | -| OpenClaw | `web_fetch`, `browser`, `browser_visual` | `web_search`, `x_search`, `search_news` | [openclaw.md](docs/agents/openclaw.md#override-default-tools) | -| Hermes Agent | `web_extract`, `browser_*`, `computer_use` | `web_search`, `x_search` | [hermes.md](docs/agents/hermes.md#override-default-tools) | -| Pi | none built in — check installed extensions | none built in | [pi.md](docs/agents/pi.md#override-default-tools) | +| Harness | Page | +| --- | --- | +| Cursor | [cursor.md](docs/agents/cursor.md#override-default-tools) | +| OpenCode | [opencode.md](docs/agents/opencode.md#override-default-tools) | +| Claude Code | [claude-code.md](docs/agents/claude-code.md#override-default-tools) | +| Codex CLI | [codex-cli.md](docs/agents/codex-cli.md#override-default-tools) | +| Hermes Agent | [hermes.md](docs/agents/hermes.md#override-default-tools) | +| Pi | [pi.md](docs/agents/pi.md#override-default-tools) | +| OpenClaw | [openclaw.md](docs/agents/openclaw.md#override-default-tools) | +| Other Coding Agents | see their officical docs | ### 5. Finish From e4de723bcc336c5b013633d13fd7b30797fbbec8 Mon Sep 17 00:00:00 2001 From: Ankit Ranjan Date: Tue, 11 Aug 2026 16:41:05 +0530 Subject: [PATCH 09/13] docs: simplify descriptions for web search and scoped search tools in start.md --- start.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/start.md b/start.md index b6dc758..1f51f70 100644 --- a/start.md +++ b/start.md @@ -83,8 +83,8 @@ Here is the rubric to shortlist the tools you'll recommend disabling. Here are some tools which you should not recommend disabling. -1. **Web search** — a builtin that takes a query and returns result titles and links without reading the pages. Every harness here except Pi ships one, usually named some spelling of `web_search` (`WebSearch`, `websearch`, or a "Web Search" toggle in Cursor). Leave it on: Webcmd has no search index of its own, and search is the cheapest way to turn a question into URLs. Webcmd reads the pages that search only names. -2. **Other search tools** — the same reasoning covers scoped search builtins: Hermes' `x_search`, OpenClaw's `x_search` and `search_news`. They return links, not page content. +1. **Web search** — a builtin that takes a query and returns result titles and links without reading the pages. Every harness here except Pi ships one, usually named some spelling of `web_search` (`WebSearch`, `websearch`, or a "Web Search" toggle in Cursor). +2. **Other search tools** — the same reasoning covers scoped search builtins: For example Hermes's `x_search`. **Real world example**: In a hermes environment, when xAI plugin is enabled here is the set of tools which are present: From f551b87a32dda766b7a085e4a56466767fcc2c67 Mon Sep 17 00:00:00 2001 From: Ankit Ranjan Date: Tue, 11 Aug 2026 16:46:21 +0530 Subject: [PATCH 10/13] docs: align all seven harness pages with the researched tool inventory Keep web search everywhere; disable only fetch and open-web browser tools. Per-harness corrections from primary docs: Claude Code keeps WebSearch and gains the Browser-pane MCP tools; Codex has nothing to disable and should move off the stale "cached" default; OpenCode keeps websearch; Cursor's Web is its search tool while Browser is the overlap; Hermes toggles toolsets not tools, so web_extract cannot be dropped without losing web_search; OpenClaw keeps its three search tools and disables the browser via browser.enabled; Pi's competing surface is entirely user-installed. Co-Authored-By: Claude Opus 5 --- docs/agents/claude-code.md | 27 ++++++++++++++++++++++----- docs/agents/codex-cli.md | 20 +++++++++++++++----- docs/agents/cursor.md | 23 ++++++++++++++--------- docs/agents/hermes.md | 22 ++++++++++++++++------ docs/agents/openclaw.md | 35 +++++++++++++++++++++++++++++------ docs/agents/opencode.md | 14 +++++++++----- docs/agents/pi.md | 20 ++++++++++++++------ 7 files changed, 119 insertions(+), 42 deletions(-) diff --git a/docs/agents/claude-code.md b/docs/agents/claude-code.md index ec7253d..f0fba88 100644 --- a/docs/agents/claude-code.md +++ b/docs/agents/claude-code.md @@ -34,22 +34,38 @@ 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 @@ -58,7 +74,8 @@ Denying these tools does not affect the Bash tool, which is how `webcmd` is driv | --- | --- | | `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`. | -| Claude Code still uses `WebFetch` / `WebSearch` | Confirm `permissions.deny` lists both in the active settings file, then restart `claude`. | +| Claude Code still uses `WebFetch` | Confirm `permissions.deny` lists it in the active settings file, then restart `claude`. | +| `WebSearch` was denied and search stopped working | Expected. Remove it from `permissions.deny` — Webcmd does not replace search. | | `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 index f184d2d..7381b74 100644 --- a/docs/agents/codex-cli.md +++ b/docs/agents/codex-cli.md @@ -34,15 +34,24 @@ 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 @@ -50,7 +59,8 @@ The setting removes only the search tool; it does not affect the shell tool, whi | --- | --- | | `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 index 16f1dc2..ed5af67 100644 --- a/docs/agents/cursor.md +++ b/docs/agents/cursor.md @@ -33,21 +33,22 @@ 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, and they get different treatment. Webcmd replaces **Web** (search and fetch external documentation). **Browser** (navigate, click, screenshot running apps) is attached to Cursor's dev server, so keep it for localhost work. +Cursor's agent ships two native web tools: -Cursor has no config key that removes either tool, so use an always-applied rule. 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: Route open-web work to Webcmd; keep Cursor's Browser tool for the local dev loop. +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 Web tool (search/fetch). Use Webcmd instead. - -Use Webcmd for anything on the open web — research, fetching, authenticated +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. @@ -57,11 +58,15 @@ third-party sites, multi-step automation, workflows worth making reusable: 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. -**Full override (opt-in).** If you never debug local apps through Cursor's browser, drop the last paragraph of the rule and set the Browser Automation dropdown in the agent window to **Off** so the built-in browser is not attached at all. +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 @@ -69,8 +74,8 @@ The `alwaysApply: true` rule is injected into every Cursor session. | --- | --- | | `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 uses its Web tool instead of Webcmd | Confirm `.cursor/rules/webcmd-browser.mdc` has `alwaysApply: true`. | -| Cursor uses its Browser tool for external sites | Confirm the rule file says to use Webcmd for the open web; for a hard block, 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 index c1137c4..3da0be3 100644 --- a/docs/agents/hermes.md +++ b/docs/agents/hermes.md @@ -40,13 +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). It is attached to Hermes' local dev server, so keep it enabled by default. +Hermes' web surface spans three toolsets: -Add this to your Hermes system prompt or project instructions: +| 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 | -> Use Webcmd (`webcmd list`, `webcmd browser ...` via the `terminal` toolset) for anything on the open web: research, fetching, authenticated third-party sites, multi-step automation. Use the `browser_*` tools only for the app being edited — localhost dev server, console and network triage, visual checks. +`web_search` lives in `web`, not in `browser`, so disabling `browser` leaves search intact. -**Full override (opt-in).** If you never debug local apps through Hermes' browser, disable the toolset outright: +**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 ...` 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 @@ -62,8 +72,6 @@ agent: Recommended: use `hermes tools disable browser` so the terminal toolset stays available. -Note: `web_search` lives in the separate `web` toolset, not in `browser`, so disabling `browser` leaves search intact. Keep `web_search` — Webcmd has no search index of its own and reads the pages search only names. `web_extract` is the tool in that toolset worth disabling. - Do not disable the `terminal` toolset — that is how Hermes runs `webcmd`. ### Troubleshooting @@ -74,6 +82,8 @@ Do not disable the `terminal` toolset — that is how Hermes runs `webcmd`. | Skills not loading in Hermes | Confirm `skills.external_dirs` includes `~/.agents/skills`, restart Hermes, and check skill discovery. | | 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`. | diff --git a/docs/agents/openclaw.md b/docs/agents/openclaw.md index 6c96a71..8f65f1a 100644 --- a/docs/agents/openclaw.md +++ b/docs/agents/openclaw.md @@ -34,21 +34,43 @@ Restart the Gateway (or start a new session) after installing skills. ### Override default tools -OpenClaw's built-in web tools split into two groups. Webcmd replaces the fetch and search tools; deny them in the Gateway config (`~/.openclaw/openclaw.json`): +Deny `web_fetch`. It is an HTTP fetch with readable extraction and does not execute JavaScript, so it fails on exactly the dynamic sites Webcmd handles. In the Gateway config (`~/.openclaw/openclaw.json`): ```json { "tools": { - "deny": ["web_search", "web_fetch", "x_search", "search_news"] + "deny": ["web_fetch"] } } ``` -Keep `browser` and `browser_visual`. They are wired into OpenClaw's dev loop, so use them for the app being edited — localhost dev server, console and network triage, visual checks — and route open-web work to Webcmd. State that split in your OpenClaw system prompt or project instructions. +**Keep the search tools** — `web_search` (backed by Brave, Gemini, Grok, Kimi, or Perplexity), `x_search`, and `search_news`. Webcmd has no search index of its own, so search stays the cheapest way to find URLs for Webcmd to read. + +The `browser` tool is a single tool with subcommands (`doctor`, `status`, `start`, `stop`, `tabs`, `open`, `focus`, `close`, `snapshot`, `screenshot`, `navigate`, `act`). It reaches both localhost and the open web, so keep it for the app being edited and route open-web work to Webcmd. State that split in your OpenClaw system prompt or project instructions. + +Worth raising with the user: OpenClaw's browser has a `user` profile that reuses their existing signed-in sessions, which overlaps directly with Webcmd's auth profiles. Its isolated `openclaw` profile does not. The Gateway watches the config file and applies changes automatically. Denying these tools does not affect the `exec` tool, which is how `webcmd` is driven. -**Full override (opt-in).** If you never debug local apps through OpenClaw's browser, add `"browser"` and `"browser_visual"` to the deny list so all web access goes through Webcmd. +**Full override (opt-in).** If the user never debugs local apps through OpenClaw's browser, disable it outright: + +```json +{ + "browser": { "enabled": false } +} +``` + +Or remove it entirely — CLI, `browser.request` gateway method, and agent tool — by disabling the plugin: + +```json +{ + "plugins": { + "entries": { + "browser": { "enabled": false } + } + } +} +``` ### Troubleshooting @@ -56,8 +78,9 @@ The Gateway watches the config file and applies changes automatically. Denying t | --- | --- | | `webcmd doctor` is red | Fix the browser runtime first; browser commands depend on it. | | Skills not loading in OpenClaw | Run `webcmd skills add` with the `agents` provider, then restart the Gateway. | -| OpenClaw still uses `web_search` / `web_fetch` | Confirm `tools.deny` lists the tool IDs in `~/.openclaw/openclaw.json`; the Gateway hot-reloads config. | -| OpenClaw uses `browser` for external sites | Remind it that Webcmd handles the open web; for a hard block, add `browser` and `browser_visual` to `tools.deny`. | +| OpenClaw still uses `web_fetch` | Confirm `tools.deny` lists it in `~/.openclaw/openclaw.json`; the Gateway hot-reloads config. | +| OpenClaw uses `browser` for external sites | Remind it that Webcmd handles the open web; for a hard block, set `browser.enabled: false`. | +| Search stopped working | Check whether `web_search` was denied. Webcmd does not replace search — remove it from `tools.deny`. | | `webcmd` not found in OpenClaw exec | Confirm `webcmd` is on the PATH the Gateway's `exec` tool 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/opencode.md b/docs/agents/opencode.md index 476f78f..a880c36 100644 --- a/docs/agents/opencode.md +++ b/docs/agents/opencode.md @@ -34,27 +34,31 @@ Restart OpenCode after changing config. Confirm the skill loads with `/skills` a ### Override default tools -OpenCode's native web tools are `webfetch` (fetch a URL) and `websearch` (search). Deny both so OpenCode cannot fall back to them while Webcmd is its browser surface. Do not add a legacy `tools` block as well; `permission` is the supported field. Denying the tools does not turn off the Bash tool, which is how `webcmd browser` is driven. +OpenCode's native web tools are `webfetch` (fetch a URL) and `websearch` (search). OpenCode has no browser tool. -Add to `opencode.json`: +Deny `webfetch` so OpenCode cannot fall back to it while Webcmd is its browser surface. Add to `opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "permission": { - "webfetch": "deny", - "websearch": "deny" + "webfetch": "deny" } } ``` +**Keep `websearch`.** Webcmd has no search index of its own, so search stays useful — it turns a question into URLs that Webcmd then reads. Note that `websearch` only registers when the OpenCode provider is in use or `OPENCODE_ENABLE_EXA=1` is set, so it may already be absent. + +`permission` values are `allow`, `deny`, and `ask`, and wildcards work (`"mymcp_*": "deny"`) — useful if the user has a browser or scraping MCP that overlaps with Webcmd. Do not add a legacy `tools` block as well; `permission` is the supported field. Denying tools does not turn off the Bash tool, which is how `webcmd browser` 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 OpenCode | Run `webcmd skills add` with the `agents` provider, restart OpenCode, and check `/skills`. | -| OpenCode still uses `webfetch` / `websearch` | Confirm `permission.webfetch` and `permission.websearch` are `deny` in the active config, then restart OpenCode. | +| OpenCode still uses `webfetch` | Confirm `permission.webfetch` is `deny` in the active config, then restart OpenCode. | +| `websearch` is missing entirely | It registers only with the OpenCode provider or `OPENCODE_ENABLE_EXA=1`. Not a Webcmd problem. | | `webcmd browser` errors | Read `webcmd-usage` and `webcmd-browser` skills; sessions require a `` name after `browser`. | | 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/pi.md b/docs/agents/pi.md index 5dae433..9bdffa7 100644 --- a/docs/agents/pi.md +++ b/docs/agents/pi.md @@ -41,14 +41,21 @@ Project skills under `.pi/skills` and `.agents/skills` load only after the proje ### Override default tools -Pi has no built-in web, search, or browser tools, so there is nothing to turn off. Webcmd works through the default `bash` tool as soon as the CLI is on PATH. +Pi ships seven built-in tools — `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls` — and no web, search, or browser tool at all, so there is nothing built in to turn off. Webcmd works through `bash` as soon as the CLI is on PATH. Do not reach for `--no-builtin-tools`: it strips `read`/`write`/`edit`/`bash`, and `bash` is how Webcmd runs. -If you also installed the official [pi-skills](https://github.com/badlogic/pi-skills) collection, two skills overlap with Webcmd: +Pi is the harness where competing tools are most likely to come from what the user installed, since every web capability it has is an extension or skill. Check for these and ask before removing any: -* `brave-search` — web search and content extraction via the Brave Search API -* `browser-tools` — browser automation via the Chrome DevTools Protocol (Chrome on `:9222`) +| Installed | Overlaps | What to do | +| --- | --- | --- | +| [`pi-skills/browser-tools`](https://github.com/badlogic/pi-skills/tree/main/browser-tools) | Browser automation over CDP (Chrome on `:9222`) | Recommend removing, or tell Pi to prefer Webcmd | +| [`pi-agent-browser-native`](https://github.com/fitchmultz/pi-agent-browser-native) | Exposes agent-browser as a native tool | Recommend removing | +| [`pi-web-fetch`](https://github.com/georgebashi/pi-web-fetch) | Headless-Chrome fetch plus trafilatura extraction | Recommend removing | +| [`pi-web-access`](https://github.com/nicobailon/pi-web-access) | Search **and** content extraction | Keep the search half; set `webSearch.enabled: false` only if the user wants search gone too | +| `pi-skills/brave-search` | Brave Search API, plus content extraction | Keep it for search; tell Pi to prefer Webcmd for reading pages | -If both are present, tell Pi to prefer Webcmd, or remove the competing folders (for example `~/.pi/agent/skills/pi-skills/browser-tools`) so the model does not fall back to them. +Extensions that mix search with extraction are the awkward case: the search half is worth keeping, and only some expose a config toggle to split them. When there is no toggle, steer Pi with instructions instead of removing the extension. + +To remove one outright, delete its folder — for example `~/.pi/agent/skills/pi-skills/browser-tools` — and restart Pi. ### Troubleshooting @@ -56,7 +63,8 @@ If both are present, tell Pi to prefer Webcmd, or remove the competing folders ( | --- | --- | | `webcmd doctor` is red | Fix the browser runtime first; browser commands depend on it. | | Skills not surfacing in Pi | Confirm links exist under `~/.agents/skills/`, `.agents/skills/`, `~/.pi/agent/skills/`, or `.pi/skills/` (rerun `webcmd skills add`), ensure the project is trusted, then restart Pi. | -| Pi still uses `brave-search` / `browser-tools` | Remove those skill folders or prompt Pi to prefer Webcmd. | +| Pi still uses `browser-tools` or a web-fetch extension | Remove the skill folder or prompt Pi to prefer Webcmd, then restart Pi. | +| Search stopped working after removing an extension | Some extensions bundle search with extraction. Reinstall it and steer Pi with instructions instead — Webcmd does not replace search. | | `webcmd` not found in Pi's shell | Confirm `webcmd` is on the PATH Pi's `bash` tool uses; restart Pi 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`. | From 43ee40bff496d1ffb2f4add4e4ca506da8d87573 Mon Sep 17 00:00:00 2001 From: Ankit Ranjan Date: Tue, 11 Aug 2026 18:02:41 +0530 Subject: [PATCH 11/13] docs: document marketplace install on the Claude Code and Codex pages Both pages now lead with the plugin path and keep `webcmd skills add` as the manual alternative, with a warning against doing both. Commands were verified against the locally installed claude and codex CLIs. Co-Authored-By: Claude Opus 5 --- docs/agents/claude-code.md | 24 +++++++++++++++++++++++- docs/agents/codex-cli.md | 24 +++++++++++++++++++++++- start.md | 2 +- 3 files changed, 47 insertions(+), 3 deletions(-) diff --git a/docs/agents/claude-code.md b/docs/agents/claude-code.md index f0fba88..4eb4569 100644 --- a/docs/agents/claude-code.md +++ b/docs/agents/claude-code.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 +claude plugin marketplace add agentrhq/webcmd +``` + +```bash +claude plugin install webcmd@webcmd +``` + +Or from inside a session, with the slash-command equivalents: `/plugin marketplace add agentrhq/webcmd`, then `/plugin install webcmd@webcmd`. + +Pin to a branch or tag by appending `@ref` to the source: `claude plugin marketplace add agentrhq/webcmd@v1.0`. Both commands take `--scope user` (default), `project`, or `local`; use `--scope project` to commit the marketplace so the whole team gets it. + +The plugin bundles all seven Webcmd skills. Start a new session after installing. + +Useful follow-ups: `claude plugin list`, `claude plugin uninstall webcmd`, `claude plugin marketplace update webcmd`. + +#### Manual ```bash npm install -g @agentrhq/webcmd diff --git a/docs/agents/codex-cli.md b/docs/agents/codex-cli.md index 7381b74..48a49be 100644 --- 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 `. + +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 diff --git a/start.md b/start.md index 1f51f70..eacb1c2 100644 --- a/start.md +++ b/start.md @@ -111,7 +111,7 @@ For instructions on how to disable tools for a specific harness, refer to the do | Hermes Agent | [hermes.md](docs/agents/hermes.md#override-default-tools) | | Pi | [pi.md](docs/agents/pi.md#override-default-tools) | | OpenClaw | [openclaw.md](docs/agents/openclaw.md#override-default-tools) | -| Other Coding Agents | see their officical docs | +| Other Coding Agents | see their official docs | ### 5. Finish From 8320f0845d97b55b9d80978d27f0c33cfcf0974e Mon Sep 17 00:00:00 2001 From: ngaurav Date: Tue, 11 Aug 2026 15:04:28 +0530 Subject: [PATCH 12/13] docs: restore manual quick start in README (#275) --- README.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 40ea147..fcf2af0 100644 --- 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 -f json +webcmd plugin install +``` + +```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 From 2266a3eada7fda41c228dc732d77eb39857e003f Mon Sep 17 00:00:00 2001 From: Ankit Ranjan Date: Tue, 11 Aug 2026 18:02:19 +0530 Subject: [PATCH 13/13] feat: add Claude Code plugin marketplace manifest (#273) Claude Code discovers marketplaces via .claude-plugin/marketplace.json, so `claude plugin marketplace add agentrhq/webcmd` failed against the existing Codex-only manifests. Add the Claude Code marketplace and plugin manifests pointing at the repo root, so the seven bundled skills install as a plugin. Wire the new manifest version into release-please and extend the plugin metadata check to keep both manifests in sync with package.json. Co-authored-by: Claude Opus 5 --- .claude-plugin/marketplace.json | 17 +++++++++++++++++ .claude-plugin/plugin.json | 18 ++++++++++++++++++ docs/agents/claude-code.md | 27 ++++++++------------------- docs/quickstart.mdx | 10 ++++++++++ release-please-config.json | 5 +++++ scripts/check-codex-plugin.mjs | 16 +++++++++++++++- 6 files changed, 73 insertions(+), 20 deletions(-) create mode 100644 .claude-plugin/marketplace.json create mode 100644 .claude-plugin/plugin.json diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..528ebe3 --- /dev/null +++ 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 new file mode 100644 index 0000000..abc91a4 --- /dev/null +++ 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/docs/agents/claude-code.md b/docs/agents/claude-code.md index 4eb4569..83fb138 100644 --- a/docs/agents/claude-code.md +++ b/docs/agents/claude-code.md @@ -18,31 +18,20 @@ 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 - -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: +### Install the plugin ```bash claude plugin marketplace add agentrhq/webcmd -``` - -```bash claude plugin install webcmd@webcmd ``` -Or from inside a session, with the slash-command equivalents: `/plugin marketplace add agentrhq/webcmd`, then `/plugin install webcmd@webcmd`. - -Pin to a branch or tag by appending `@ref` to the source: `claude plugin marketplace add agentrhq/webcmd@v1.0`. Both commands take `--scope user` (default), `project`, or `local`; use `--scope project` to commit the marketplace so the whole team gets it. +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. -The plugin bundles all seven Webcmd skills. Start a new session after installing. +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. -Useful follow-ups: `claude plugin list`, `claude plugin uninstall webcmd`, `claude plugin marketplace update webcmd`. +### Install and configure without the plugin -#### Manual +Install Webcmd and its skills: ```bash npm install -g @agentrhq/webcmd @@ -95,9 +84,9 @@ Denying these tools does not affect the Bash tool, which is how `webcmd` is driv | 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`. | -| Claude Code still uses `WebFetch` | Confirm `permissions.deny` lists it in the active settings file, then restart `claude`. | -| `WebSearch` was denied and search stopped working | Expected. Remove it from `permissions.deny` — Webcmd does not replace search. | +| 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/quickstart.mdx b/docs/quickstart.mdx index 94613eb..adbde84 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -15,6 +15,16 @@ the npm CLI automatically if `webcmd` is missing. The plugin includes all seven bundled Webcmd skills. Do not also add those skills with `webcmd skills add` in Codex. +## Install the Claude Code 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` in Claude Code. + ## Other Agents or Plugin-Free Setup Webcmd requires Node.js 20.6+ and a place where your agent harness can run its diff --git a/release-please-config.json b/release-please-config.json index b437fff..01f862f 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -12,6 +12,11 @@ "type": "json", "path": ".codex-plugin/plugin.json", "jsonpath": "$.version" + }, + { + "type": "json", + "path": ".claude-plugin/plugin.json", + "jsonpath": "$.version" } ] } diff --git a/scripts/check-codex-plugin.mjs b/scripts/check-codex-plugin.mjs index d5596f1..d6e9c8b 100644 --- a/scripts/check-codex-plugin.mjs +++ b/scripts/check-codex-plugin.mjs @@ -13,6 +13,9 @@ const packageJson = readJson('package.json'); const manifest = readJson('.codex-plugin/plugin.json'); const marketplace = readJson('.agents/plugins/marketplace.json'); const marketplacePlugin = marketplace.plugins?.[0]; +const claudeManifest = readJson('.claude-plugin/plugin.json'); +const claudeMarketplace = readJson('.claude-plugin/marketplace.json'); +const claudeMarketplacePlugin = claudeMarketplace.plugins?.[0]; assert.equal(manifest.name, 'webcmd'); assert.equal(manifest.version, packageJson.version); @@ -27,6 +30,15 @@ assert.deepEqual(marketplacePlugin?.source, { url: './', }); +assert.equal(claudeManifest.name, 'webcmd'); +assert.equal(claudeManifest.version, packageJson.version); +assert.equal(claudeManifest.author?.name, 'AgentRHQ'); +assert.equal(claudeMarketplace.name, 'webcmd'); +assert.equal(claudeMarketplace.owner?.name, 'AgentRHQ'); +assert.equal(claudeMarketplace.plugins?.length, 1); +assert.equal(claudeMarketplacePlugin?.name, 'webcmd'); +assert.equal(claudeMarketplacePlugin?.source, './'); + const expectedSkills = [ 'smart-search', 'webcmd-adapter-author', @@ -54,4 +66,6 @@ assert.match(usageSkill, /## CLI Preflight/); assert.match(usageSkill, /webcmd --version/); assert.match(usageSkill, /npm install -g @agentrhq\/webcmd/); -console.log(`Codex plugin metadata valid: ${actualSkills.length} skills`); +console.log( + `Codex and Claude Code plugin metadata valid: ${actualSkills.length} skills`, +);