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/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 diff --git a/docs/agents/claude-code.md b/docs/agents/claude-code.md index ec7253d..83fb138 100644 --- a/docs/agents/claude-code.md +++ b/docs/agents/claude-code.md @@ -18,7 +18,18 @@ Fetch and follow https://raw.githubusercontent.com/agentrhq/webcmd/main/start.md * Claude Code (`claude`), installed globally or in the project * A browser runtime; confirm with `webcmd doctor` before browser work -### Install and configure +### Install the plugin + +```bash +claude plugin marketplace add agentrhq/webcmd +claude plugin install webcmd@webcmd +``` + +This installs all seven bundled Webcmd skills. Do not also add those skills with `webcmd skills add`; running both leaves two copies that can sit at different versions. + +Plugin updates are version-gated, not commit-gated. Run `claude plugin update webcmd@webcmd` to pick up a new release; it is separate from `webcmd update`, which upgrades only the npm CLI. + +### Install and configure without the plugin Install Webcmd and its skills: @@ -34,22 +45,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 @@ -57,7 +84,8 @@ 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`. | +| Skills not loading in Claude Code | Run `webcmd skills add` with the `claude` provider, then restart `claude`. With the plugin, run `claude plugin install webcmd@webcmd` and restart. | +| Skill text looks out of date | `webcmd update` upgrades only the CLI. Run `claude plugin update webcmd@webcmd` to refresh plugin skills. | | Claude Code still uses `WebFetch` / `WebSearch` | Confirm `permissions.deny` lists both in the active settings file, then restart `claude`. | | `claude` requires permission prompts for `webcmd` | The Bash tool still asks before non-approved commands; run `claude --dangerously-skip-permissions` or allow the shell command if you accept the risk. | | Browser sessions stop working after idle | Ask the agent to open a fresh session or re-bind with `tabs` and `bind --page`. | diff --git a/docs/agents/codex-cli.md b/docs/agents/codex-cli.md index f184d2d..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 @@ -34,15 +56,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 +81,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 6b13914..ed5af67 100644 --- a/docs/agents/cursor.md +++ b/docs/agents/cursor.md @@ -33,29 +33,40 @@ For a project-scoped setup, copy the `webcmd-*` skill folders into the project's ### Override default tools -Cursor's agent ships two native web tools: **Browser** (navigate, click, screenshot running apps) and **Web** (search and fetch external documentation). Cursor has no single config key that removes them, so replace them with an always-applied rule that forces Webcmd usage. +Cursor's agent ships two native web tools: -Add `.cursor/rules/webcmd-browser.mdc`: +* **Web** — generates search queries and performs web searches. This is Cursor's search tool. **Keep it on** (Settings has a "Web Search Tool" toggle); Webcmd has no search index of its own. +* **Browser** — navigate, click, type, scroll, screenshot, plus console logs and network traffic. It has dev-server awareness for localhost but can navigate anywhere on the web, so it is the tool that overlaps with Webcmd. + +Cursor has no config key that removes the Browser tool for individual users, so steer it with an always-applied rule. Add `.cursor/rules/webcmd-browser.mdc`: ```markdown --- -description: Use Webcmd for all browser automation instead of Cursor's built-in Browser and Web tools. +description: Use Webcmd for the open web; keep Cursor's Browser tool for the local dev loop. globs: - "**/*" alwaysApply: true --- -Do not use your native Browser tool (navigate/click/screenshot) or your Web tool (search/fetch) for browser work. - -Use Webcmd instead: +Use Webcmd for anything on the open web — fetching, authenticated +third-party sites, multi-step automation, workflows worth making reusable: - Check `webcmd list -f json` for an adapter that covers the task; use it first. - Otherwise drive a live browser with `webcmd browser ...` via the shell tool. - Run `webcmd doctor` first and keep the session lifecycle (`tabs`, `bind`, `snapshot`, `run`, `close`). - For login walls, use Webcmd's human handoff; never type passwords, OTPs, cookies, or credentials. + +Use the native Browser tool only for the app being edited: localhost dev server, +console and network triage, visual checks after a change. + +Keep using the Web tool to search. Webcmd reads the pages that search finds. ``` -The `alwaysApply: true` rule is injected into every Cursor session, so the agent does not fall back to its native Browser/Web tools. You can also set the Browser Automation dropdown in the agent window to **Off** so the built-in browser is not attached at all. +The `alwaysApply: true` rule is injected into every Cursor session. + +Note that the rule is guidance, not a block. Cursor's Browser Automation has been reported to enable itself when a prompt mentions "browser", and the user-level switch to turn it off has come and gone across releases — so expect the agent to reach for it occasionally even with the rule in place. + +**Full override (opt-in).** If the user never debugs local apps through Cursor's browser, drop the Browser paragraph from the rule and set Browser Automation to **Off** in the agent window. On Team and Enterprise plans an admin can also toggle browser features in the Settings Dashboard under MCP Configuration, or restrict the agent to an origin allowlist. ### Troubleshooting @@ -63,7 +74,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 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 bfb42d8..3da0be3 100644 --- a/docs/agents/hermes.md +++ b/docs/agents/hermes.md @@ -40,7 +40,23 @@ Hermes then reads `webcmd-usage` and `webcmd-browser` as skills. Restart Hermes ### Override default tools -Hermes' native browser toolset is `browser` (`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_scroll`, and the rest). Disable it so Hermes does not keep its native browser tools alongside Webcmd: +Hermes' web surface spans three toolsets: + +| Toolset | Tools | What to do | +| --- | --- | --- | +| `web` | `web_search`, `web_extract` | Keep enabled for `web_search`; prefer Webcmd over `web_extract` | +| `browser` | `browser_navigate`, `browser_click`, `browser_type`, `browser_scroll`, `browser_press`, `browser_back`, `browser_snapshot`, `browser_vision`, `browser_console`, `browser_get_images`, plus CDP-gated `browser_cdp` and `browser_dialog` | Keep for localhost, route open-web work to Webcmd | +| `x_search` | `x_search` | Keep — it is search, and it auto-enables whenever xAI credentials are present | + +`web_search` lives in `web`, not in `browser`, so disabling `browser` leaves search intact. + +**Hermes toggles toolsets, not individual tools.** There is no way to drop `web_extract` while keeping `web_search`, so leave the `web` toolset on and steer the agent with instructions instead. Add this to your Hermes system prompt or project instructions: + +> Use Webcmd (`webcmd list`, `webcmd browser ...` via the `terminal` toolset) for anything on the open web: fetching, authenticated third-party sites, multi-step automation. Prefer it over `web_extract`. Use the `browser_*` tools only for the app being edited — localhost dev server, console and network triage, visual checks. Keep using `web_search` and `x_search` to find URLs. + +Also check the `computer_use` toolset. It drives the whole desktop rather than a browser, so it overlaps with Webcmd whenever it is aimed at a website. Disable it if the user does not need desktop control. + +**Full override (opt-in).** If the user never debugs local apps through Hermes' browser, disable the toolset outright: ```bash hermes tools disable browser @@ -56,8 +72,6 @@ agent: Recommended: use `hermes tools disable browser` so the terminal toolset stays available. -Note: Hermes' `browser` toolset statically bundles `web_search`, so disabling `browser` also removes `web_search` from every session. `web_extract` and the rest of the `web` toolset are unaffected. That is acceptable here: Webcmd's `smart-search` skill and adapters cover search, so Hermes should rely on Webcmd for browser work and search. - Do not disable the `terminal` toolset — that is how Hermes runs `webcmd`. ### Troubleshooting @@ -66,8 +80,10 @@ Do not disable the `terminal` toolset — that is how Hermes runs `webcmd`. | --- | --- | | `webcmd doctor` is red | Fix the browser runtime first; browser commands depend on it. | | Skills not loading in Hermes | Confirm `skills.external_dirs` includes `~/.agents/skills`, restart Hermes, and check skill discovery. | -| Hermes still uses `browser_*` tools | Confirm `agent.disabled_toolsets` includes `browser`, then restart Hermes. | -| `web_search` missing after disabling `browser` | Expected: Hermes bundles `web_search` inside the `browser` toolset. Use Webcmd's `smart-search` skill or adapters instead. | +| Hermes uses `browser_*` for open-web work | Remind it in the system prompt that Webcmd handles the open web; for a hard block, add `browser` to `agent.disabled_toolsets` and restart Hermes. | +| `web_search` missing after disabling `browser` | Unexpected — `web_search` is in the `web` toolset. Confirm `web` is still enabled with `hermes tools`. | +| Search disappeared after disabling `web` | Expected: `web_search` and `web_extract` share one toolset. Re-enable `web` and steer the agent with instructions instead. | +| `x_search` appeared on its own | Expected: it auto-registers when `XAI_API_KEY` or Grok OAuth is configured. Leave it — it is search. | | `webcmd` not found in Hermes terminal | Confirm `webcmd` is on the host PATH that Hermes' `terminal` toolset uses; non-interactive shells may skip shell init files. | | Browser sessions stop working after idle | Ask the agent to open a fresh session or re-bind with `tabs` and `bind --page`. | diff --git a/docs/agents/openclaw.md b/docs/agents/openclaw.md index 2525697..8f65f1a 100644 --- a/docs/agents/openclaw.md +++ b/docs/agents/openclaw.md @@ -34,17 +34,43 @@ 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: +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", "browser", "browser_visual"] + "deny": ["web_fetch"] } } ``` -`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 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 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 @@ -52,7 +78,9 @@ 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_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`. | 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`, +); diff --git a/start.md b/start.md index 2da5064..eacb1c2 100644 --- a/start.md +++ b/start.md @@ -66,22 +66,52 @@ 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 - -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: - -| Harness | Native tools Webcmd replaces | 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 | - -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. +### 4. Override installed tools + +Recommend these changes to the user and ask before applying any of them. Do not edit their tool configuration on your own. + +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. **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. **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: + +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 | 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 official docs | ### 5. Finish