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.1

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.1
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)

Table of built distributions (wheels) for headless-reaper 0.1.1
File Actions
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.

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