headless-reaper
A command-line tool that finds and stops orphaned headless browsers, with a dry run by default.
The demo starts a dedicated headless shell from a short-lived parent, then reaps that browser's /tmp profile. It never launches Google Chrome. Recording source.
Install
pipx install headless-reaper
uv tool install headless-reaper
pip install headless-reaper
Python 3.9+. Wheels install the Rust CLI and an importable Python reference. Source installs need Rust; cargo install --path rust --locked installs the standalone command.
| Platform | Observed behavior |
|---|---|
| macOS arm64 | Orphan detection and cleanup; live-parent browser preserved |
| Ubuntu 24.04 arm64 | Chromium and Firefox orphan cleanup; live-parent browser preserved |
| Windows x64 | Both editions exit 2: browser reaping is unsupported |
Quick start
Start with a dry run. These outputs came from a disposable headless-shell process. The environment variable limits every command to that one profile; replace the path with your own job's profile directory.
$ export HEADLESS_REAPER_PATH=/tmp/reaper-demo.58q834un
$ headless-reaper
headless-reaper 0.1.0: 1 orphaned group, 4 processes, 224.8 MB RSS (1024 processes scanned, paths /tmp/reaper-demo.58q834un)
ROOT AGE RSS PIDS PROFILE
18952 1s 224.8 MB 4 /tmp/reaper-demo.58q834un
why: headless, temp profile, remote debugging; launcher gone (reparented to launchd 1)
dry run: nothing was killed. Rerun with --kill to terminate these groups.
$ headless-reaper --kill
headless-reaper 0.1.0: 1 orphaned group, 4 processes, 224.8 MB RSS (1024 processes scanned, paths /tmp/reaper-demo.58q834un)
ROOT AGE RSS PIDS PROFILE
18952 1s 224.8 MB 4 /tmp/reaper-demo.58q834un
why: headless, temp profile, remote debugging; launcher gone (reparented to launchd 1)
reaped 1 group: sent SIGTERM to 4 of 4 processes, SIGKILL to 0.
$ headless-reaper
headless-reaper 0.1.0: no orphaned headless browsers (1024 processes scanned, paths /tmp/reaper-demo.58q834un).
The second scan confirms that the scoped browser is gone. Process counts, PIDs and RSS will differ on your machine.
Why
A crashed test can leave its browser running after the test process is gone. You can find it with ps, but deciding which helpers belong to it takes another step. headless-reaper groups the browser tree and checks whether its launcher still exists before proposing cleanup.
Use your test framework's browser-close call for normal teardown. Use ps or a process monitor when you need to inspect arbitrary processes. This tool handles leftovers: it requires a recognized browser, an automation signal, and a missing launcher. A default personal profile is excluded.
Measurements
Saved measurements from 2026-11-17: median of 20 sequential subprocess runs, warm filesystem cache, release Rust 1.100.0. Startup ran --version; scanning ran --json --path /tmp/headless-reaper-bench-empty and still read the whole process table. Peak RSS came from a separate /usr/bin/time scan. These are two hosts and their process populations, not a claim about every machine.
| Platform / edition | Startup (ms) | Scan (ms) | Peak RSS (KiB) |
|---|---|---|---|
| macOS arm64 / Python 3.12.8 | 36.078 | 122.098 | 23,296 |
| macOS arm64 / Rust | 2.856 | 11.315 | 3,136 |
| Ubuntu 24.04 arm64 / Python 3.12 | 68.953 | 76.615 | 15,144 |
| Ubuntu 24.04 arm64 / Rust | 0.841 | 5.564 | 1,892 |
Reference
| Option | Default | Meaning |
|---|---|---|
--kill |
Off | SIGTERM, wait, then SIGKILL for surviving targets |
--path PREFIX |
All profiles | Limit profile paths; repeat for several prefixes |
--min-age DURATION |
0 |
Skip younger groups; accepts 30s, 10m, 2h, 1d |
--grace DURATION |
10s |
Wait between SIGTERM and SIGKILL |
--remove-profiles |
Off | With --kill, remove eligible temporary profiles |
--json |
Off | Report groups, totals, cleanup results and errors as JSON |
--clean-clones |
Off | Inspect unused macOS code-signing clones; add --kill to delete |
--all-leftovers |
Off | Combine --kill, --clean-clones and --remove-profiles |
Exit 0 means a dry run succeeded or all targets were reaped. Exit 1 means a target survived or inspection failed. Exit 2 means invalid usage or an unsupported platform.
HEADLESS_REAPER_PATH, HEADLESS_REAPER_MIN_AGE, and HEADLESS_REAPER_GRACE set defaults. Paths use : as the separator on macOS/Linux. Flags override environment values. There is no configuration file.
Target selection
An eligible target is a recognized automation browser whose launcher is gone and whose path and age match your scope. Personal default profiles are excluded. KILL is only for processes surviving the grace period.
A root must be a recognized Chrome/Chromium, Edge, Firefox, or WebKit browser process, not a renderer or helper. It must carry --headless, a temporary or automation profile, or remote debugging together with such a profile. Its parent must be PID 1, an init process, or missing from the snapshot.
The tool groups descendants under the root. Before signalling, it compares process start times to avoid signalling a recycled PID. It excludes default personal profiles and browsers whose launcher is alive.
Profile and clone cleanup
--remove-profiles requires --kill. Cleanup preserves a profile outside temporary roots, one still used by a live browser, one with a live singleton lock, or one whose group left a survivor.
On macOS, --clean-clones examines recognized browser code_sign_clone.* directories under the current user's X temp directory. It uses a ten-minute minimum age unless you set one. Directory symlinks and live uses are preserved; matching includes device/inode identity because clones may share hard links. An open-file scan failure prevents deletion.
Clone reports distinguish apparent size, allocated blocks, and observed free-space change. Shared APFS blocks mean apparent size is not reclaimable space. --path filters browser profiles; it does not change the fixed clone scope. Clone-only mode does nothing on other operating systems.
Python
import time
from headless_reaper import find_groups, list_processes
groups = find_groups(list_processes(), now=time.time(),
min_age=600, paths=("/tmp/my-test",))
for group in groups:
print(group.root.pid, group.profile, group.rss_bytes())
reap(groups) terminates selected groups; cleanup_profiles(groups) handles their temporary profiles. clean_clones(kill=False, min_age=600) performs a macOS clone dry run. python -m headless_reaper selects the Python CLI explicitly.
Limits
- A browser launched directly by launchd or systemd looks orphaned. Scope cleanup with
--path; an age threshold alone does not establish ownership. - WebKit's argument detection was checked, but a live WebKit browser was not exercised because the test host lacked GTK 4.
- macOS/Linux x86_64 backends were not exercised. Windows has no browser backend.
- The Python macOS backend reads
psoutput and cannot recover profile paths containing spaces reliably. Rust reads exact argv throughKERN_PROCARGS2; Linux reads/procin both editions. - A visible automation browser with a custom home-directory profile can remain after its launcher exits. The detector does not treat every remote-debugging browser as disposable.
Contributing
Issues and platform reports are welcome; run cargo test --manifest-path rust/Cargo.toml from the source checkout. See AGENTS.md for the code layout and safety rules.
License: MIT.
Unofficial; not affiliated with Google, Mozilla, Microsoft, or the browser automation projects mentioned here.
Metadata
Release files for headless-reaper 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| headless_reaper-0.1.1.tar.gz | 39.4 kB | Without provenance | Details for headless_reaper-0.1.1.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| headless_reaper-0.1.1-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details for headless_reaper-0.1.1-py3-none-win_amd64.whl |
| headless_reaper-0.1.1-py3-none-manylinux_2_28_x86_64.whl | Python 3 | none | Linux glibc 2.28+ x86-64 | Details for headless_reaper-0.1.1-py3-none-manylinux_2_28_x86_64.whl |
| headless_reaper-0.1.1-py3-none-manylinux_2_28_aarch64.whl | Python 3 | none | Linux glibc 2.28+ ARM64 | Details for headless_reaper-0.1.1-py3-none-manylinux_2_28_aarch64.whl |
| headless_reaper-0.1.1-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details for headless_reaper-0.1.1-py3-none-macosx_11_0_arm64.whl |
| headless_reaper-0.1.1-py3-none-macosx_10_12_x86_64.whl | Python 3 | none | macOS 10.12+ x86-64 | Details for headless_reaper-0.1.1-py3-none-macosx_10_12_x86_64.whl |
Total release size: 1.6 MB
Release files / headless_reaper-0.1.1.tar.gz
| Download URL | headless_reaper-0.1.1.tar.gz |
|---|---|
| Size | 39.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6c0fb58b2166b3219aae6e203a92dc3c7e2eeb84ed662c0cb6dc50371fb6b29d
|
|
BLAKE2b-256 checksum How to use checksums |
1383513721473ef0f8e5a01380ec249206382a2cf5f77f604c55ecbe46f8509d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
maturin/1.16.0
|
Release files / headless_reaper-0.1.1-py3-none-win_amd64.whl
| Download URL | headless_reaper-0.1.1-py3-none-win_amd64.whl |
|---|---|
| Size | 192.3 kB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
e5e4879205ff976fa4bbfdfed376fbffb8a27a9d4883bf96d07bf78a890d2cb0
|
|
BLAKE2b-256 checksum How to use checksums |
8ef474efc312bdf7a42f36df50021a216fd3f668edf5f4d7edebadaee1a3c7fa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.8
|
Release files / headless_reaper-0.1.1-py3-none-manylinux_2_28_x86_64.whl
| Download URL | headless_reaper-0.1.1-py3-none-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 333.2 kB |
| Tags | Linux glibc 2.28+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
3a1ca1f556573068634afafd7a696315eabad83f558fbb5e0d98cb4db40f1174
|
|
BLAKE2b-256 checksum How to use checksums |
83d19a5ab0568efda8d3fe51d5212caaad96d2c6b44b6b25cb37bea4d64c7e71
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.8
|
Release files / headless_reaper-0.1.1-py3-none-manylinux_2_28_aarch64.whl
| Download URL | headless_reaper-0.1.1-py3-none-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 316.2 kB |
| Tags | Linux glibc 2.28+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
01126bf030cf6d85a653dfeaf542625a0177e91e761104fd936b1ccd9c2d5abc
|
|
BLAKE2b-256 checksum How to use checksums |
b9feadd3f44a552328d484486bf1a5beac37932abb328b92c5b49715fe754070
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.8
|
Release files / headless_reaper-0.1.1-py3-none-macosx_11_0_arm64.whl
| Download URL | headless_reaper-0.1.1-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 339.4 kB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
a325672c8ee9cb23ef77adba60a681e890b635380e353f6931c61603ff3386a8
|
|
BLAKE2b-256 checksum How to use checksums |
213d36ba1109e028afb4b0aab2138519e3cc8fd13d812f08888189ef77bb2d9b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.8
|
Release files / headless_reaper-0.1.1-py3-none-macosx_10_12_x86_64.whl
| Download URL | headless_reaper-0.1.1-py3-none-macosx_10_12_x86_64.whl |
|---|---|
| Size | 356.2 kB |
| Tags | Python 3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
8a6b75d6f548849df4a57d50306e50c023d75b56ae45851112315ade3b727c14
|
|
BLAKE2b-256 checksum How to use checksums |
5b1b5e54724525e23e091b1dc4383d5d7851601b474374ecee133a64e8f370ad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.8
|
Security for headless-reaper 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.