diff --git a/docs/agents/aider.md b/docs/agents/aider.md new file mode 100644 index 00000000..5075daf1 --- /dev/null +++ b/docs/agents/aider.md @@ -0,0 +1,96 @@ +--- +title: Aider +sidebarTitle: Aider +--- + +## Agent prompt + +```text +Fetch and follow https://raw.githubusercontent.com/agentrhq/webcmd/main/start.md to set up Webcmd end to end. +``` + +## Manual + +### Requirements + +* Node.js 20.6+ +* The `webcmd` npm CLI, installed globally or in the project +* [Aider](https://aider.chat/docs/) (`aider`), installed and configured with an LLM +* A browser runtime; confirm with `webcmd doctor` before browser work + +### Install and configure + +Aider has no skills system. Install Webcmd and load its skill instructions as read-only context: + +```bash +npm install -g @agentrhq/webcmd +webcmd doctor +webcmd skills add +``` + +When `webcmd skills add` prompts, choose the `agents` provider. It installs into `~/.agents/skills/` (user) or `.agents/skills/` (project). + +Then add those skill files to Aider's `read` list in `.aider.conf.yml` at your repo root or home directory: + +```yaml +read: + - ~/.agents/skills/webcmd-usage/SKILL.md + - ~/.agents/skills/webcmd-browser/SKILL.md +``` + +Aider loads `read` files at startup as read-only reference and caches them when prompt caching is enabled. Restart Aider after changing config. + +For a project-scoped setup, use `.agents/skills/` paths relative to the repo: + +```yaml +read: + - .agents/skills/webcmd-usage/SKILL.md + - .agents/skills/webcmd-browser/SKILL.md +``` + +### Override default tools + +Aider's built-in tools are file editing, git, linting, and shell access through `/run` (alias `!`). It has no search tool and no browser automation tool. + +The overlap is `/web`, which scrapes a URL into markdown using `httpx` or Playwright. That is a one-shot fetch — it does not handle JavaScript-heavy pages, authenticated sessions, or multi-step workflows the way Webcmd does. Prefer `/run webcmd ...` instead. + +Add this to your conventions file (for example `CONVENTIONS.md`) and include it in the `read` list alongside the Webcmd skills: + +```markdown +# Webcmd for the open web + +When a task needs web content, authenticated sites, or browser automation: + +- Run `webcmd list -f json` first to check for an existing adapter. +- Use `/run webcmd ...` (or `!webcmd ...`) to drive Webcmd from the shell. +- For interactive browser work, create a named session: `webcmd --profile work session create "Work Project"`, then pass its readable ID to later commands. +- For login walls, use Webcmd's human handoff; never type passwords, OTPs, cookies, or credentials. + +Do not use `/web` when Webcmd can handle the task. `/web` is a lossy scrape; Webcmd returns real page content and supports sessions. +``` + +To stop Aider from auto-offering `/web` when it detects URLs in your messages, set in `.aider.conf.yml`: + +```yaml +detect-urls: false +``` + +Aider has no search index. When you need to discover URLs, find them yourself or pipe search results into the chat — Webcmd reads the pages that search finds. + +### Troubleshooting + +| Symptom | What to try | +| --- | --- | +| `webcmd doctor` is red | Fix the browser runtime first; browser commands depend on it. | +| Aider ignores Webcmd instructions | Confirm the skill files are in the `read` list in `.aider.conf.yml`, then restart Aider. | +| Aider still uses `/web` | Add the conventions guidance above; set `detect-urls: false` to stop URL auto-detection. | +| `/web` keeps prompting for Playwright | Expected on JS-heavy sites. Use Webcmd instead, or install Playwright per [Aider's optional setup](https://aider.chat/docs/install/optional.html). | +| `webcmd` not found in `/run` | Confirm `webcmd` is on the PATH in the shell Aider uses; restart the terminal session. | +| Browser Session idles or loses its window | Keep its immutable, Profile-scoped ID; `webcmd --profile work --session work-project-k7 browser tabs` reopens it. Start with `webcmd --profile work session create "Work Project"`; use `webcmd --profile work session list` and `webcmd --profile work session close work-project-k7` for lifecycle. Adapter commands without `--session` reuse `adapter-default`; raw browser commands require an explicit readable selector. | + +## See also + +* [Aider documentation](https://aider.chat/docs/) — installation, usage, LLM configuration, and in-chat commands. +* [`start.md`](../../start.md) — common setup, [auth profiles and human handoff](../../start.md#auth-profiles-and-human-handoff), and [security](../../start.md#security). +* [`webcmd-browser`](../../skills/webcmd-browser/SKILL.md) — the raw browser session surface. +* [`webcmd-usage`](../../skills/webcmd-usage/SKILL.md) — adapter-first usage rules. diff --git a/docs/agents/cline.md b/docs/agents/cline.md new file mode 100644 index 00000000..922d5d11 --- /dev/null +++ b/docs/agents/cline.md @@ -0,0 +1,95 @@ +--- +title: Cline +sidebarTitle: Cline +--- + +## Agent prompt + +```text +Fetch and follow https://raw.githubusercontent.com/agentrhq/webcmd/main/start.md to set up Webcmd end to end. +``` + +## Manual + +### Requirements + +* Node.js 20.6+ +* The `webcmd` npm CLI, installed globally or in the project +* Cline — the [VS Code extension](https://docs.cline.bot/cline-overview), [CLI](https://docs.cline.bot/usage/cli-overview), or JetBrains plugin +* A browser runtime; confirm with `webcmd doctor` before browser work + +### Install and configure + +Install Webcmd and its skills into Cline's skill directories: + +```bash +npm install -g @agentrhq/webcmd +webcmd doctor +webcmd skills add --path ~/.cline/skills +``` + +For a project-scoped setup that travels with the repo: + +```bash +webcmd skills add --path .cline/skills --scope project +``` + +Cline also discovers skills in `~/.cline/skills/`, `.cline/skills/`, and `.claude/skills/`. It loads skill metadata at startup and activates `webcmd-usage` and `webcmd-browser` on demand through its `use_skill` tool. + +Restart Cline (or start a new task) after installing skills. In the extension, confirm they appear under the Skills tab (scale icon in the Cline panel). + +### Override default tools + +Cline's web surface depends on which app you are using: + +| Surface | Tools | What to do | +| --- | --- | --- | +| ClineCore (CLI, SDK, Kanban) | `fetch_web` | Prefer Webcmd over `fetch_web` for reading pages | +| IDE extension (Cline provider) | `web_fetch`, `web_search`, `browser_action` | Keep `web_search`; prefer Webcmd over `web_fetch` and `browser_action` on the open web | + +`fetch_web` and `web_fetch` are lossy fetches — HTTP with HTML-to-markdown conversion, no real browser session. Webcmd returns authenticated, JavaScript-rendered content and supports multi-step automation. **Keep `web_search`.** Webcmd has no search index of its own. + +Cline has no per-tool deny list like OpenCode. Steer it with a rule in `.clinerules/webcmd.md`: + +```markdown +# Webcmd for the open web + +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 run `webcmd --profile work session create "Work Project"`, then drive its returned readable ID with `webcmd --profile work --session work-project-k7 browser tabs` via `bash`. +- Run `webcmd doctor` first; use `webcmd --profile work session list` to inspect state and `webcmd --profile work session close work-project-k7` when finished. +- For login walls, use Webcmd's human handoff; never type passwords, OTPs, cookies, or credentials. + +Use Cline's `web_search` to find URLs, then Webcmd to read them. + +Use `browser_action` only for the app being edited: localhost dev server, console and network triage, visual checks after a change. + +Do not use `fetch_web`, `web_fetch`, or `browser_action` for external third-party sites when Webcmd can handle the task. +``` + +Commit `.clinerules/webcmd.md` so the whole team gets the split. Toggle it on in the Rules panel (scale icon → Rules tab). + +**Full override (opt-in).** In the IDE extension, turn off **Web Tools** under Cline Settings → Feature Settings. That removes `web_fetch` and `web_search` for the Cline provider — only do this if search is not needed. For a hard block on browser automation, leave Web Tools enabled but deny approval for **Use the browser** in Auto Approve settings. + +Denying web tools does not affect the `bash` tool, which is how `webcmd` is driven. + +Check for browser or scraping MCP servers in `.cline/mcp.json` — they overlap with Webcmd the same way native browser tools do. Disable or remove servers the user does not need. + +### Troubleshooting + +| Symptom | What to try | +| --- | --- | +| `webcmd doctor` is red | Fix the browser runtime first; browser commands depend on it. | +| Skills not loading in Cline | Confirm symlinks exist under `~/.cline/skills/` or `.cline/skills/`, then restart Cline or start a new task. | +| Cline still uses `fetch_web` / `web_fetch` | Confirm `.clinerules/webcmd.md` is toggled on in the Rules panel. | +| `web_search` missing | Web Tools require the Cline provider and the Web Tools toggle in Feature Settings. Not a Webcmd problem. | +| `webcmd` not found in Cline shell | Confirm `webcmd` is on the PATH Cline's `bash` tool uses; restart after installing the CLI. | +| Browser Session idles or loses its window | Keep its immutable, Profile-scoped ID; `webcmd --profile work --session work-project-k7 browser tabs` reopens it. Start with `webcmd --profile work session create "Work Project"`; use `webcmd --profile work session list` and `webcmd --profile work session close work-project-k7` for lifecycle. Adapter commands without `--session` reuse `adapter-default`; raw browser commands require an explicit readable selector. | + +## See also + +* [Cline documentation](https://docs.cline.bot/cline-overview) — installation, providers, and the core workflow. +* [`start.md`](../../start.md) — common setup, [auth profiles and human handoff](../../start.md#auth-profiles-and-human-handoff), and [security](../../start.md#security). +* [`webcmd-browser`](../../skills/webcmd-browser/SKILL.md) — the raw browser session surface. +* [`webcmd-usage`](../../skills/webcmd-usage/SKILL.md) — adapter-first usage rules. diff --git a/docs/agents/codex-cli.md b/docs/agents/codex-cli.md index b93e5505..8303f8d3 100644 --- a/docs/agents/codex-cli.md +++ b/docs/agents/codex-cli.md @@ -1,6 +1,6 @@ --- -title: Codex CLI Agent -sidebarTitle: Codex CLI +title: Codex CLI +sidebarTitle: Codex --- ## Agent prompt diff --git a/docs/agents/openclaw.md b/docs/agents/openclaw.md index 59582a9d..5b1dc30e 100644 --- a/docs/agents/openclaw.md +++ b/docs/agents/openclaw.md @@ -1,5 +1,5 @@ --- -title: OpenClaw Agent +title: OpenClaw sidebarTitle: OpenClaw --- diff --git a/docs/agents/opencode.md b/docs/agents/opencode.md index 9b697a49..d6dbe243 100644 --- a/docs/agents/opencode.md +++ b/docs/agents/opencode.md @@ -1,5 +1,5 @@ --- -title: OpenCode Agent +title: OpenCode sidebarTitle: OpenCode --- diff --git a/docs/docs.json b/docs/docs.json index fb5fb94a..d08614b8 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -49,14 +49,16 @@ { "group": "Agent Harnesses", "pages": [ - "agents/cursor", - "agents/opencode", + "agents/aider", "agents/claude-code", + "agents/cline", "agents/codex-cli", + "agents/cursor", + "agents/custom-sdk", "agents/hermes", - "agents/pi", "agents/openclaw", - "agents/custom-sdk" + "agents/opencode", + "agents/pi" ] }, {