headless-reaper
Find the headless browsers that a test or automation tool abandoned, and stop them — dry run by default.
$ headless-reaper
headless-reaper 0.1.0: 1 orphaned group, 8 processes, 705 MB RSS (998 processes scanned)
ROOT AGE RSS PIDS PROFILE
13251 1m 12s 705 MB 8 /tmp/hr-readme/profile
why: headless, temp profile, remote debugging; launcher gone (reparented to launchd 1)
dry run: nothing was killed. Rerun with --kill to terminate these groups.
A test launches Chrome in headless mode, then crashes, or calls process.exit() before its cleanup runs. The browser is reparented to the init process, keeps its tabs and its renderers, and holds memory for days. One such run left 57 browser processes holding about 24 GB.
This tool reads the process table, groups each browser tree under its main process, and kills a tree only when its launcher is gone. It never touches a browser a person is using.
Why
- Only orphans. A group is killed only when its parent is PID 1, an init process, or a PID that no longer exists. A browser whose launcher is still alive is reported as nothing and left alone.
- Only automation. A target must carry an automation signal:
--headless, a temp or automation--user-data-dir, or a remote debugging switch together with such a profile. A visible browser on a real user profile is never a target, even when it has--remote-debugging-port. - Whole trees. Renderers, GPU and utility helpers are grouped with their main process, so the reported RSS is the memory the tree actually holds, and one command stops all of it.
- A safe ladder.
--killsends SIGTERM to every process in the group, waits 10 seconds by default, then sends SIGKILL to what survived. A recycled PID is detected by comparing start times before a signal is sent. - Two editions. The Rust CLI reads macOS through libproc/sysctl and Linux through
/proc. The Python reference uses only its standard library (pson macOS,/procon Linux). Neither needs a browser or network to scan. - Optional profile cleanup.
--remove-profilesdeletes the temp profile of a reaped group only when it is under a temp root, no live browser uses it, and no singleton lock is held.
Install
$ pipx install headless-reaper # recommended: isolated, on PATH
$ uvx headless-reaper --help # or run without installing
$ pip install headless-reaper # inside a project
Python 3.9 or newer for the Python package. macOS and Linux have process backends. Both editions report Windows as unsupported and exit 2.
Rust command and Python library in one package
The wheel uses maturin bindings = "bin": pipx install headless-reaper installs the native headless-reaper executable. The same wheel includes src/headless_reaper, so import headless_reaper and python -m headless_reaper still use the pure-Python reference. No Python extension or interpreter is needed by the Rust executable itself.
Build from this source with a current stable Rust toolchain:
$ cargo install --path rust --locked
$ python -m venv .venv
$ .venv/bin/pip install maturin
$ .venv/bin/maturin build --release --out dist
$ .venv/bin/pip install dist/*.whl
$ .venv/bin/python -c 'import headless_reaper; print(headless_reaper.__version__)'
A source install through pip also needs Rust. To run only the reference edition from a checkout, use PYTHONPATH=src python -m headless_reaper. The Rust crate is edition 2021; its direct dependencies are libc (Unix process APIs) and serde_json (JSON encoding). Cargo.lock pins their resolved versions.
The Rust CLI keeps the reference's flags, environment variables, table, JSON fields and exit codes. rust/parity.sh compares both commands, normalizing changing snapshot counters (scanned processes, age and RSS) while preserving their types. Run rust/parity.sh --json --path /tmp/your-test to compare a live fixture. Mutating parity requires an empty scope because the first command consumes any target. Use cargo test --manifest-path rust/Cargo.toml for the live-parent, default-profile, helper and path-boundary fixtures.
.github/workflows/wheels.yml prepares macOS arm64/x86_64, manylinux x86_64/aarch64 and Windows x86_64 wheels plus an sdist. It builds artifacts only; it does not upload to PyPI.
Measured editions
Measured 2026-11-17, Rust 1.100.0, release builds. Each time is the median of 20 sequential subprocess runs, including process launch. Startup uses --version; scan uses --json --path /tmp/headless-reaper-bench-empty and still reads the whole process table. Peak RSS is a separate scan measured with /usr/bin/time (-l on macOS, -v on Linux). Filesystem caches were warm; these are two machines and their current process populations, not a general benchmark.
| OS / CPU | Edition | Startup (ms) | Scan (ms) | Scan peak RSS (KiB) | Binary (bytes) |
|---|---|---|---|---|---|
| macOS 27 / arm64 | Python 3.12.8 | 36.078 | 122.098 | 23,296 | — |
| macOS 27 / arm64 | Rust | 2.856 | 11.315 | 3,136 | 620,000 |
| Ubuntu 24.04 / arm64 | Python 3.12 | 68.953 | 76.615 | 15,144 | — |
| Ubuntu 24.04 / arm64 | Rust | 0.841 | 5.564 | 1,892 | 594,688 |
Rust's lower scan time and RSS justify preferring the native command in scheduled callers, with python -m headless_reaper as the fallback when it is missing.
On both OSes, a deliberate orphan using a literal throwaway profile under /tmp passed table/JSON parity, was reaped with zero running survivors, and had its temp profile removed. A second browser with a live parent was preserved. The macOS fixture had 10 processes; the Linux Chromium headless-shell fixture had 6. The 18-case CLI parity suite passed on macOS, Linux and Windows; Windows Rust was built with the GNU x86_64 toolchain and its unsupported-backend response was exercised. The macOS binary also scanned successfully on a second arm64 Mac.
Usage
Look
$ headless-reaper
This is a dry run: nothing is signalled. The header gives the total, then one row per browser tree with its root PID, age, resident memory, process count and profile directory, and a why line that names the signals and the reason the launcher counts as gone.
Stop
$ headless-reaper --kill
headless-reaper 0.1.0: 1 orphaned group, 7 processes, 705.1 MB RSS (1003 processes scanned)
ROOT AGE RSS PIDS PROFILE
13251 1m 53s 705.1 MB 7 /tmp/hr-readme/profile
why: headless, temp profile, remote debugging; launcher gone (reparented to launchd 1)
reaped 1 group: sent SIGTERM to 7 of 7 processes, SIGKILL to 0.
When a process ignores SIGTERM, the same run ends with SIGKILL to 1, and a process that survives even that is named in the output. The exit code is 0 when every target is gone and 1 when one survived.
Scope it
A shared machine runs several jobs at once. Two filters keep the sweep inside one of them:
$ headless-reaper --path /srv/app/_tmp
$ headless-reaper --kill --path /srv/app/_tmp --min-age 30m
--path matches the profile directory, not the executable. Repeat it for more than one prefix. --min-age skips trees younger than the given duration, so a browser started a minute ago by a job that is still starting up is left alone. Durations are 30s, 10m, 2h, 1d, or a plain number of seconds.
Remove the temp profiles
$ headless-reaper --kill --remove-profiles
reaped 1 group: sent SIGTERM to 8 of 8 processes, SIGKILL to 0.
removed temp profile: /tmp/hr-readme/profile
A profile is kept, with the reason printed, when it is not under a temp root, when a live browser still uses it, when a SingletonLock points at a live process, or when the group left a survivor. Playwright and Puppeteer create a fresh profile per launch, so on a long-lived test machine these directories add up too.
Machine-readable
$ headless-reaper --json | python3 -m json.tool
{
"ok": true,
"version": "0.1.0",
"platform": "darwin",
"dry_run": true,
"scanned": 1013,
"min_age_seconds": 0,
"paths": [
"/tmp/hr-json"
],
"totals": {
"groups": 1,
"processes": 13,
"rss_bytes": 1320402944
},
"groups": [
{
"root_pid": 22308,
"pids": [
22308,
22316,
22317,
22319,
22322,
22324,
22325,
22326,
22328,
22329,
22542,
22560,
22596
],
"processes": 13,
"profile": "/tmp/hr-json/profile",
"signals": [
"headless",
"temp profile"
],
"reason": "launcher gone (reparented to launchd 1)",
"age_seconds": 10,
"age": "10s",
"rss_bytes": 1320402944,
"rss": "1.2 GB"
}
],
"reap": null
}
With --kill, reap becomes an object with targets, sigterm, sigkill, survivors, already_gone, denied, removed_profiles and kept_profiles. An error prints {"ok": false, "error": "…"} and exits non-zero.
Code-signing clones on macOS
Chrome can leave a code-signing copy of its app bundle under the user's X temp directory on each launch, especially after it is killed. Chromium, Edge and Chrome for Testing use the same kind of directory. On one measured host, 174 clones accounted for 193 GB apparent size; deleting 171 unused clones increased real free space by only 1.5 GB. Hard links and shared APFS blocks explain why directory totals can be much larger than the physical space recovered. The directories still accumulate and distort disk alerts.
$ headless-reaper --clean-clones # dry run, default min age 10m
$ headless-reaper --kill --clean-clones --min-age 30m
$ headless-reaper --all-leftovers # --kill + --clean-clones + --remove-profiles
--clean-clones alone inspects clones without scanning browser groups or deleting anything. It examines only code_sign_clone.* directories under the recognized browser bundle directories in $(getconf DARWIN_USER_TEMP_DIR)/../X. It rejects directory symlinks. --path still filters browser profiles; it does not expand or change this fixed clone scope. On Linux and Windows clone-only mode says nothing to do on this OS; Windows --all-leftovers still exits 2 because the browser backend is unsupported.
A clone must be older than --min-age and unused by running processes. Both editions use native proc_pidpath for exact executable paths and lsof -nP for open and mapped files. Some same-user protected processes refuse native descriptor-path queries, so those queries cannot replace lsof here. Matching includes file device/inode identity: Chrome clones can hard-link the same executable as /Applications, and a pathname alone can name a different link on the next scan. A running browser can therefore preserve several shared clones. Run scheduled cleanup after Chrome quits. A failed open-file scan preserves all clones and exits 1.
The dry run reports eligible count and apparent bytes. JSON adds a clones object with candidates, kept, removed, apparent_bytes, allocated_bytes, reclaimable_bytes_estimate and free_space_change_bytes. Allocated blocks can be shared, so the reclaimable estimate is null. A deletion pass reports the observed filesystem free-space change, which can also include concurrent disk activity. It rechecks usage before deleting anything.
The local cleanup fixture removed an aged unused clone and preserved an open file reached through a hard link outside the clone, plus a symlink to a directory outside X. The manual Rust sweep changed the fixture-inclusive count from 6 to 5. It did not quit any real Chrome window.
From cron or a launcher
The tool is quiet when there is nothing to do, and exits 0 after a successful sweep:
$ 30 4 * * * headless-reaper --kill --min-age 30m
--min-age 30m is the useful guard for a scheduled sweep: a browser that started five minutes ago belongs to a job that is probably still running, and its launcher is still alive anyway.
Options
| Option | Default | Meaning |
|---|---|---|
--kill |
off | Terminate the groups: SIGTERM, wait, then SIGKILL |
--clean-clones |
off | Inspect unused macOS code-sign clones; delete only with --kill |
--all-leftovers |
off | --kill --clean-clones --remove-profiles |
--min-age DURATION |
0 (10m with clone cleanup) |
Skip groups younger than this (10m, 2h, 1d) |
--path PREFIX |
every path | Only profiles under PREFIX; repeatable |
--remove-profiles |
off | With --kill, delete the temp profile of a reaped group |
--grace DURATION |
10s |
Wait between SIGTERM and SIGKILL |
--json |
off | Print one machine-readable object |
--version |
Print the version |
Exit codes: 0 dry run, or every target reaped; 1 a target survived or the process table could not be read; 2 bad usage or an unsupported platform.
What counts as a target
A process becomes a group root only when all of these hold:
- Its executable is a browser family the tool knows: Chrome, Chromium, Edge, Chrome for Testing, Playwright's Chromium and headless shell, Puppeteer's Chrome, Firefox (including Playwright's build), or WebKit's mini browser.
- It is a browser main process, not a helper. A helper carries
--type=…,-contentproc, or a name such as… Helper,WebKitWebProcess,chrome_crashpad_handler. - It carries an automation signal:
--headless, or a--user-data-dirthat is under a temp root or is shaped like an automation profile (playwright_*dev_profile-*,puppeteer_dev_*_profile-*,scoped_dir*), or a--remote-debugging-*switch together with such a profile. - Its launcher is gone: the parent is PID 1, a process named
launchd,initorsystemd, or a PID that no longer exists.
The whole tree under that root is the group. A helper that outlived the root and was reparented to init joins the group through its shared profile path instead of becoming a stray group.
Never a target:
- a browser on macOS's or Linux's real user profile (
~/Library/Application Support/Google/Chrome,~/.config/google-chrome,~/.mozilla/firefox, and siblings), even with--headless; - a visible browser without an automation profile, even with
--remote-debugging-port; - a browser whose parent process is alive.
Environment
| Variable | Same as | Example |
|---|---|---|
HEADLESS_REAPER_MIN_AGE |
--min-age |
30m |
HEADLESS_REAPER_PATH |
--path |
/srv/app/_tmp:/srv/other/_tmp |
HEADLESS_REAPER_GRACE |
--grace |
5s |
A command-line flag wins over its variable. HEADLESS_REAPER_PATH uses the platform path separator: : on macOS and Linux.
Python API
import time
from headless_reaper import clean_clones, cleanup_profiles, find_groups, list_processes, reap
procs = list_processes()
groups = find_groups(procs, now=time.time(), min_age=600, paths=("/srv/app/_tmp",))
for group in groups:
print(group.root.pid, group.profile, group.signals, group.rss_bytes())
result = reap(groups)
print(result.sigterm, result.sigkill, result.survivors)
removed, kept = cleanup_profiles(groups)
clones = clean_clones(kill=False, min_age=600) # macOS only; a dry run
list_processes() returns Proc records (pid, ppid, rss_bytes, started_at, state, exe, argv). find_groups() returns Group records with root, members, profile, signals, reason, and helpers pids, rss_bytes(), age_seconds(now).
Limits
Tested on:
- macOS 27, arm64, Google Chrome 157: a deliberate orphan made by launching headless Chrome from a short-lived parent, then a second one from a live parent. The first was found and stopped, the second was left alone, and the machine's normal Chrome windows were untouched.
- Ubuntu 24.04, arm64, Playwright Chromium headless shell 159 and Playwright Firefox 159: a deliberate orphan for each, found, stopped, and its temp profile removed. The real Playwright launch arguments (
--headless,--user-data-dir=/tmp/playwright_chromiumdev_profile-…,--remote-debugging-pipe;-headless -profile …for Firefox) are what the detector matches.
Not tested:
- Windows browser detection. Both editions deliberately have no backend. The Rust GNU x86_64 build and the matching exit-2 response were checked; no browser is scanned or killed there.
- WebKit live. The Playwright WebKit build on the test host was missing its GTK 4 libraries, so only its argument shape (
pw_run.sh --headless --user-data-dir=/tmp/playwright_webkitdev_profile-…) was checked against the detector, not a running browser. - macOS/Linux x86_64. Their process backends have not been run on x86_64. The Windows x86_64 build only exercises the unsupported-platform branch.
- Python macOS
psand spaces. The reference cannot recover a profile path containing spaces fromps. Rust usesKERN_PROCARGS2for exact argv and libproc for PID, parent, start time and RSS. Linux reads exact argv in both editions. An inaccessible macOS PID is retained as an unknown process so its children cannot be mistaken for orphans. - A browser started directly by launchd or systemd. Its parent is the init process, so it looks exactly like an orphan. Scope it with
--path, or give it a--min-agelarger than its restart interval. - A visible automation browser on a real profile. Puppeteer with
headless: falseand a project profile under your home directory is not reaped, even if its launcher died. That is deliberate: the tool prefers to leave a visible window running over closing one a person may be using. Put such profiles under a temp root if you want them swept.
Agents
If you are an AI agent asked to clean up leftover browsers, read AGENTS.md. The Claude Code skill lives in skill/headless-reaper/SKILL.md; install it by copying that folder to ~/.claude/skills/headless-reaper/.
License
MIT — see LICENSE.
Metadata
Release files for headless-reaper 0.1.0
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.0.tar.gz | 50.9 kB | Without provenance | Details for headless_reaper-0.1.0.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| headless_reaper-0.1.0-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details for headless_reaper-0.1.0-py3-none-win_amd64.whl |
| headless_reaper-0.1.0-py3-none-manylinux_2_28_x86_64.whl | Python 3 | none | Linux glibc 2.28+ x86-64 | Details for headless_reaper-0.1.0-py3-none-manylinux_2_28_x86_64.whl |
| headless_reaper-0.1.0-py3-none-manylinux_2_28_aarch64.whl | Python 3 | none | Linux glibc 2.28+ ARM64 | Details for headless_reaper-0.1.0-py3-none-manylinux_2_28_aarch64.whl |
| headless_reaper-0.1.0-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details for headless_reaper-0.1.0-py3-none-macosx_11_0_arm64.whl |
| headless_reaper-0.1.0-py3-none-macosx_10_12_x86_64.whl | Python 3 | none | macOS 10.12+ x86-64 | Details for headless_reaper-0.1.0-py3-none-macosx_10_12_x86_64.whl |
Total release size: 1.6 MB
Release files / headless_reaper-0.1.0.tar.gz
| Download URL | headless_reaper-0.1.0.tar.gz |
|---|---|
| Size | 50.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4d28631e5ecb2ca9c16938f89f0d3b26d464f843f9f07bb203e5ea3574279583
|
|
BLAKE2b-256 checksum How to use checksums |
34a887812b3708b94661095f5647decd1ca68efe6af62c7b0db7060432178d32
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
maturin/1.16.0
|
Release files / headless_reaper-0.1.0-py3-none-win_amd64.whl
| Download URL | headless_reaper-0.1.0-py3-none-win_amd64.whl |
|---|---|
| Size | 196.0 kB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
f77ec3a8f1fe997f2086812dc7ca060c22851f5ef1fa6264841f04d96d525923
|
|
BLAKE2b-256 checksum How to use checksums |
227225c28463eee91c58e94eb0ae11cd80501cfabc1c1c7e93a5e49cfd70646a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
maturin/1.16.0
|
Release files / headless_reaper-0.1.0-py3-none-manylinux_2_28_x86_64.whl
| Download URL | headless_reaper-0.1.0-py3-none-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 337.0 kB |
| Tags | Linux glibc 2.28+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
36b0e78b8f91523015bb8eec07ba9ea54267ca71260db57c6d63095e0927cf08
|
|
BLAKE2b-256 checksum How to use checksums |
196c5d399cf74a116f28f805cc8c58e9dd5fc0a8d7812ba7a10620ed64f21540
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
maturin/1.16.0
|
Release files / headless_reaper-0.1.0-py3-none-manylinux_2_28_aarch64.whl
| Download URL | headless_reaper-0.1.0-py3-none-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 319.9 kB |
| Tags | Linux glibc 2.28+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
5e67ba9b0abc987f17c5f8fca54184f67bc151eee30d25db353381bc4ae72d19
|
|
BLAKE2b-256 checksum How to use checksums |
f3004989d28e320f565ee4c47de4018d357ed7fba59752e35389d52c3e5c87a6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
maturin/1.16.0
|
Release files / headless_reaper-0.1.0-py3-none-macosx_11_0_arm64.whl
| Download URL | headless_reaper-0.1.0-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 343.9 kB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
ae7fa0d02ee41bcb016a437dc324361586534e9cf19077acf429e4b540aabdc0
|
|
BLAKE2b-256 checksum How to use checksums |
46232233f9896cb82a2c1e1945d5b824544a96e84407a0cfc1c8dff43decba5a
|
| 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.0-py3-none-macosx_10_12_x86_64.whl
| Download URL | headless_reaper-0.1.0-py3-none-macosx_10_12_x86_64.whl |
|---|---|
| Size | 361.2 kB |
| Tags | Python 3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
dfbb8f669e7a1cadbb951e6e02a4d759dce86265028e1945f9b6bc639e59697c
|
|
BLAKE2b-256 checksum How to use checksums |
f7c47c2b862ae8e7d29b7f8103075c8b233d70dfb738b6ce9e0a621c7fad1b6e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
maturin/1.16.0
|
Security for headless-reaper 0.1.0
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.