Documentation

Complete reference for asshole-gc v1.0.0.

Installation

Homebrew (macOS/Linux)

brew install asshole-gc

Cargo

cargo install asshole-gc

npm

npm install -g asshole-gc

Install script

curl -fsSL # coming soon | sh

Quick Start

Three commands cover 90% of use cases:

asshole-gc --dry-run

asshole-gc --run --grace-period

asshole-gc --schedule "0 9 * * 0"  # Every Sunday 9am

Configuration

Global config lives at ~/.config/asshole-gc/config.toml. Per-environment config can be placed in .asshole-gc.toml in any directory.

[defaults]
threshold       = 3        # consecutive bad days before flagging
day_threshold   = 0.55     # BSA score to count a day as "bad"
reset_threshold = 0.30     # BSA score required to reset the counter
window_hours    = 72       # signal rolling window
grace_days      = 7        # grace period duration
confidence_min  = 0.70     # minimum confidence to flag

[contexts]
# Reduce signal weight during known stress events
deadline_factor = 0.70
personal_factor = 0.40

[output]
color           = true
format          = "human"  # human | json | csv

--dry-run

Scans the environment, runs the full detection pipeline, and prints the candidate list with evidence — but makes no changes. Always run this before --run.

asshole-gc --dry-run [--format json] [--threshold N]

Output columns:

• Name — subject identifier
• Consecutive days — current streak
• Confidence — BSA confidence score (0–100%)
• Top signal — highest-weighted dimension this period
• Priority — HIGH / REVIEW / MONITOR

--run

Executes collection on all subjects above threshold and confidence minimum. Irreversible without manual reinstatement. Use --grace-period to send a warning first.

asshole-gc --run [--grace-period] [--target NAME]

--threshold N

Sets the consecutive bad days threshold. Default: 3.

--grace-period

Sends a notification to the flagged subject before executing collection. The grace period is 7 days by default. During the grace period, behavior is still monitored. Genuine improvement clears the flag.

asshole-gc --run --grace-period [--grace-days N]

Grace period notifications are honest and direct. They do not hedge. The system will not generate a notification that begins with "I feel like..."

--schedule CRON

Installs a cron job that runs asshole-gc --dry-run on the specified schedule and emails you the results. Requires output config (email or webhook).

# Every Sunday at 9am
asshole-gc --schedule "0 9 * * 0"

# First of every month
asshole-gc --schedule "0 8 1 * *"

status [NAME]

Shows current monitoring status for all tracked subjects, or a specific one.

asshole-gc status
asshole-gc status "Dave"

clear NAME

Manually clears a subject's flag and resets their counter. Use when you've verified a false positive or accepted an adequate apology. No judgment.

asshole-gc clear "Casey"

Philosophy

"Not every bug is worth fixing. Some you just remove from the codebase."

asshole-gc is built on a few core beliefs:

• People's time and energy are finite. Chronic toxicity is a resource drain.
• Most people know who the problem is. They just needed someone to confirm it.
• One bad day is noise. Three in a row is a choice.
• Removal without reflection is waste. Use the dry run.
• The grace period exists because people are redeemable. Use it liberally.

False Positives

The algorithm is conservative by design. But false positives happen. Common causes:

• Undetected personal crisis (update context config)
• You're the problem (the mirroring check helps, but isn't perfect)
• Deadline artifacts (set a deadline context window)
• Single-source signals (get a second opinion)

If a collection turns out to be a false positive, use asshole-gc clear and consider a reinstantiation. The tool does not hold grudges on your behalf. That part's up to you.

Ethics & Limits

asshole-gc is a decision-support tool, not a decision-making tool. It surfaces patterns and confirms what you already feel. The decision is always yours.

Things asshole-gc will not do:

• Act without a dry-run review path
• Automate collection without human confirmation
• Process signals from private communications without consent
• Generate a confidence score above 100% (tempting as it is)

The tool is not a replacement for conversation, therapy, or HR. It is a replacement for the mental overhead of tracking patterns you already know exist.