{"id":49091116,"url":"https://github.com/patrick204nqh/browserctl","last_synced_at":"2026-05-01T06:05:46.369Z","repository":{"id":352419992,"uuid":"1214899956","full_name":"patrick204nqh/browserctl","owner":"patrick204nqh","description":"Persistent browser automation daemon and CLI for AI agents and developer workflows. Named sessions, Ruby DSL, and a token-efficient snapshot format.","archived":false,"fork":false,"pushed_at":"2026-04-24T08:59:10.000Z","size":1028,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-24T23:14:58.073Z","etag":null,"topics":["ai-agents","browser-automation","chrome-devtools-protocol","cli","developer-tools","dsl","ferrum","headless-browser","ruby","smoke-testing","unix-socket","workflow-automation"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/patrick204nqh.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":".github/CODEOWNERS","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-04-19T07:44:15.000Z","updated_at":"2026-04-24T08:58:53.000Z","dependencies_parsed_at":"2026-04-22T21:00:39.563Z","dependency_job_id":"824dfa53-8461-4caa-8a8e-dd00076e7930","html_url":"https://github.com/patrick204nqh/browserctl","commit_stats":null,"previous_names":["patrick204nqh/browserctl"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/patrick204nqh/browserctl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick204nqh%2Fbrowserctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick204nqh%2Fbrowserctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick204nqh%2Fbrowserctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick204nqh%2Fbrowserctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patrick204nqh","download_url":"https://codeload.github.com/patrick204nqh/browserctl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick204nqh%2Fbrowserctl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32280981,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai-agents","browser-automation","chrome-devtools-protocol","cli","developer-tools","dsl","ferrum","headless-browser","ruby","smoke-testing","unix-socket","workflow-automation"],"created_at":"2026-04-20T19:00:18.785Z","updated_at":"2026-05-01T06:05:46.363Z","avatar_url":"https://github.com/patrick204nqh.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/logo.svg\" width=\"96\" height=\"96\" alt=\"browserctl logo\"/\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ebrowserctl\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  The browser you delegate to your agents — with a pause button for the parts that still need you.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/patrick204nqh/browserctl/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/patrick204nqh/browserctl/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://badge.fury.io/rb/browserctl\"\u003e\u003cimg src=\"https://badge.fury.io/rb/browserctl.svg\" alt=\"Gem Version\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://rubygems.org/gems/browserctl\"\u003e\u003cimg src=\"https://img.shields.io/gem/dt/browserctl\" alt=\"Downloads\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nEvery browser automation tool restarts the browser when your script ends. That means re-authenticating, re-navigating, re-loading state — on every run. browserctl doesn't restart. The session stays alive between commands, so you pick up exactly where you left off.\n\n```bash\nbrowserd \u0026                                               # start the daemon (headless)\nbrowserctl page open main --url https://example.com/login\nbrowserctl snapshot main                                 # AI-friendly JSON snapshot with ref IDs\nbrowserctl fill main --ref e1 --value me@example.com    # interact by ref, no selectors needed\nbrowserctl click main --ref e2\nbrowserctl daemon stop\n```\n\n---\n\n## Quick Start\n\n```bash\n# 1. Install\ngem install browserctl\n\n# 2. Start the daemon\nbrowserd \u0026\n\n# 3. Open a named page\nbrowserctl page open main --url https://moatazeldebsy.github.io/test-automation-practices/#/auth\n\n# 4. Snapshot — returns JSON with a ref ID per interactable element\nbrowserctl snapshot main\n# → [{\"ref\":\"e1\",\"tag\":\"input\",\"attrs\":{\"data-test\":\"username-input\"}}, {\"ref\":\"e2\",...}, {\"ref\":\"e3\",\"tag\":\"button\",\"text\":\"Login\",...}]\n\n# 5. Interact using the ref IDs from the snapshot\nbrowserctl fill main --ref e1 --value admin\nbrowserctl fill main --ref e2 --value admin\nbrowserctl click main --ref e3\n\n# 6. Observe\nbrowserctl url main\nbrowserctl snapshot main --diff   # only what changed\n\n# Session persistence: save now, pick up later\nbrowserctl session save my-session\n# On a fresh daemon tomorrow: `browserctl session load my-session`\n# → tabs restored, cookies intact, no re-login needed\n\n# 7. Done\nbrowserctl daemon stop\n```\n\n→ [Full Getting Started guide](docs/getting-started.md)\n\n---\n\n## See it in action\n\n\u003ctable align=\"center\"\u003e\u003ctr\u003e\n\u003ctd align=\"center\" width=\"50%\"\u003e\n\n**Terminal**\u003cbr/\u003e\n\u003csub\u003eCLI commands, live output, session persistence proof\u003c/sub\u003e\n\n\u003cimg src=\"docs/assets/terminal.gif\" alt=\"browserctl terminal demo\"/\u003e\n\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"50%\"\u003e\n\n**Browser**\u003cbr/\u003e\n\u003csub\u003eWhat the browser sees as those commands run\u003c/sub\u003e\n\n\u003cimg src=\"docs/assets/browser_demo.gif\" alt=\"browserctl browser demo\"/\u003e\n\n\u003c/td\u003e\n\u003c/tr\u003e\u003c/table\u003e\n\n---\n\n## Use cases\n\n**AI coding agent authenticating into a staging environment** — the agent logs in once, the session persists, subsequent commands run inside the authenticated context without re-authenticating between steps.\n\n**Developer reproducing a multi-step bug report** — navigate to the failure point once, then iterate on the fix with the browser already in the right state; no restarting from the home page each run.\n\n**Automated smoke test that needs human sign-off** — the test runs until it hits something ambiguous, calls `browserctl pause`, lets a human inspect and act, then `browserctl resume` hands control back to the script with all state intact.\n\n---\n\n## Why browserctl?\n\nMost automation tools are stateless — every script spins up a fresh browser and tears it down. browserctl doesn't.\n\n| Capability | browserctl | Playwright / Selenium |\n|---|---|---|\n| Session persists across commands | ✓ | ✗ (per-script lifecycle) |\n| Named page handles | ✓ | ✗ |\n| AI-friendly DOM snapshot | ✓ | ✗ |\n| Human-in-the-loop pause/resume | ✓ | ✗ |\n| Lightweight CLI interface | ✓ | ✗ |\n| Full browser automation API | — | ✓ |\n| Parallel multi-browser testing | — | ✓ |\n\n**Use browserctl when** you need a browser that stays alive and remembers state — for AI agents, iterative dev workflows, or tasks that mix automation with human judgment.\n\n**Use Playwright/Selenium when** you need parallel test suites, multi-browser support, or a full programmatic API.\n\n---\n\n## Installation\n\n**Requirements:** Ruby \u003e= 3.3 · Chrome or Chromium installed\n\n**macOS (Homebrew — recommended)**\n\n```bash\nbrew install patrick204nqh/tap/browserctl\n```\n\n**RubyGems**\n\n```bash\ngem install browserctl\n```\n\nOr in your `Gemfile` (for projects using the client API directly):\n\n```ruby\ngem \"browserctl\"\n```\n\n---\n\n## Claude Code Plugin\n\nbrowserctl ships as a Claude Code plugin. Install it once and Claude automatically knows how to use the daemon, ref-based interaction, HITL patterns, and workflow authoring.\n\n**Interactive install**\n\n```\n/plugin marketplace add patrick204nqh/browserctl\n/plugin install browserctl@browserctl\n```\n\n**Project settings** — commit `.claude/settings.json` to share with your team:\n\n```json\n{\n  \"extraKnownMarketplaces\": {\n    \"browserctl\": {\n      \"source\": { \"source\": \"github\", \"repo\": \"patrick204nqh/browserctl\" }\n    }\n  },\n  \"enabledPlugins\": {\n    \"browserctl@browserctl\": true\n  }\n}\n```\n\nOnce installed, the `browserctl` skill loads automatically.\n\n---\n\n## How it works\n\n`browserd` runs as a background process, listening on a Unix socket at `~/.browserctl/browserd.sock`. It manages a Ferrum (Chrome DevTools Protocol) browser instance with named page handles. `browserctl` sends JSON-RPC commands over the socket and prints the result.\n\nStart multiple named instances for agent isolation:\n\n```bash\nbrowserd --name agent-a \u0026\nbrowserd --name agent-b \u0026\nbrowserctl --daemon agent-a page open main --url https://app.example.com\n```\n\nThe daemon shuts itself down after 30 minutes of inactivity.\n\n---\n\n## Documentation\n\n| | |\n|---|---|\n| [Getting Started](docs/getting-started.md) | Install, first session, first snapshot |\n| [Agent Integration](docs/guides/agent-integration.md) | Call browserctl from Python, shell, or Anthropic tool-use agents |\n| [Concepts](docs/concepts/) | Sessions, snapshots, human-in-the-loop |\n| [Guides](docs/guides/) | Writing workflows, handling challenges, smoke testing |\n| [Examples](examples/) | Runnable scripts: session reuse, Cloudflare HITL, and more |\n| [Command Reference](docs/reference/commands.md) | Every command and flag |\n| [API Stability](docs/reference/api-stability.md) | Wire protocol contract and stability zones |\n| [CHANGELOG](CHANGELOG.md) | Release history |\n| [Product](docs/product.md) | What browserctl is and who it's for |\n| [Vision \u0026 Roadmap](docs/vision.md) | Philosophy and release roadmap |\n| [vs. agent-browser](docs/vs-agent-browser.md) | How browserctl differs from Vercel's agent-browser |\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/patrick204nqh/browserctl\ncd browserctl\nbin/setup              # brew bundle (macOS) + bundle install + Chrome check\n\nbundle exec rspec      # run tests\nbundle exec rubocop    # lint\n\nrake demo               # full pipeline: screenshots + browser GIF + terminal GIF\nrake demo:screenshots   # smoke test screenshots only\nrake demo:browser_gif   # browser animation only  (requires: ffmpeg)\nrake demo:terminal      # terminal GIF only        (requires: vhs)\n```\n\n\u003e Demo assets are regenerated automatically on every push to `main` that touches `demo/` or the login example.\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md)\n\n## License\n\n[MIT](LICENSE)\n\n---\n\nBuilt by [Patrick](https://github.com/patrick204nqh) — I built this because I was building AI agents that needed authenticated web sessions, and every automation tool I tried restarted the browser between runs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrick204nqh%2Fbrowserctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatrick204nqh%2Fbrowserctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrick204nqh%2Fbrowserctl/lists"}