proc-janitor
AGENTS.md7 starsChanged 9 months agoMITView on GitHub
Homebrew: the formula is NOT pushed from release.yml. The tap (jhlee0409/homebrew-tap) pulls this repo's latest release from its own update-formula.yml, so no cross-repo secret is involved. Do not reintroduce a push-based job — the token it needs expired once and failed five releases in a row unnoticed.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository7 other files it gives its agents.
- .github/AGENTS.mdAGENTS.md
- integrations/AGENTS.mdAGENTS.md
- resources/AGENTS.mdAGENTS.md
- scripts/AGENTS.mdAGENTS.md
- src/AGENTS.mdAGENTS.md
- tests/AGENTS.mdAGENTS.md
- analyzeSkill
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 36
Read CLAUDE.md first for build commands and architecture overview
- Very specific: line 38
All fs2 calls use fully qualified syntax (fs2::FileExt::lock_exclusive(...))
- Very specific: line 39
Never introduce unsafe code or new unwrap() calls.
- Very specific: line 82
Every kill path MUST verify start_time before signalling a PID (PID reuse).
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- Generated: 2026-02-06 -->proc-janitor
Purpose
Rust daemon + CLI that polls the process table to detect and kill orphaned processes (PPID=1) matching configurable regex patterns. Primarily targets macOS with experimental Linux support.
Key Files
| File | Description |
Cargo.toml | Crate manifest (edition 2021, MSRV 1.70+) |
Cargo.lock | Locked dependency versions |
LICENSE | MIT license |
README.md | User-facing documentation |
CLAUDE.md | AI agent instructions (build commands, architecture, design decisions) |
Subdirectories
| Directory | Purpose |
src/ | All Rust source code (see src/AGENTS.md) |
tests/ | Integration tests (see tests/AGENTS.md) |
scripts/ | Installation script (see scripts/AGENTS.md) |
resources/ | macOS LaunchAgent plist (see resources/AGENTS.md) |
integrations/ | Shell/editor integration helpers (see integrations/AGENTS.md) |
.github/ | CI workflows and issue templates (see .github/AGENTS.md) |
Homebrew: the formula is NOT pushed from
release.yml. The tap (jhlee0409/homebrew-tap) pulls this repo's latest release from its ownupdate-formula.yml, so no cross-repo secret is involved. Do not reintroduce a push-based job — the token it needs expired once and failed five releases in a row unnoticed.
For AI Agents
Working In This Directory
- Read
CLAUDE.mdfirst for build commands and architecture overview cargo buildmust succeed beforecargo test(integration tests invoke the binary)- All fs2 calls use fully qualified syntax (
fs2::FileExt::lock_exclusive(...)) - Never introduce
unsafecode or newunwrap()calls. Theunsafehalf is pinned bytest_src_contains_no_unsafe_code; if a change genuinely needs it, update the rule and that test together with the justification rather than adding it quietly
Testing Requirements
cargo build # Must pass first
cargo test # 117 tests (83 unit + 34 integration)
cargo check --target x86_64-unknown-linux-gnu --all-targets # cfg-gated Linux path
cargo clippy --all-targets # Must be warning-free, tests included. Run on an up-to-date `stable`: CI uses
# dtolnay/rust-toolchain@stable, so an older local toolchain
# silently misses lints (e.g. collapsible_match landed in 1.98)
cargo fmt --check # CI enforces formatting
cargo audit # CI fails on advisories; keep the lockfile currentCommon Patterns
- File locking:
set_len(0)+seek(0)+write_all+sync_allunder exclusive lock - Log files: only
proc-janitor.<date>.logis ours; supervisor redirect targets (launchd.*,daemon.*) must never be rotated or deleted - Process table access:
util::process_snapshot()/process_snapshot_for(pid), neverProcessRefreshKind::everything()— it fetches cpu/disk/user/cwd/root/environ that nothing reads - Target/whitelist matching: one function,
scanner::matches_any;visualizemust use it sotreecannot disagree withscan - Color output:
crate::util::use_color()+owo-colors(conditional) - Any process-supplied text (name, cmdline) printed for humans MUST go through
util::sanitize_for_display; a process controls its own argv and can otherwise inject terminal escapes and forge report lines. JSON output must NOT use it — serde escapes, and the value must stay the real command line - Symlink protection:
util::check_not_symlink()before writing predictable paths - Config validation: boundary checks on all numeric values, pinned by the table in
test_validate_boundaries - Regex compilation: always
scanner::compile_pattern, neverRegex::new. Pattern count and length are bounded by the config, but only that helper bounds compiled SIZE — 100 patterns of 39 chars once cost 1.5 GB and 7.5 s per scan - A config that exists but fails to load MUST be fatal for
start.Config::load()already returns empty targets when there is no file, so an Err means user intent that could not be honoured; falling back toConfig::default()substitutes the built-in kill patterns - Config path: always
config::config_path(), which honours$PROC_JANITOR_CONFIG; never rebuild the path inline - MSRV is a tested claim, not a preference: never lower it by pinning a dependency back without checking
cargo auditfirst
Key Design Decisions
scan= detection only (never kills),clean= execution (always kills, with optional filters)- Scanner is stateful in daemon mode (grace period tracking), stateless in CLI mode. Config reload MUST go through
Scanner::reconfigure— replacing theScannerdropstracked/first_seenand restarts every orphan's grace period - Two-phase kill: SIGTERM with 100ms polling, then SIGKILL after timeout
- Every kill path MUST verify
start_timebefore signalling a PID (PID reuse);exec::signal_treeandkill::kill_process_with_sysboth do daemon/clean= cleanup after the fact (pattern-based);exec= prevention (parent-death link, no patterns)- The scan interval bounds discovery only; reacting to orphaning is event-driven (
watch::ExitWaiter, kqueue NOTE_EXIT). Never reintroduce a plainthread::sleepin the daemon loop - kqueue registration and waiting MUST be one
keventcall: a separate registration call returns already-pending events in its own eventlist and silently drops them - Background daemonization stays on the
daemonizecrate even though it is unmaintained (RUSTSEC-2025-0069): hand-rolling it needsnix::unistd::fork, which isunsafe fn, so a replacement would trade a warning for a rule violation. The dependency-free option is to drop background mode entirely — every documented path (plist, systemd unit, brew services) already uses--foreground— but that changesstart's behaviour and is a product decision - Session subsystem is independent with its own JSON persistence + file locking
session clean: explicitly tracked PIDs are killed unfiltered (naming a PID is consent); with nothing tracked it falls back to the parent's descendants filtered by target/whitelist patterns. The fallback MUST stay pattern-gated — unfiltered it would kill every process in the terminal and bypass the safety model
Dependencies
External (key crates)
sysinfo- Process table accessclap+clap_complete- CLI parsing and shell completionsregex- Target/whitelist pattern matchingserde+serde_json+toml- Serializationnix- Unix signal handlingfs2- Cross-platform file lockinganyhow- Error handlingtracing+tracing-subscriber- Structured loggingowo-colors+supports-color- Conditional terminal colorsindicatif- Progress spinners
<!-- MANUAL: -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

