{"id":51377483,"url":"https://github.com/agentrhq/webcmd","last_synced_at":"2026-07-03T14:04:48.148Z","repository":{"id":368369522,"uuid":"1271196851","full_name":"agentrhq/webcmd","owner":"agentrhq","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-30T08:35:47.000Z","size":693,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-30T10:05:09.253Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agentrhq.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-16T12:31:04.000Z","updated_at":"2026-06-30T08:35:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/agentrhq/webcmd","commit_stats":null,"previous_names":["agentrhq/webcmd"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/agentrhq/webcmd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentrhq%2Fwebcmd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentrhq%2Fwebcmd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentrhq%2Fwebcmd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentrhq%2Fwebcmd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentrhq","download_url":"https://codeload.github.com/agentrhq/webcmd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentrhq%2Fwebcmd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35088498,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-03T02:00:05.635Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-03T14:04:47.584Z","updated_at":"2026-07-03T14:04:48.120Z","avatar_url":"https://github.com/agentrhq.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg width=\"2054\" height=\"766\" alt=\"Group 54\" src=\"https://github.com/user-attachments/assets/3e5b9702-5ffd-43bd-ab1b-2319a8cc0e2a\" /\u003e\n\n\n# Webcmd\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@agentrhq/webcmd\"\u003e\n    \u003cimg alt=\"NPM version\" src=\"https://img.shields.io/npm/v/@agentrhq/webcmd.svg?style=for-the-badge\u0026color=1E88E5\u0026labelColor=000000\"\u003e\n  \u003c/a\u003e\n\n\u003ca href=\"https://github.com/agentrhq/webcmd/blob/main/LICENSE\"\u003e\n  \u003cimg alt=\"License\" src=\"https://img.shields.io/badge/license-Apache%202.0-1E88E5.svg?style=for-the-badge\u0026labelColor=000000\"\u003e\n\u003c/a\u003e\n\n  \u003ca href=\"https://github.com/agentrhq/webcmd/discussions\"\u003e\n    \u003cimg alt=\"Join the community on GitHub\" src=\"https://img.shields.io/badge/Join%20the%20community-1E88E5.svg?style=for-the-badge\u0026logo=github\u0026labelColor=000000\u0026logoWidth=20\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n**Teach a coding agent a website once. Get back a script it can run forever.**\n\nCoding agents are great at driving a browser and terrible at remembering how. Every session they re-learn the same login, the same clicks, the same fragile selectors. Webcmd records a real browser task session, distills it into a durable capability graph for that app, and materializes the result as a deterministic workflow script or a standalone task CLI — so the next run is one command instead of another exploratory crawl.\n\n\u003e **Screen recording / demo goes here.**\n\n```bash\nnpm install -g @agentrhq/webcmd\nwebcmd setup\n```\n\n---\n\n## How it works\n\nWebcmd turns one messy browser session into reusable, deterministic artifacts through five stages:\n\n1. **Record** — open a browser session with `webcmd open`. Everything is captured to a raw **journal** (DOM snapshots, actions, and redacted network evidence) by default.\n2. **Inspect** — read the journal and review captured network calls to understand what the task actually did and which requests had side effects.\n3. **Distill** — collapse the journal into the app's **capability graph**: the durable, deduplicated model of what this app can do.\n4. **Materialize** — emit a **workflow** (a deterministic `.mjs` replay script) or a **CLI** (a standalone package grounded in graph capabilities, shipped with its own `SKILL.md`).\n5. **Run** — replay the workflow or invoke the generated CLI. Deterministic, no live exploration.\n\n### Vocabulary\n\n| Term | What it is |\n|------|-----------|\n| **Session** | A live browser run, identified by `--session \u003cname\u003e`. Records by default. |\n| **Journal** | The raw event log of a session — snapshots, actions, network evidence. |\n| **Snapshot** | A semantic capture of page state. Webcmd can diff two snapshots. |\n| **Capability graph** | The distilled, durable model of an app's capabilities, built from journals. |\n| **Workflow** | A deterministic `.mjs` script that replays a task. No `SKILL.md`. |\n| **CLI** | A standalone package generated from graph capabilities. Ships a `SKILL.md`. |\n| **Profile** | A workspace identity context under `.webcmd/profiles/\u003cname\u003e` — may hold auth for several apps. |\n| **Authoring packet** | A planning step that decides the safe next action when creating, updating, or healing an artifact. |\n\n---\n\n## Quick start (golden path)\n\nFrom an empty workspace to a runnable CLI:\n\n```bash\n# 1. Install skills and prepare runtime\nwebcmd setup\n\n# 2. Record a task in a headed browser (this shell stays alive until close)\nwebcmd open \"https://news.ycombinator.com\" --session hn --headed\n\n# 3. From another shell, drive and inspect the session\nwebcmd snapshot --session hn\nwebcmd click --session hn --role link --name \"Learn more\"\nwebcmd network summary --session hn\n\n# 4. Let the authoring packet pick the safe next step\nwebcmd author cli --operation create \\\n  --task \"Collect top Hacker News posts\" \\\n  --app-id hacker-news \\\n  --url https://news.ycombinator.com\n\n# 5. Materialize the CLI from a plan, then run it\nwebcmd cli hacker-news --plan \u003cplan.json\u003e\nwebcmd run top-posts\n\n# 6. Done — close the session\nwebcmd close --session hn\n```\n\nSessions record by default; pass `--no-record` only for ephemeral sessions.\n\n---\n\n## For AI agents\n\nWebcmd is built to be driven by a coding agent (Claude Code, Cursor, and similar), not typed by hand.\n\n**Install the skills.** `webcmd setup` installs the canonical Webcmd skills so your agent knows how to record, inspect, distill, and materialize.\n\n```bash\nwebcmd setup                          # global: ~/.agents/skills/\nwebcmd setup --scope local            # workspace: .agents/skills/\nwebcmd setup --skills-root /path/to/.agents/skills\n```\n\n**Generated CLIs teach the next agent.** Every CLI Webcmd materializes ships with a `SKILL.md` whose frontmatter records command metadata, graph-capability provenance, and safe smoke tests. Install it alongside the CLI or into a shared skills root:\n\n```bash\nwebcmd cli \u003capp-id\u003e --plan \u003cplan.json\u003e --install-skill\nwebcmd cli \u003capp-id\u003e --plan \u003cplan.json\u003e --install-skill /path/to/skills\n```\n\nWorkflows never get a `SKILL.md`; CLIs always do.\n\n**The primitives your agent drives.** Open a session, then control it from another shell:\n\n```bash\nwebcmd snapshot --session default\nwebcmd click --session default --role link --name \"Learn more\"\nwebcmd press Enter --session default\nwebcmd goto \"https://example.com\" --session default\nwebcmd wait url_contains \"example.com\" --session default --timeout-ms 5000\nwebcmd close --session default\n```\n\n---\n\n## Browser runtime\n\nWebcmd opens a **CloakBrowser**-backed session by default:\n\n```bash\nwebcmd open \"https://example.com\" --session default\n```\n\nRun headed when you need to watch or hand off — the command stays alive until the session closes:\n\n```bash\nwebcmd open \"https://example.com\" --session default --headed\n```\n\nUse stock Playwright Chromium explicitly when you'd rather not use CloakBrowser (install browsers first):\n\n```bash\nnpm run browsers:install\nwebcmd open \"https://example.com\" --browser chromium\n```\n\n### Profiles and identity\n\nNamed profiles are workspace identity contexts under `.webcmd/profiles/\u003cname\u003e`. A single profile can carry auth for more than one app. Use `default` for the normal workspace identity:\n\n```bash\nwebcmd open \"https://accounts.google.com\" --session login --headed \\\n  --profile default --browser chromium --channel chrome\n```\n\nOr point at a dedicated absolute profile directory:\n\n```bash\nwebcmd open \"https://accounts.google.com\" --session google --headed \\\n  --user-data-dir /absolute/dedicated/profile --browser chromium --channel chrome\n```\n\n\u003e **Do not** point `--user-data-dir` at your daily Chrome profile while Chrome is open. Use a dedicated Webcmd profile.\n\nGenerated workflows and CLIs that initialize with `auth: true` reuse `.webcmd/profiles/default` unless the caller passes another `profile` or `userDataDir`.\n\n### Auth-aware graphs\n\nValidate profile state and open a headed login flow:\n\n```bash\nwebcmd auth doctor linkedin --profile default\nwebcmd auth login linkedin --profile default --browser chromium --channel chrome\nwebcmd auth bind linkedin --session login\n```\n\n### Optional Camofox provider\n\nUse Camofox when a normal Playwright browser is blocked:\n\n```bash\nwebcmd open https://example.com --browser camofox --camofox-url http://localhost:3000\n```\n\n---\n\n## Network inspection\n\nCaptured sessions write redacted request evidence to `.webcmd/sessions/\u003csession\u003e/network.jsonl`; reviewer marks live separately in `network.marks.json`.\n\n```bash\nwebcmd network list --session default --method POST\nwebcmd network show n1 --session default\nwebcmd network summary --session default\nwebcmd network candidates --session default\nwebcmd network mark n1 --session default --mark side-effect\n```\n\nMarking side-effecting requests helps the distill step reason about which calls are safe to replay.\n\n---\n\n## Authoring, distilling \u0026 materializing\n\n### Authoring packets\n\nUse an authoring packet when the user asks to **create**, **update**, or **heal** a CLI or workflow and you need to decide whether existing graph evidence is enough.\n\n```bash\nwebcmd author cli --operation create --task \"Create a Hacker News CLI\" --app-id hacker-news --url https://news.ycombinator.com\nwebcmd author cli --operation update --task \"Add saved jobs\" --app-id linkedin\nwebcmd author cli --operation heal --task \"jobs search fails\" --app-id linkedin --target .webcmd/exports/clis/www.linkedin.com\n\nwebcmd author workflow --operation create --task \"Collect top Hacker News posts\" --app-id hacker-news --url https://news.ycombinator.com\nwebcmd author workflow --operation update --task \"Return JSON with title and URL\" --app-id hacker-news\nwebcmd author workflow --operation heal --task \"top posts workflow no longer finds titles\" --app-id hacker-news --target .webcmd/exports/workflows/news.ycombinator.com/top-posts.mjs\n```\n\nThe packet tells the agent which phase to run next:\n\n| Phase | What to do |\n|-------|-----------|\n| `discovery` | Record browser and network evidence within the discovery budget. |\n| `distill` | Distill existing recorded sessions into the graph. |\n| `build` | Prepare a CLI or workflow materialization packet. |\n| `repair` | Reproduce and classify the failure before patching. |\n\nThe packet only chooses the safe next step — the actual artifact always comes from `webcmd cli`, `webcmd workflow`, and `webcmd verify`.\n\n### Materialization exports\n\n```bash\nwebcmd workflow \u003capp-id\u003e --plan \u003cplan.json\u003e\nwebcmd workflow list\nwebcmd run \u003cworkflow_name\u003e\nwebcmd run \u003cdomain\u003e/\u003cworkflow_name\u003e\nwebcmd run \u003cworkflow_name\u003e --help\n\nwebcmd cli \u003capp-id\u003e --plan \u003cplan.json\u003e\nwebcmd cli \u003capp-id\u003e --plan \u003cplan.json\u003e --install-skill\n```\n\n- Workflows export to `~/.webcmd/exports/workflows/\u003cdomain\u003e/\u003cworkflow-name\u003e.mjs`.\n- CLIs export to `~/.webcmd/exports/clis/\u003cdomain\u003e/` as standalone packages grounded in graph capabilities.\n\n---\n\n## User handoff\n\nPause for a human to demonstrate a step, then resume from the user-authored journal events:\n\n```bash\nwebcmd handoff --session default\n# user demonstrates the workflow in the headed browser\nwebcmd resume --session default\n```\n\n---\n\n## Reading a session\n\n```bash\nwebcmd journal        # read an existing recorded session\nwebcmd run \u003cname\u003e     # execute an exported workflow .mjs\n```\n\n---\n\n## Configuration reference\n\n| Path | Purpose |\n|------|---------|\n| `~/.agents/skills/` | Global skills install target (`webcmd setup`). |\n| `.agents/skills/` | Local/workspace skills (`webcmd setup --scope local`). |\n| `.webcmd/` | Runtime state — created automatically when needed. |\n| `.webcmd/profiles/\u003cname\u003e` | Named identity profiles (auth, storage). |\n| `.webcmd/sessions/\u003csession\u003e/network.jsonl` | Redacted request evidence. |\n| `.webcmd/sessions/\u003csession\u003e/network.marks.json` | Reviewer marks. |\n| `~/.webcmd/exports/workflows/\u003cdomain\u003e/` | Exported workflow `.mjs` scripts. |\n| `~/.webcmd/exports/clis/\u003cdomain\u003e/` | Exported standalone CLI packages. |\n\nCommon flags: `--session \u003cname\u003e`, `--profile \u003cname\u003e`, `--browser \u003ccloak\\|chromium\\|camofox\u003e`, `--channel chrome`, `--headed`, `--no-record`, `--user-data-dir \u003cpath\u003e`, `--timeout-ms \u003cn\u003e`.\n\n---\n\n## Troubleshooting\n\n- **`--user-data-dir` conflict / profile locked** — Chrome is likely open on that profile. Close Chrome or use a dedicated Webcmd profile under `.webcmd/profiles/\u003cname\u003e`.\n- **Auth check fails** — run `webcmd auth doctor \u003capp\u003e --profile default`, then `webcmd auth login \u003capp\u003e ...` and re-bind with `webcmd auth bind \u003capp\u003e --session login`.\n- **Browser is blocked / bot-walled** — retry with the Camofox provider: `--browser camofox --camofox-url http://localhost:3000`.\n- **Stock Chromium missing** — run `npm run browsers:install` before using `--browser chromium`.\n- **Session not found** — confirm the `--session` name matches the one used with `webcmd open`; headed sessions must still be alive.\n- **Node errors on startup** — Webcmd requires Node \u003e= 20. Check `node --version` and upgrade.\n\n\u003c!-- TODO: document output formats and exit codes here once finalized —\n     both are high-value for agents/CI branching on results. --\u003e\n\n---\n\n## Installation\n\nWebcmd requires **Node \u003e= 20**.\n\n```bash\nnpm install -g @agentrhq/webcmd\nwebcmd --help\n```\n\nOne-off usage without a global install:\n\n```bash\nnpx @agentrhq/webcmd --help\n```\n\n---\n\n## Development\n\n```bash\nnpm install\nnpm test\nnpm run check\nnpm run build\n```\n\n---\n\n## Contributing \u0026 releases\n\nRelease engineering (Release Please, Conventional Commits, npm Trusted Publishing, and first-publish bootstrap) is documented separately in [`CONTRIBUTING.md`](./CONTRIBUTING.md) .\n\nIn short: `fix:` → patch, `feat:` → minor, `!` or `BREAKING CHANGE:` → major. CI runs `npm ci \u0026\u0026 npm run check \u0026\u0026 npm test \u0026\u0026 npm run build \u0026\u0026 npm pack --dry-run` on every push and PR; merging the Release Please PR cuts the GitHub release and publishes to npm.\n\n---\n\n## License\n\nReleased under the terms in [`LICENSE`](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentrhq%2Fwebcmd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentrhq%2Fwebcmd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentrhq%2Fwebcmd/lists"}