atomontage / chrome.el

Emacs remote tab control for Google Chrome

chrome.el is a portable Emacs interface to Google Chrome.

It is forked off of osa-chrome.el (https://github.com/atomontage/osa-chrome) which is an Emacs Mac port interface to Google Chrome and relies on Apple events as well as Yamamoto Mitsuharu’s excellent Emacs mac port.

In contrast, chrome.el only requires access to the Chrome DevTools debugging API and is thus fully cross-platform. Its only dependencies are stock Emacs and Google Chrome itself.

While this does represent a slight compromise in functionality and flexibility compared to the capabilities of the OSA enabled version of this code base, it is sufficient for a variety of daily workflow use cases and brings osa-chrome.el’s excellent narrowing capabilities to a much wider set of Chrome users.

Examples include:

• Controlling multiple remote Chrome instances that e.g. run inside a VM from Emacs
• Controlling multiple independent Chrome instances spawned from ephemeral profile managers such as https://github.com/atomontage/chrome-private

This fork/port aims to retain basic feature parity with osa-chrome.el where possible without introducing additional dependencies beyond DevTools API access.

See Additional Information for a list of differences with osa-chrome.el.

Getting Started

1. google-chrome –remote-debugging-port=9222
2. M-x chrome RET

To reset the session list you can M-x chrome-reset RET which will purge all active sessions from the session list.

To add another Chrome DevTools session on a different port you can M-x chrome-connect RET

NOTE: you can connect as many concurrent and independent Chrome DevTools connections sessions as you require, mixing both local and remote Chrome instances in a seamless Emacs orchestration experience.

Advanced users may manage the addition and removal of DevTools session via the chrome-sessions alist, which consists of (port . host) pairs, e.g. ‘(9222 . “127.0.0.1”). This facilates e.g. user specified functions that also manage spawning ephemeral Chrome instances with a managed range of DevTools ports.

Security Warning

Note that anyone with access to this port can both inspect and influence your Chrome Session. It may be possible to bypass CORS in certain scenarios and this may expose you to security risks. Do not use this on multi-user systems or expose DevTools API endpoints in untrusted network environments.

You can read more about the DevTools protocol here:

https://chromedevtools.github.io/devtools-protocol/

Additional Information

A partial list of differences with osa-chrome.el is included below. These stem from the underlying APIs (DevTools vs macOS automation).

• When visiting a tab, chrome.el always raises the Chrome window, unlike osa-chrome.el where this is up to the user.
• When accessing a restored Chrome session that contains a lot of tabs, chrome.el will retrieve and only be able to control tabs that Chrome fully loads, typically a small fraction of all tabs. osa-chrome.el retrieves and is able to control all tabs.
• chrome.el is only able to show one active tab per Chrome session. This means that when controlling tabs from multiple windows, some active tabs will not be shown as “active” in Emacs. This issue does not exist in osa-chrome.el which is able to accurately track and display all active tabs.
• chrome.el does not maintain an exact ordering of tabs as displayed in Chrome. osa-chrome.el tabs are always displayed in exactly the same order as they are in the browser, allowing the user to reason about tab lifetimes.
• When viewing the HTML source of a tab, chrome.el will open a new tab in Chrome that contains the HTML source. osa-chrome.el does not open any new tabs and simply shows the source in an Emacs side-buffer.

For further information, much of the original ose-chrome.el mode logic wrt filtering, use cases and methodoloy holds, and I recommend you read the original documentation for osa-chrome.el:

https://github.com/atomontage/osa-chrome/

Where possible chrome.el will maintain basic feature parity with osa-chrome.el.