Tabrelay / Automate Chrome without stealing focus
Automate Chrome in the background without stealing focus
Automation that pops a window in front of you every few minutes gets turned off. Tabrelay jobs run in background windows and tabs, so you can keep typing while they work.
Chrome or Chromium, Python 3.10+, macOS and Linux. Source on GitHub.
Why automation steals focus
Browsers throttle pages that are hidden or behind other windows, and sites such as uploaders and lazy-loaded pages may not finish until they believe they have focus. The usual workaround is to bring the window to the front, which interrupts you.
Background windows and focus emulation
tabrelay open URL opens a new unfocused window and prints the tab id. When a script calls front(tab), Tabrelay uses focus emulation and an active lifecycle state, so the page is told it has focus and keeps working without being raised. That is what keeps file uploads and lazy pages working while you type in another app.
tab = tr.job("open", url="https://example.com/")["tabId"]
tr.front(tab) # focus emulation, no raise
tr.wait_for(tab, "document.readyState == 'complete'", 30)
If a site still stalls in the background (a <video> preview that never loads, for example), set TABRELAY_FRONT=1 or use front(tab, force=True) to raise the window as a last resort. On macOS, Chrome throttles windows that are hidden or behind others, so this is where you are most likely to need it.
Several Chrome profiles
Load the same extension/ folder in each profile. Each reports the Google account its profile is signed in to, and the server keeps one queue per account. tabrelay profiles lists the connected copies. Choose one with profile in ~/.config/tabrelay/config.json or with TABRELAY_PROFILE=ACCOUNT_EMAIL tabrelay tabs. With several profiles connected and none chosen, a job goes to whichever asks first, so set one.
Keep logins alive with keepalive
Some sites end a session after a few hours without a visit. keepalive.py visits each site from the keepalive section of your config in an inactive background tab, waits for the page to refresh its session, checks for a marker that only the logged-in page shows, and closes the tab. A lost login raises a desktop notification with the login URL. It never starts Chrome; if Chrome is not running, the run is skipped.
./keepalive.py --only github # test one site now
./keepalive.py --status # last visit and state per site
scripts/install-keepalive.sh # macOS: every 30 minutes with launchd
On Linux a cron line does the same. Remember that every site you add to a keepalive also needs to be on the extension's allow-list.
Be a good guest
Run jobs at a human pace, give scripts a --draft mode while you build them, and follow each site's terms of service and automation rules. See using a logged-in browser safely.
More: control Chrome from the command line. Download Tabrelay from the latest release.
Frequently asked questions
Does Tabrelay raise Chrome windows?
Not normally. Jobs run in background windows and tabs. Raising the window is a last resort, with TABRELAY_FRONT=1 or front(tab, force=True).
Why do some pages stall in the background?
Chrome throttles hidden windows. Focus emulation handles most pages, but a few sites, such as a video preview that never loads, still need the window raised.
How do I stop a site logging me out?
Use keepalive.py. It visits sites on a schedule in an inactive background tab, checks that you are still logged in and notifies you if not.
How do I choose which Chrome profile a job uses?
Set profile in the config file to the Google account email of that profile, or use TABRELAY_PROFILE for one command.
Chrome or Chromium, Python 3.10+, macOS and Linux. Source on GitHub.