Skip to main content

headless-reaper

한국어

A command-line tool that finds and stops orphaned headless browsers, with a dry run by default.

A disposable orphan browser is listed, reaped, and absent from the final scan

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

Select an eligible browser, report it, and terminate only when --kill is requested

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 ps output and cannot recover profile paths containing spaces reliably. Rust reads exact argv through KERN_PROCARGS2; Linux reads /proc in 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.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for headless-reaper 0.1.3
File Size Uploaded Provenance Actions
headless_reaper-0.1.3.tar.gz 39.6 kB Without provenance Details for headless_reaper-0.1.3.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for headless-reaper 0.1.3
File Actions
headless_reaper-0.1.3-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for headless_reaper-0.1.3-py3-none-win_amd64.whl
headless_reaper-0.1.3-py3-none-manylinux_2_28_x86_64.whl Python 3 none Linux glibc 2.28+ x86-64 Details for headless_reaper-0.1.3-py3-none-manylinux_2_28_x86_64.whl
headless_reaper-0.1.3-py3-none-manylinux_2_28_aarch64.whl Python 3 none Linux glibc 2.28+ ARM64 Details for headless_reaper-0.1.3-py3-none-manylinux_2_28_aarch64.whl
headless_reaper-0.1.3-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for headless_reaper-0.1.3-py3-none-macosx_11_0_arm64.whl
headless_reaper-0.1.3-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for headless_reaper-0.1.3-py3-none-macosx_10_12_x86_64.whl

Total release size: 1.6 MB

Release files / headless_reaper-0.1.3.tar.gz

Download URL headless_reaper-0.1.3.tar.gz
Size 39.6 kB
Tags Source
SHA-256 checksum
How to use checksums
7bbaf0e6ee46e636117e520475703bd733adeda3838c5a9910ee50ee7596c53f
BLAKE2b-256 checksum
How to use checksums
c00e1a488a949e2dd34b39ffefbd6f1aa2e5b98aeab2f1424d095f455f46cfab
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via maturin/1.16.0

Release files / headless_reaper-0.1.3-py3-none-win_amd64.whl

Download URL headless_reaper-0.1.3-py3-none-win_amd64.whl
Size 192.5 kB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
88a8f34af68e30b1402d0a729790574de634ea29b952ad31546955f8c9d09ccd
BLAKE2b-256 checksum
How to use checksums
0c68f4cf3528380e0133c23889eda1a865832b1e575c6e6c599a4557343bc34d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via maturin/1.16.0

Release files / headless_reaper-0.1.3-py3-none-manylinux_2_28_x86_64.whl

Download URL headless_reaper-0.1.3-py3-none-manylinux_2_28_x86_64.whl
Size 333.5 kB
Tags Linux glibc 2.28+ x86-64 Python 3
SHA-256 checksum
How to use checksums
a1d7a3f5ce4f22515e63d2fe88c65d43ea40c9d8f4063587cf319cd70abf93ee
BLAKE2b-256 checksum
How to use checksums
4aa2f4715aa71f1f67c8f156677fea99e83a0c21abd468923f3f9ccfb68dbe1f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via maturin/1.16.0

Release files / headless_reaper-0.1.3-py3-none-manylinux_2_28_aarch64.whl

Download URL headless_reaper-0.1.3-py3-none-manylinux_2_28_aarch64.whl
Size 316.3 kB
Tags Linux glibc 2.28+ ARM64 Python 3
SHA-256 checksum
How to use checksums
db10dfc7030c51096b5dfbd2f8afae3ab0dc3f9f2ddd2d75fea844fc60ba377a
BLAKE2b-256 checksum
How to use checksums
e3c5fe24de586310587a41eba82e00bcf57b17c444e1b2cb261dd4da0a8a8c3f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via maturin/1.16.0

Release files / headless_reaper-0.1.3-py3-none-macosx_11_0_arm64.whl

Download URL headless_reaper-0.1.3-py3-none-macosx_11_0_arm64.whl
Size 339.2 kB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
5ce7626bbcaece67fd19df8fd3f9d482a4608e7d62bc9c43bf753ac8232c5f87
BLAKE2b-256 checksum
How to use checksums
cffd4f2b382bb712a3f4cb5e0a1030b5b80c8d57b407d3312c2e67955d84541c
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.3-py3-none-macosx_10_12_x86_64.whl

Download URL headless_reaper-0.1.3-py3-none-macosx_10_12_x86_64.whl
Size 356.3 kB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
8df84169450109655b7cc7218fbf06f28b2840ac3dbc37ee0d388062a9fef168
BLAKE2b-256 checksum
How to use checksums
5eb6b140bc02637df1edc7e0da5a8f1e30181da3c734e9e3af24ddfb25cdb733
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.3

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page