{"_id":"@opengsd/gsd-browser","_rev":"7-5f199295f78005f1fedd3e2425073d1d","name":"@opengsd/gsd-browser","dist-tags":{"dev":"0.2.0","latest":"0.2.2"},"versions":{"0.1.27":{"name":"@opengsd/gsd-browser","version":"0.1.27","keywords":["browser","automation","cdp","chrome","devtools","testing","accessibility","screenshot","cli"],"license":"MIT OR Apache-2.0","_id":"@opengsd/gsd-browser@0.1.27","maintainers":[{"name":"trek-e","email":"trekkie@nomorestars.com"},{"name":"solvely-colin","email":"colin@solvely.net"},{"name":"jeremymcs","email":"jeremy@fluxlabs.net"}],"homepage":"https://github.com/open-gsd/gsd-browser","bugs":{"url":"https://github.com/open-gsd/gsd-browser/issues"},"os":["darwin","linux","win32"],"bin":{"gsd-browser":"bin/gsd-browser"},"cpu":["arm64","x64"],"dist":{"shasum":"3a5ce99d9aa1c83dc2c9188b9b618c1f34601a0f","tarball":"https://registry.npmjs.org/@opengsd/gsd-browser/-/gsd-browser-0.1.27.tgz","fileCount":8,"integrity":"sha512-bUSdFD5VgX1gOk1l5PaZrMBPRc+eh6zQsMLS6nwX4PHDpQgLojIFqD+NTZzifEOynSlHPBy8LbD8T8Bj1iQnDg==","signatures":[{"sig":"MEUCIDs01AO01qPqpeib8FqOBfEJ46MiUsWPAuiaT2SR2F9ZAiEA7sEw+cl3j+BVoFALO00veWdm/RC4rnfj1kL2gnmZaRg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":70301},"engines":{"node":">=16"},"gitHead":"b168ec3853983860f6af3d1f73b121265bb19599","scripts":{"postinstall":"node scripts/postinstall.js"},"_npmUser":{"name":"jeremymcs","email":"jeremy@fluxlabs.net"},"repository":{"url":"git+https://github.com/open-gsd/gsd-browser.git","type":"git"},"_npmVersion":"11.12.1","description":"Browser automation CLI powered by Chrome DevTools Protocol — 92 commands for navigation, interaction, live viewing, annotations, recording bundles, screenshots, accessibility, network mocking, visual diffing, and more.","directories":{},"_nodeVersion":"26.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gsd-browser_0.1.27_1780160613681_0.5727082306553595","host":"s3://npm-registry-packages-npm-production"}},"0.1.29":{"name":"@opengsd/gsd-browser","version":"0.1.29","keywords":["browser","automation","cdp","chrome","devtools","testing","accessibility","screenshot","cli"],"license":"MIT OR Apache-2.0","_id":"@opengsd/gsd-browser@0.1.29","maintainers":[{"name":"trek-e","email":"trekkie@nomorestars.com"},{"name":"solvely-colin","email":"colin@solvely.net"},{"name":"jeremymcs","email":"jeremy@fluxlabs.net"}],"homepage":"https://github.com/open-gsd/gsd-browser","bugs":{"url":"https://github.com/open-gsd/gsd-browser/issues"},"os":["darwin","linux","win32"],"bin":{"gsd-browser":"bin/gsd-browser"},"cpu":["arm64","x64"],"dist":{"shasum":"2c50ec08ad614369c260c3bfc2b77e9f582dac37","tarball":"https://registry.npmjs.org/@opengsd/gsd-browser/-/gsd-browser-0.1.29.tgz","fileCount":11,"integrity":"sha512-RLL/KtGtyh8DswVE7K6om0eVfb29Kwv3Lc66s46Ct80sxsxhOILaryWPeLNKGqzVYxrcigkX8DS0R73NamxUDQ==","signatures":[{"sig":"MEQCIGPdFBc78BXRArSD26J+gJ4H+LynYcaTo0uFwsMg401DAiATYZQRMl+xEAloLAufT0nMvVhSZ5Z2IRCFLXdD/sqKvA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@opengsd%2fgsd-browser@0.1.29","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":77931},"engines":{"node":">=16"},"gitHead":"88576310ec4f80515aca751b2590ce6600564eeb","scripts":{"test":"node scripts/test-package.js","build":"node scripts/build-package.js","smoke":"node bin/gsd-browser --version","postinstall":"node scripts/postinstall.js","prepublishOnly":"npm test && npm run build","verify:release-tag":"node scripts/verify-release-tag.js"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:87e00ccb-4e4e-4a92-a7f5-b26e4ccc5d34"}},"repository":{"url":"git+https://github.com/open-gsd/gsd-browser.git","type":"git"},"_npmVersion":"11.17.0","description":"Browser automation CLI powered by Chrome DevTools Protocol — 92 commands for navigation, interaction, live viewing, annotations, recording bundles, screenshots, accessibility, network mocking, visual diffing, and more.","directories":{},"_nodeVersion":"22.22.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gsd-browser_0.1.29_1781212551306_0.23722733847956978","host":"s3://npm-registry-packages-npm-production"}},"0.1.31":{"name":"@opengsd/gsd-browser","version":"0.1.31","keywords":["browser","automation","cdp","chrome","devtools","testing","accessibility","screenshot","cli"],"license":"MIT OR Apache-2.0","_id":"@opengsd/gsd-browser@0.1.31","maintainers":[{"name":"trek-e","email":"trekkie@nomorestars.com"},{"name":"solvely-colin","email":"colin@solvely.net"},{"name":"jeremymcs","email":"jeremy@fluxlabs.net"}],"homepage":"https://github.com/open-gsd/gsd-browser","bugs":{"url":"https://github.com/open-gsd/gsd-browser/issues"},"os":["darwin","linux","win32"],"bin":{"gsd-browser":"bin/gsd-browser"},"cpu":["arm64","x64"],"dist":{"shasum":"d009d8235efe1688d84262ff10df6d9f6fe536f5","tarball":"https://registry.npmjs.org/@opengsd/gsd-browser/-/gsd-browser-0.1.31.tgz","fileCount":11,"integrity":"sha512-zZ93WRgiOH4Uez5KiNxHUKKIw/82JAh1qf8x95ZOUDmr7GHl/UHrOi+HVhYgKgemCR73N0F4al0ccpwlc6enaw==","signatures":[{"sig":"MEYCIQCr51fWoP/k+dUc64KR9I344gORWwrId6DTKEbRHkFjgQIhALHFxlNfWnl0Dp7XPyYjv4KiqDR9vbuBHncxKK7We+Z9","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@opengsd%2fgsd-browser@0.1.31","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":77955},"engines":{"node":">=16"},"gitHead":"6d4a56956a7da24037373f92043a5fed1a5768ca","scripts":{"test":"node scripts/test-package.js","build":"node scripts/build-package.js","smoke":"node bin/gsd-browser --version","postinstall":"node scripts/postinstall.js","prepublishOnly":"npm test && npm run build","verify:release-tag":"node scripts/verify-release-tag.js"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:2d87d41b-471a-4613-8a32-d9608820575c"}},"repository":{"url":"git+https://github.com/open-gsd/gsd-browser.git","type":"git"},"_npmVersion":"11.17.0","description":"Browser automation CLI powered by Chrome DevTools Protocol — 92 commands for navigation, interaction, live viewing, annotations, recording bundles, screenshots, accessibility, network mocking, visual diffing, and more.","directories":{},"_nodeVersion":"24.16.0","publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"readmeFilename":"README.md","_npmOperationalInternal":{"tmp":"tmp/gsd-browser_0.1.31_1781292139499_0.5164728079962688","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@opengsd/gsd-browser","version":"0.2.0","keywords":["browser","automation","cdp","chrome","devtools","testing","accessibility","screenshot","cli"],"license":"MIT OR Apache-2.0","_id":"@opengsd/gsd-browser@0.2.0","maintainers":[{"name":"trek-e","email":"trekkie@nomorestars.com"},{"name":"solvely-colin","email":"colin@solvely.net"},{"name":"jeremymcs","email":"jeremy@fluxlabs.net"}],"homepage":"https://github.com/open-gsd/gsd-browser","bugs":{"url":"https://github.com/open-gsd/gsd-browser/issues"},"os":["darwin","linux","win32"],"bin":{"gsd-browser":"bin/gsd-browser"},"cpu":["arm64","x64"],"dist":{"shasum":"0fef961f1d5cdca15c2483a4e6d8cba4fd56b000","tarball":"https://registry.npmjs.org/@opengsd/gsd-browser/-/gsd-browser-0.2.0.tgz","fileCount":11,"integrity":"sha512-ou+MKLoMaKctHSeqQS0+GfVpwV1VupZEXbJLfiW7gfPEFrcXsVSK7ytULYl/3FddWnBaL4AGxMN7sZWnP0IdyA==","signatures":[{"sig":"MEYCIQC9mWuHIdlxUvjLOecDuCQVY54aYYAd/4ti/7qXaZUuvAIhANTJ0O7xKxJtgIBW+AdxwjUzaR9VV9Wp7gboVvLVYASg","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@opengsd%2fgsd-browser@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":78316},"engines":{"node":">=16"},"gitHead":"80b1e0e276073322a3cb82bd11415422fd67acba","scripts":{"test":"node scripts/test-package.js","build":"node scripts/build-package.js","smoke":"node bin/gsd-browser --version","postinstall":"node scripts/postinstall.js","prepublishOnly":"npm test && npm run build","verify:release-tag":"node scripts/verify-release-tag.js"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:2d87d41b-471a-4613-8a32-d9608820575c"}},"repository":{"url":"git+https://github.com/open-gsd/gsd-browser.git","type":"git"},"_npmVersion":"11.17.0","description":"Browser automation CLI powered by Chrome DevTools Protocol — 92 commands for navigation, interaction, live viewing, annotations, recording bundles, screenshots, accessibility, network mocking, visual diffing, and more.","directories":{},"_nodeVersion":"24.16.0","publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"readmeFilename":"README.md","_npmOperationalInternal":{"tmp":"tmp/gsd-browser_0.2.0_1781462111604_0.824407196318578","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@opengsd/gsd-browser","version":"0.2.1","keywords":["browser","automation","cdp","chrome","devtools","testing","accessibility","screenshot","cli"],"license":"MIT OR Apache-2.0","_id":"@opengsd/gsd-browser@0.2.1","maintainers":[{"name":"trek-e","email":"trekkie@nomorestars.com"},{"name":"solvely-colin","email":"colin@solvely.net"},{"name":"jeremymcs","email":"jeremy@fluxlabs.net"}],"homepage":"https://github.com/open-gsd/gsd-browser","bugs":{"url":"https://github.com/open-gsd/gsd-browser/issues"},"os":["darwin","linux","win32"],"bin":{"gsd-browser":"bin/gsd-browser"},"cpu":["arm64","x64"],"dist":{"shasum":"c585e214691c05e5b9f10e8c3ac3ac9b5c0ddcbb","tarball":"https://registry.npmjs.org/@opengsd/gsd-browser/-/gsd-browser-0.2.1.tgz","fileCount":11,"integrity":"sha512-Okm1CH6609B6mDtkNVbZGMAaeIyembqDvksrHhSwbC3ANJwqxjPrJSbm9x1qPpC+0mmu3vNyV2rn+xyMY2CqVA==","signatures":[{"sig":"MEUCIQCWODT83mMf8pLtmSMFDe8lt4hOYoU9/kpkKQyLVr9pAgIgNvLI1Ciruf7qYTeTQCakSlEkXqLlWcKpyZAF6wek2Go=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@opengsd%2fgsd-browser@0.2.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":78316},"engines":{"node":">=16"},"gitHead":"2ce2b5960d39e7a7378f1f8a46c904cb196d1b62","scripts":{"test":"node scripts/test-package.js","build":"node scripts/build-package.js","smoke":"node bin/gsd-browser --version","postinstall":"node scripts/postinstall.js","prepublishOnly":"npm test && npm run build","verify:release-tag":"node scripts/verify-release-tag.js"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:2d87d41b-471a-4613-8a32-d9608820575c"}},"repository":{"url":"git+https://github.com/open-gsd/gsd-browser.git","type":"git"},"_npmVersion":"11.17.0","description":"Browser automation CLI powered by Chrome DevTools Protocol — 92 commands for navigation, interaction, live viewing, annotations, recording bundles, screenshots, accessibility, network mocking, visual diffing, and more.","directories":{},"_nodeVersion":"24.16.0","publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gsd-browser_0.2.1_1781478832573_0.8244638376180558","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@opengsd/gsd-browser","version":"0.2.2","description":"Browser automation CLI powered by Chrome DevTools Protocol — 92 commands for navigation, interaction, live viewing, annotations, recording bundles, screenshots, accessibility, network mocking, visual diffing, and more.","license":"MIT OR Apache-2.0","repository":{"type":"git","url":"git+https://github.com/open-gsd/gsd-browser.git"},"homepage":"https://github.com/open-gsd/gsd-browser","bugs":{"url":"https://github.com/open-gsd/gsd-browser/issues"},"keywords":["browser","automation","cdp","chrome","devtools","testing","accessibility","screenshot","cli"],"bin":{"gsd-browser":"bin/gsd-browser"},"scripts":{"build":"node scripts/build-package.js","postinstall":"node scripts/postinstall.js","prepublishOnly":"npm test && npm run build","smoke":"node bin/gsd-browser --version","test":"node scripts/test-package.js","verify:release-tag":"node scripts/verify-release-tag.js"},"publishConfig":{"access":"public","provenance":true},"os":["darwin","linux","win32"],"cpu":["arm64","x64"],"engines":{"node":">=16"},"gitHead":"4e77bc47e6b6c9263bb422d00a0d0a79b2b195bf","_id":"@opengsd/gsd-browser@0.2.2","_nodeVersion":"24.16.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-ld4TOZKcXJF3v0KVlUqrOfHC+rYG8l00Dw0GkEuHtQTIYq7+blYO2acnGHN+P2Owod0xlq/2k1UQDaYgrRSKgw==","shasum":"cbc2ffb2e7b564dc10f4eecbabcecd903605ed46","tarball":"https://registry.npmjs.org/@opengsd/gsd-browser/-/gsd-browser-0.2.2.tgz","fileCount":11,"unpackedSize":79617,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@opengsd%2fgsd-browser@0.2.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC/R/b2x9LICdZHA4BAfL0Vt0BI16ynvhZCJbMmID0AlwIhAODKio/Za0WZ1/UWAa+sUDDaD59rRCaQtarBHVfYmFFS"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:2d87d41b-471a-4613-8a32-d9608820575c"}},"directories":{},"maintainers":[{"name":"trek-e","email":"trekkie@nomorestars.com"},{"name":"solvely-colin","email":"colin@solvely.net"},{"name":"jeremymcs","email":"jeremy@fluxlabs.net"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/gsd-browser_0.2.2_1781495228603_0.4134639560077269"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-30T17:03:33.573Z","modified":"2026-06-15T03:47:09.123Z","0.1.27":"2026-05-30T17:03:33.814Z","0.1.29":"2026-06-11T21:15:51.457Z","0.1.31":"2026-06-12T19:22:19.640Z","0.2.0":"2026-06-14T18:35:11.736Z","0.2.1":"2026-06-14T23:13:52.707Z","0.2.2":"2026-06-15T03:47:08.746Z"},"bugs":{"url":"https://github.com/open-gsd/gsd-browser/issues"},"license":"MIT OR Apache-2.0","homepage":"https://github.com/open-gsd/gsd-browser","keywords":["browser","automation","cdp","chrome","devtools","testing","accessibility","screenshot","cli"],"repository":{"type":"git","url":"git+https://github.com/open-gsd/gsd-browser.git"},"description":"Browser automation CLI powered by Chrome DevTools Protocol — 92 commands for navigation, interaction, live viewing, annotations, recording bundles, screenshots, accessibility, network mocking, visual diffing, and more.","maintainers":[{"name":"trek-e","email":"trekkie@nomorestars.com"},{"name":"solvely-colin","email":"colin@solvely.net"},{"name":"jeremymcs","email":"jeremy@fluxlabs.net"}],"readme":"# gsd-browser\n\nNative Rust browser automation CLI for Chrome/Chromium via CDP. `gsd-browser` keeps a persistent background daemon, auto-starts on first use, and exposes 90+ top-level commands for navigation, interaction, authenticated live viewing, annotations, recording bundles, snapshots with versioned refs, assertions, structured extraction, network control, visual diffing, tracing, and stateful auth flows.\n\nBuilt for AI agents, CI pipelines, and developers who want deterministic browser control without adopting a full browser test framework.\n\n### MCP Server — Massively Expanded (The Primary Path for AI Agents)\n\n`gsd-browser mcp` is now a first-class, extremely powerful browser automation platform for agents. It exposes **50+ tools**, live resources (real snapshot/refs/state/timeline data), and executable prompts over stdio (Model Context Protocol).\n\n**Completed advancements include:**\n- Full coverage of the rich surface: versioned refs + multiple snapshot modes, semantic `act` + `find_best`, advanced forms, robust assertions + waits, `browser_batch` for atomic flows, live viewer + full human collaboration (takeover, annotations, goal banners, step/abort/pause/resume, sensitive mode), first-class recording & evidence bundles, visual regression, HAR/trace/PDF export, network mocking & blocking, device emulation, encrypted auth vault + state save/restore, structured extraction, prompt injection scanning, action cache for long-term self-healing, multi-tab/frame management, rich diagnostics (`debug_bundle` etc.), and more.\n- **Resources** that actually query the daemon for live context (`gsd-browser://latest-snapshot`, `current-state`, `active-recordings`, `timeline`, etc.).\n- **Executable prompts** encoding best-practice multi-step workflows (`robust_login_flow`, `full_page_audit`, `autonomous_research_task`, `evidence_creation_workflow`, `debug_stuck_agent_flow`, etc.).\n- Standardized high-value response envelopes on every tool call: `summary`, `structured_data`, `suggested_next_actions`, `evidence_refs`.\n- Seamless reuse of the proven daemon client (auto-start, named sessions for isolation + persistent cache/state, robust error handling).\n\n**This is designed to be the high-end browser backend for serious agent platforms.**\n\n**Get started in seconds:**\n```bash\ngsd-browser mcp\n```\nPoint Cursor, Claude Desktop, VS Code + Copilot, or any MCP client at it.\n\n**Tailored setup + config snippets:**\n```bash\n./scripts/mcp-quickstart.sh cursor     # claude | vscode | generic\n```\n\n**Key documentation:**\n- [docs/mcp.md](docs/mcp.md) — Full capabilities, architecture, client configs, quickstart script.\n- [docs/AGENT-BEST-PRACTICES.md](docs/AGENT-BEST-PRACTICES.md) — Golden rules, workflow patterns, \"When to Use What\" table, self-healing, response envelopes, prompt/resource usage (essential reading for agents).\n- [docs/examples/mcp-client-config.json](docs/examples/mcp-client-config.json) — Ready-to-paste example.\n- Root [SKILL.md](SKILL.md) and the `gsd-browser-skill/` pack — Complete underlying command semantics and curated workflows (the MCP tools are a direct mapping).\n\nRun `gsd-browser mcp` and unleash one of the most powerful browser surfaces available for agentic work.\n\n## Install\n\n### npm\n\n```bash\nnpm install -g @opengsd/gsd-browser\n```\n\nCurrent release status:\n\n- GitHub latest release: [`v0.1.31`](https://github.com/open-gsd/gsd-browser/releases/tag/v0.1.31)\n- npm `dev` dist-tag: `@opengsd/gsd-browser@0.1.31`\n- npm `latest` dist-tag: `@opengsd/gsd-browser@0.1.29`\n\nTo install the current GitHub release from npm before `latest` is promoted:\n\n```bash\nnpm install -g @opengsd/gsd-browser@dev\n```\n\n### Pre-built binaries\n\nDownload from [GitHub Releases](https://github.com/open-gsd/gsd-browser/releases):\n\n| Platform | Asset |\n|----------|-------|\n| macOS (Apple Silicon) | `gsd-browser-darwin-arm64` |\n| macOS (Intel) | `gsd-browser-darwin-x64` |\n| Linux (ARM64) | `gsd-browser-linux-arm64` |\n| Linux (x64) | `gsd-browser-linux-x64` |\n| Windows (x64) | `gsd-browser-windows-x64.exe` |\n\n### Build from source\n\n```bash\ngit clone https://github.com/open-gsd/gsd-browser.git\ncd gsd-browser\ncargo install --path cli\n```\n\n### Codex Plugin\n\nInstall the CLI and register the Codex Plugin in one pass:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/open-gsd/gsd-browser/main/install.sh | bash -s -- --codex-plugin\n```\n\nThe installer writes the plugin to `~/plugins/gsd-browser`, updates the personal Codex marketplace at `~/.agents/plugins/marketplace.json`, and runs `codex plugin add gsd-browser@<marketplace>` when the Codex CLI is available. Without `--codex-plugin`, the interactive installer offers `OpenAI Codex Plugin` alongside the agent skill options.\n\n### crates.io\n\nThe crates.io package (`gsd-browser`) is not published yet. Use GitHub release assets or a source build.\n\nThe one-line installer (`curl -fsSL https://raw.githubusercontent.com/open-gsd/gsd-browser/main/install.sh | bash`) also sets up the `gsd-browser-skill/` pack for coding agents and documents the MCP path in its header.\n\n## Quick Start\n\nThe daemon starts automatically on first use.\n\n```bash\n# Navigate to a page\ngsd-browser navigate https://example.com\n\n# Snapshot interactive elements and assign refs like @v1:e1\ngsd-browser snapshot\n\n# On example.com the only interactive element is the \"More information...\" link\ngsd-browser click-ref @v1:e1\n\n# Wait for navigation and assert the result\ngsd-browser wait-for --condition network_idle\ngsd-browser assert --checks '[{\"kind\":\"url_contains\",\"text\":\"iana.org\"}]'\n\n# Capture a PNG\ngsd-browser screenshot --output page.png --format png\n```\n\nFor the modern agent experience, prefer the MCP server (see top of this README).\n\n## Interactive Workbench\n\n`gsd-browser view` starts an authenticated localhost workbench for the active session. The URL is bound to the session, viewer id, loopback origin, expiry, and viewer capabilities. Use `view --print-only` when another tool needs the URL.\n\n```bash\ngsd-browser view\ngsd-browser view --print-only\ngsd-browser control-state\ngsd-browser takeover\ngsd-browser release-control\ngsd-browser sensitive-on\ngsd-browser sensitive-off\n```\n\nThe viewer streams the real Chrome page, forwards pointer, wheel, keyboard, text, and paste input while in Control mode, creates annotations in Annotate mode, and starts/stops local recording bundles in Record mode. Sensitive mode keeps local human control available while cloud frame capture and evidence surfaces use redaction policy.\n\nAnnotations and recordings stay local to the daemon state directory:\n\n```bash\ngsd-browser annotations\ngsd-browser annotation-get <id>\ngsd-browser annotation-clear <id>\ngsd-browser annotation-resolve <id>\ngsd-browser annotation-export --output annotations.json\n\ngsd-browser record-start --name checkout-bug\ngsd-browser record-stop\ngsd-browser recordings\ngsd-browser recording-get <id>\ngsd-browser recording-export <id> --output <path>\ngsd-browser recording-discard <id>\ngsd-browser recording-validate <id-or-path> --json\n```\n\n(MCP equivalents: `browser_view`, `browser_annotation_request`, `browser_record_start`, etc. — among the highest-leverage features for collaborative agent work.)\n\n## Command Surface\n\n`gsd-browser` currently exposes 90+ top-level commands (the MCP server exposes the most valuable subset as 50+ discoverable tools with agent-optimized descriptions and envelopes):\n\n| Area | Commands |\n|------|----------|\n| Navigation | `navigate`, `back`, `forward`, `reload` |\n| Logs & JavaScript | `console`, `network`, `dialog`, `eval` |\n| Interaction | `click`, `type`, `press`, `hover`, `scroll`, `select-option`, `set-checked`, `drag`, `set-viewport`, `upload-file` |\n| Inspection | `accessibility-tree`, `find`, `page-source` |\n| Waits | `wait-for` |\n| Snapshots & refs | `snapshot`, `get-ref`, `click-ref`, `hover-ref`, `fill-ref` |\n| Assertions & batching | `assert`, `diff`, `batch` |\n| Pages & frames | `list-pages`, `switch-page`, `close-page`, `list-frames`, `select-frame` |\n| Forms & semantic actions | `analyze-form`, `fill-form`, `find-best`, `act` |\n| Live workbench | `goal`, `view`, `control-state`, `takeover`, `release-control`, `pause`, `resume`, `step`, `abort`, `sensitive-on`, `sensitive-off` |\n| Annotations | `annotations`, `annotation-get`, `annotation-clear`, `annotation-resolve`, `annotation-export`, `annotation-request` |\n| Recording bundles | `record-start`, `record-stop`, `record-pause`, `record-resume`, `recordings`, `recording-get`, `recording-export`, `recording-discard`, `recording-validate` |\n| Diagnostics | `timeline`, `session-summary`, `debug-bundle` |\n| Screenshots & document output | `screenshot`, `zoom-region`, `save-pdf` |\n| Visual regression | `visual-diff` |\n| Structured extraction | `extract` |\n| Network control | `mock-route`, `block-urls`, `clear-routes` |\n| Device & browser state | `emulate-device`, `save-state`, `restore-state` |\n| Auth vault | `vault-save`, `vault-login`, `vault-list` |\n| Recording & traces | `generate-test`, `har-export`, `trace-start`, `trace-stop` |\n| Safety, caching & daemon management | `action-cache`, `check-injection`, `daemon` |\n| MCP, cloud & updates | `mcp`, `cloud-methods`, `update` |\n\n## Highlights\n\n- Persistent daemon with automatic startup for fast repeated commands\n- Durable named sessions with explicit health reporting and no silent session replacement\n- Versioned refs from `snapshot` for deterministic interaction (`@v1:e1`, `@v2:e3`)\n- Explicit assertions with `assert` and multi-step automation with `batch`\n- Shared inspection semantics across `snapshot`, `find`, `wait-for`, `assert`, and ref-driven actions\n- Semantic `find-best` and `act` flows covering 15 built-in intents\n- Named sessions via `--session` for isolated parallel browser workers\n- Authenticated local viewer with human takeover, pause/step/abort, annotations, sensitive mode, and bounded recording bundles\n- Structured JSON output on every command via `--json`\n- Visual diffing, HAR export, PDF generation, and CDP tracing in the same tool\n- Saved browser state plus encrypted credential replay through the auth vault\n- Prompt injection scanning for agent-facing browsing workflows\n- Action cache for self-healing intent mappings across sessions (especially powerful with named MCP sessions)\n- Full MCP server with resources, prompts, and agent-optimized envelopes\n\n## Configuration\n\n`gsd-browser` merges configuration in this order:\n\n1. Built-in defaults\n2. User config: `~/.gsd-browser/config.toml`\n3. Project config: `./gsd-browser.toml`\n4. Environment variables: `GSD_BROWSER_*`\n5. CLI flags\n\nExample `gsd-browser.toml`:\n\n```toml\n[browser]\npath = \"/usr/bin/chromium\"\ncdp_url = \"http://localhost:9222\"   # attach to existing Chrome instead of launching\nheadless = true\n\n[daemon]\nport = 9222\nhost = \"127.0.0.1\"\n\n[screenshot]\nquality = 90\nformat = \"png\"\nfull_page = false\n\n[settle]\ntimeout_ms = 500\npoll_ms = 40\nquiet_window_ms = 100\n\n[logs]\nmax_buffer_size = 1000\n\n[artifacts]\ndir = \"./browser-artifacts\"\n\n[timeline]\nenabled = true\nmax_entries = 500\n```\n\nSupported environment variable overrides use `GSD_BROWSER_<SECTION>_<FIELD>` naming:\n\n```bash\nexport GSD_BROWSER_BROWSER_PATH=/usr/bin/chromium\nexport GSD_BROWSER_BROWSER_CDP_URL=http://localhost:9222\nexport GSD_BROWSER_BROWSER_HEADLESS=true\nexport GSD_BROWSER_DAEMON_PORT=9333\nexport GSD_BROWSER_SCREENSHOT_QUALITY=90\nexport GSD_BROWSER_SETTLE_TIMEOUT_MS=1000\nexport GSD_BROWSER_ARTIFACTS_DIR=./browser-artifacts\nexport GSD_BROWSER_VAULT_KEY=your-encryption-key\n```\n\nFor MCP usage, place the relevant `GSD_BROWSER_*` variables in your MCP client's server `env` configuration.\n\n\n## Stealth Mode & Alternative Backends (Experimental)\n\ngsd-browser defaults to the stable `chromiumoxide` CDP client for maximum compatibility.\n\n### `--stealth` / `backend = \"stealth\"`\n```bash\ngsd-browser --stealth navigate https://bot.sannysoft.com\n# or\ngsd-browser --backend stealth navigate ...\n# config.toml\n[browser]\nstealth = true\nbackend = \"chaser-oxide\"   # or \"stealth\", \"chromey\"\n```\n\nEffects when enabled:\n- Anti-detection Chrome flags (`--disable-blink-features=AutomationControlled`, IsolateOrigins, etc.)\n- Realistic UA + hardware (cores, memory, platform) spoofing\n- CDP signal patches (webdriver, cdc_ markers, chrome object, permissions, WebGL)\n- Client Hints and locale/language consistency\n- (Future) human-like mouse curves via input_dispatch when chaser-oxide backend active\n\n### Feature-Gated Backends\nThe following require explicit cargo features (the published binary always ships the stable default):\n\n- `chromiumoxide-backend` (default) — current stable\n- `chromey-backend` — fresher CDP definitions, adblock, fingerprint crate (drop-in, same `use chromiumoxide`)\n- `chaser-backend` / `stealth` feature — protocol-level stealth, `ChaserPage` human input (compile with `--features stealth`)\n- `ferrous-backend` — ergonomic locator/wait API (launch path experimental)\n\nTo build with an alternative:\n```bash\ncargo install --path cli --no-default-features --features chromey-backend\n# or for full stealth\ncargo install --path cli --no-default-features --features stealth\n```\n\nSee also the audit and superpowers plans for the \"dependency/stealth refresh\" item.\n\nTrade-off: stealth backends may lag the main chromiumoxide feature surface or have different perf characteristics. The daemon handlers/refs/viewer remain unchanged regardless of backend.\n\n## How It Works\n\n- The CLI parses commands and sends them to a local daemon over a loopback HTTP channel.\n- The daemon maintains the browser lifecycle, page/frame routing, network hooks, action timeline, and session manifest state.\n- `--session <name>` creates isolated daemon and browser instances for parallel workflows.\n- The MCP stdio server (`gsd-browser mcp`) is a thin, high-fidelity adapter over the exact same daemon client used by the CLI.\n\n## For AI Agents\n\n**Recommended 2026+ path:** Connect via the MCP server (`gsd-browser mcp`). It gives you automatic discovery of 50+ tools, resources, and prompts with rich envelopes and best-practice guidance. See the dedicated sections at the top of this README, plus `docs/mcp.md` and especially `docs/AGENT-BEST-PRACTICES.md`.\n\nWhen using the CLI directly (or for reference):\n- The daemon auto-starts. You almost never need `gsd-browser daemon start`.\n- `gsd-browser daemon health` reports the current session state and does not auto-start the daemon.\n- Use `--json` when you need structured output.\n- Prefer `snapshot` then `click-ref` or `fill-ref` for stable interaction, and re-snapshot after page changes. (MCP: read the `latest-snapshot` resource.)\n- Use `assert` and `batch` when you need deterministic pass/fail automation.\n- `find-best` and `act` cover 15 built-in semantic intents for common navigation, form, dialog, auth, and pagination actions.\n- The live viewer + annotations + recordings + human takeover are first-class superpowers for collaborative or auditable work.\n- Read [SKILL.md](./SKILL.md) for the full command reference and workflow patterns (this is the source of truth for MCP tool semantics).\n- Install the curated `gsd-browser-skill/` pack (via the main installer) for coding agents.\n\n## License\n\nLicensed under either of:\n\n- [MIT License](LICENSE-MIT)\n- [Apache License, Version 2.0](LICENSE-APACHE)\n\nat your option.\n","readmeFilename":"README.md"}