{"id":13602420,"url":"https://github.com/sebastiancarlos/beachpatrol","last_synced_at":"2025-04-09T18:34:40.604Z","repository":{"id":214392960,"uuid":"736406184","full_name":"sebastiancarlos/beachpatrol","owner":"sebastiancarlos","description":"A CLI tool to replace and automate your everyday web browser.","archived":false,"fork":false,"pushed_at":"2023-12-29T15:38:58.000Z","size":205,"stargazers_count":38,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-02-13T02:50:15.742Z","etag":null,"topics":["automation","browser","browser-automation","browser-extension","chrome","chromium","cli","extension","javascript","linux","nodejs","playwright","pupeteer","selenium","selenium-webdriver","terminal"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/sebastiancarlos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-12-27T20:20:21.000Z","updated_at":"2024-01-29T01:24:46.000Z","dependencies_parsed_at":"2023-12-27T22:25:34.917Z","dependency_job_id":"37b4be2f-6350-4d64-8c45-1a86247f3ec8","html_url":"https://github.com/sebastiancarlos/beachpatrol","commit_stats":null,"previous_names":["sebastiancarlos/beachpatrol"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebastiancarlos%2Fbeachpatrol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebastiancarlos%2Fbeachpatrol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebastiancarlos%2Fbeachpatrol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebastiancarlos%2Fbeachpatrol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sebastiancarlos","download_url":"https://codeload.github.com/sebastiancarlos/beachpatrol/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248088283,"owners_count":21045677,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["automation","browser","browser-automation","browser-extension","chrome","chromium","cli","extension","javascript","linux","nodejs","playwright","pupeteer","selenium","selenium-webdriver","terminal"],"created_at":"2024-08-01T18:01:22.730Z","updated_at":"2025-04-09T18:34:40.586Z","avatar_url":"https://github.com/sebastiancarlos.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","cli","\u003ca name=\"webdev\"\u003e\u003c/a\u003eWeb development"],"sub_categories":[],"readme":"# Beachpatrol: Browser's End-user Automation CLI Hub. Potentialize All Tasks Regarding Online Life.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/sebastiancarlos/beachpatrol/assets/88276600/49fbdf4f-eeec-42f8-a0aa-dd1c1c6c1617\"\u003e\n\u003c/p\u003e\n\n_Essential software should be fully automatable. Web browsers aren't. Let's change that._\n\n## Introduction\n\nBeachpatrol is a CLI tool to replace and automate your everyday web browser.\n\nhttps://github.com/sebastiancarlos/beachpatrol/assets/88276600/bc3bf9e8-28e2-48ef-a1f4-8754b4918916\n\nRun `beachpatrol` to launch a Chromium or Firefox browser which can be controlled\nexternally through [Playwright](https://playwright.dev/) scripts. You can use it as your daily driver; it works\nlike a regular browser. \n\nUse also `beachpatrol --profile \u003cprofile-name\u003e` to launch a specific profile,\nor `beachpatrol --incognito`.\n\nTo automate it, create a custom Playwright script in the `beachpatrol/commands`\nfolder. Then, run `beachmsg \u003cscript-name\u003e [\u003cargument\u003e...]`. It will run your\nscript by default on the currently focused tab, but you can use the Playwright\nAPI to move to an existing tab, open a new one, or use a headless tab instead.\n\nIf you don't want to go back and forth to the CLI to automate your browser, you can\ninstall the `beachpatrol-browser-extension`. Its UI allows you to select a\ncommand and call it with arguments. It will call `beachmsg` itself through the\nbrowser extension's Native Messaging feature. Also, the UI will highlight commands\nwhich are meant to run on the current URL, will provide GUI elements for common\nsituations (such as pagination and dropdowns), and will support hotkeys:\n\n![image](https://github.com/sebastiancarlos/beachpatrol/assets/88276600/751aec3f-284d-4563-ac0f-09bfa52034e2)\n\n### What can you automate with Beachpatrol? The sky is the limit:\n- Check your email.\n- Check your bank transactions.\n- Download a file from a website.\n- Dump the text from the current tab into a file.\n- Fill an online form.\n- Check for messages in your social media or work communication platform.\n- Integrate with your OS: Add browser task to your Bash/Python scripts.\n- **All of this right there on your everyday browser!**\n\n## Requirements\n\n- Linux (Wayland or X11) or macOS\n- Node.js and NPM\n- Chromium or Firefox (installed automatically by Puppeteer)\n\n## Installation\n\n- Clone the repo: `git clone https://github.com/sebastiancarlos/beachpatrol`\n- Move to the folder: `cd beachpatrol`\n- Run `npm install` to install dependencies.\n- Run `make` to install symlinks to the executables (in `/usr/local/bin` by\n  default, which should be in your `PATH`)\n\n## Example\n\n- Launch a browser with `beachpatrol`\n  - Optionally launch it in the background with `beachpatrol \u0026`\n- Use it as your regular browser. \n  - Install browser extensions if you want.\n  - If you close it. Run `beachpatrol` again and you should still be logged-in\n    to all your sites.\n  - If you want a different profile, use `beachpatrol --profile\n    new-profile-name`\n    - Note: Due to a Chromium's limitation, it is not possible to use the\n      in-browser's profile features to switch profiles. However, this might be\n      fixed in the future.\n- Run `beachmsg smoke-test` to run the pre-installed test command, which\n  performs the classic [Selenium smoke test](https://www.selenium.dev/documentation/webdriver/getting_started/first_script/).\n- If it reads \"Form submitted\", it worked correctly.\n- Now create your own automation scripts!\n\n## Technical details \n\nFirst and foremost, `beachpatrol` contains a customized Playwright script to\nlaunch your browser. It passes arguments which closely recreate the experience\nof using a non-automated browser. For example, it does not set a fixed viewport\n(which is, otherwise, a sensible default for Playwright's main use-case of\nautomated testing.)\n\nBeachpatrol also installs and loads the packages `playwright-extra` and\n`puppeteer-extra-plugin-stealth`. This is needed to hide the fact that the\nbrowser is automated, which in turn is needed for basic features such as Google\nSign-in. \n\nNaturally, the above package is tangentially related to a cat-and-mouse game\nbetween web-scrapers and web-masters. As such, it might stop working at any\ntime. Beachpatrol guarantees to find new automation-hiding techniques if that\nhappens. Beachpatrol also encourages users to respect every website's terms and\nconditions.\n\nAfter the browser is launched, it listens on a UNIX socket created on\n`/tmp/beachpatrol.sock` for messages by `beachmsg`.\n\n## Usage\n\n```bash\nUsage: beachpatrol [--profile \u003cprofile_name\u003e] [--incognito] [--headless]\n\nLaunches a browser with the specified profile.\nOpens a socket to listen for commands. Commands can be sent with\nthe 'beachmsg' command.\n\nOptions:\n  --profile \u003cprofile_name\u003e  Use the specified profile. Default: default\n  --browser \u003cbrowser_name\u003e  Use the specified browser. Default: chromium\n      Supported browsers: chromium, firefox\n  --incognito               Launch browser in incognito mode\n  --headless                Launch browser in headless mode\n```\n\n```bash\nUsage: beachmsg \u003ccommand\u003e [\u003carg\u003e...]\n\nSend commands to beachpatrol. The provided command must exist\nin the commands directory of beachpatrol.\n```\n\n## F.A.Q.\n\n### Isn't the claim that web browsers aren't automatable a bit far-fetched?\n\nWhen we say that web browsers aren't automatable, we're thinking more along \nthe lines of the depth of automation available with tools like Bash, Vim or Emacs \n(where virtually every interaction can be scripted and interwoven into custom\nworkflows without much resistance.)\n\nYes, we acknowledge there are existing ways to automate browser tasks like\nautofill, mouse and keyboard macros, bookmarklets, extensions, and of course \nvarious tools like Playwright.\n\nBeachpatrol aspires to bring a new spin to the state-of-the-art, re-imagining\nautomation tools not as a one-time task, but integrated into your daily\nbrowser. Just as your favorite shell or extendable text editor.\n\nIn short, our aim is to take existing automation tools (currently designed for\ntesting or scraping) and tweak them for everyday browsing, while also providing\na UI which is both simple and power-user friendly.\n\n### But what’s the point? Isn’t Beachpatrol just a wrapper around a Playwright browser?\n\nTrue, but it offers several value-added features:\n\n- **Automation Detection Evasion**: Beachpatrol carefully selects Playwright options and plugins to mirror the activity of a regular browser, helping to avoid detection mechanisms that websites use to identify and block automated browsers.\n- **Client/Server Architecture**: `beachpatrol` launches a browser and listens on a socket. The separate client `beachmsg` can then be used to transmit Playwright commands to the controlled browser. This separation allows for greater flexibility and integration with other tools and scripts.\n- **Browser Extension**: An accompanying browser extension is designed to also communicate with the socket and send commands. The extension provides a user-friendly graphical interface and contextual tools.\n\n### Why Playwright instead of Selenium?\n\nInitial browser launch benchmarks suggested us to prioritize Playwright.\n\n| Browser                  | Launch time |\n|--------------------------|-------------|\n| Playwright Chrome        |       1.7s  |\n| Selenium Node Chrome     |       1.8s  |\n| Selenium Java Chrome     |       4s    |\n| Playwright Firefox       |       4.3s  |\n| Selenium Java Firefox    |       6s    |\n| Selenium Node Firefox    |       9s    |\n\n### Why JavaScript/Node.js instead of Python?\n\nWhile Python is a popular language for web automation, we decided for JavaScript \nto enable code sharing with the browser extension.\n\n### Why use an external automation tool (Playwright) instead of a browser extension?\n\nSimilar functionality can indeed be achieved with Userscript managers, such as the [Violentmonkey](https://github.com/violentmonkey/violentmonkey) browser extension.\n\nBut, while Beachpatrol allows us to control the browser from both the OS and a browser\nextension, our priority is the OS. Also, there are [limitations](https://www.sitepoint.com/community/t/tampermonkey-access-local-files-and-commands/299771) on how much you can interact with the OS from a browser extension. Therefore, something like Playwright was\nthe natural choice.\n\nFurthermore, while controlling the browser from an extension is possible, [Manifest v3 removed the ability to execute third-party strings of code](https://developer.chrome.com/docs/extensions/develop/migrate/improve-security). Popular automation extensions like Greasemonkey and Tampermonkey could also be affected by Manifest v3. The alternative is to embed the code into the extension, but that would require re-bundling the extensions after every change. Other tricks do exist to make this approach work, and there is some hope for [future Manifest v3 solutions](https://github.com/w3c/webextensions/issues/279), but this path is certainly tricky.\n\nIt is more likely that Selenium and related tools will continue to work in the foreseeable future given the business demand for traditional browser testing.\n\n### How does Beachpatrol compare to bookmarklets for quick tasks?\n\nBookmarklets are handy for executing scripts with a click, but they are\nlimited to user-triggered actions and may not handle complex workflows, such\nas automation based on specific timing or interaction with operating system features.\n\nPlus, there's a personal preference factor. For those who like to have finer\ncontrol, keeping automation scripts within their file system feels cleaner and\nless bound to a particular browser ecosystem. However, we recognize that\nbookmarklets have their place and can be the preferred choice for many users.\n\n### Writing Playwright scripts for every task takes too long.\n\nYou can use [Chromium DevDool's Recorder tab](https://developer.chrome.com/docs/devtools/recorder/reference) to record actions and export them as\nPuppeteer scripts, which use the same API as Playwright.\n\nAlso, given Playwright's popularity, you can describe your task in natural language\nto an AI and ask for it as a Playwright script. With some practice, this should \nget you halfway to a working script.\n\n## Project Status\n\nThis project is in **alpha**. \n- The API is subject to change.\n- Currently Linux and macOS are supported.\n- Currently only Chromium and Firefox are supported.\n- The ability to run a command when a new URL matches a pattern will be added soon.\n- The `beachpatrol-browser-extension` is in early-testing and **not publicly\n  released.** It is expected to launch in a fully-functional state by the next\n  release.\n- Contributions welcome!\n\n## You might also like\n- [TabFS](https://github.com/osnr/TabFS)\n- [Violentmonkey](https://github.com/violentmonkey/violentmonkey)\n\n## License\nMIT\n\n## Contributing\nWe welcome contributions of all kinds. If you have a suggestion or fix, please feel free to open an issue or pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebastiancarlos%2Fbeachpatrol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsebastiancarlos%2Fbeachpatrol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebastiancarlos%2Fbeachpatrol/lists"}