Snap Judgment
Your screenshots, reviewed. Snap Judgment reads a folder of screenshots and issues a courtroom-style verdict on your screenshot habits: a tier, the evidence, awards, and a sentence.
Meet the defendants: five synthetic screenshot collections, from The Minimalist (35 screenshots, acquitted) to The Hoarder (2,800, Unrepentant Screenshot Felon), judged and entered into the record. New presiding voices live in judges/, and the version record is kept in the changelog.
Install
pip install snap-judgment
Pure Python standard library. No dependencies, Python 3.9+.
Usage
snapjudgment ~/Pictures/Screenshots
snapjudgment ~/Desktop ~/Pictures --card card.html --out report.md
snapjudgment ~/Pictures --svg card.svg # SVG share card (1200x630)
snapjudgment ~/Pictures --png card.png # PNG share card (1200x630), rendered with the stdlib alone
snapjudgment ~/Pictures --html page.html # full self-contained HTML report
snapjudgment ~/Downloads --all # judge every image in the folder
snapjudgment ~/Pictures --since 2024-01-01 # only screenshots on or after a date (a bare year works too)
snapjudgment ~/Pictures --until 2026-06-30 # only screenshots on or before a date
snapjudgment ~/Pictures --year 2026 # judge one single year only
snapjudgment ~/Pictures --vs ~/Phone # co-defendant mode: compare two folders
snapjudgment ~/Pictures --vs-year 2026 # compare one year against another year in the data
snapjudgment ~/Pictures --judge strict # strict | fair | lenient presiding judge
snapjudgment ~/Pictures --judge-file poet.json # a custom judge voice from a JSON pack
snapjudgment ~/Pictures --intensity roast # court commentary at full roast (0-100 or gentle|kind|honest|spicy|roast)
snapjudgment ~/Pictures --wrapped-kit ./kit # year-scoped SVG card + ready-to-post drafts
snapjudgment ~/Downloads --court downloads # the downloads docket: a second court, for the downloads folder
snapjudgment --grand-jury ~/Pictures/Screenshots ~/Downloads # both courts, one hearing, a combined FULL DOCKET verdict
snapjudgment ~/Downloads --court downloads --recursive # the docket judges subfolders too
snapjudgment ~/Pictures --cleanup-list cleanup.txt # the cleanup order: the exact files a plea bargain would remove
snapjudgment ~/Pictures --plea-bargain # the hypothetical verdict if you deleted the old and the duplicated
snapjudgment ~/Pictures --rematch # compare this hearing with the last one on record
snapjudgment ~/Pictures --badge badge.svg # a shields-style verdict badge for your README
snapjudgment ~/Pictures --fail-above "Repeat Offender" # exit 1 if the verdict ranks above this tier
snapjudgment ~/Pictures --oneline # print exactly one summary line
snapjudgment ~/Pictures --csv files.csv # per-file records as CSV
snapjudgment --history # print the court record of prior hearings
snapjudgment ~/Pictures --json # machine-readable verdict
With no folder argument, Snap Judgment checks the usual places
(~/Pictures/Screenshots, ~/OneDrive/Pictures/Screenshots, ~/Desktop,
~/Pictures, ~/Downloads) and judges the first one that actually
contains screenshots.
The verdict tiers run from Innocent Bystander (under 50 screenshots) up
to Unrepentant Screenshot Felon (2,500+). Along the way the court weighs
the evidence: total count and size, the largest single screenshot, date
span, busiest day, month and hour, night share, weekend share, evidence
retention (how much of the collection is over a year old), screenshots per
day, median per active day, silent months (whole calendar months inside the
span with zero screenshots), longest daily streak, longest clean stretch,
biggest 60-second burst, the busiest hour window (the fullest rolling 60
minutes anywhere in the record), duplicate suspects and the storage they
waste, the per-format share (PNG, JPG, HEIC...), your busiest screenshot
season, your screenshot anniversary (the month-day you shoot most, summed
across years), and the device eras told by your screen resolutions. The
Markdown and HTML reports also draw a screenshot heatmap: the whole
collection as an hour-by-weekday grid. --since and --until narrow the
record to a date range (inclusive, and they compose with --year); the
active filter is entered into the evidence. Files the court cannot
read (broken symlinks, locked files) are counted and reported, never fatal.
With 5 or more screenshots the report also presents exhibits: the five oldest screenshots, entered into evidence as Exhibit A through Exhibit E. When several folders are judged in one run, an evidence block lists each folder with its screenshot count.
With 10 or more screenshots the court also reads the charges: a census of where the screenshots came from, from metadata hints only. Android filenames that carry an app package are credited to that app (WhatsApp, Telegram, Instagram, and friends); everything else is classified by the form factor its dimensions suggest, from Phone (tall) to Desktop / landscape.
Three judges can preside. The fair judge is the default. The strict judge (The Hanging Judge) words the same verdict severely, and the lenient judge (The Sympathetic Judge) frames everything kindly, with encouragement instead of a sentence. The voice changes the wording only, never the math.
Add --intensity and the court appends a line of commentary after the
sentence, aimed at your most damning stat: night share first, then sheer
count, duplicate extras, your longest streak, the oldest evidence. The
intensity runs 0-100 or by name: gentle, kind, honest, spicy, roast. At
gentle the court simply notes that the defendant keeps late hours; at
full roast it finds the sleep schedule guilty too. Commentary is opt-in,
appears in the terminal report, JSON, and the Markdown and HTML reports,
and composes with any judge. Like the judge's voice, it changes the
wording only, never the math. It can also live in the config file as
intensity.
Custom judge packs
--judge-file FILE.json seats a judge of your own. A pack is a JSON object:
{
"name": "The Poet",
"intro": "The Poet presides over {count} screenshots.",
"sentences": {
"Innocent Bystander": "A short poem of a folder."
},
"award_lead": "The court pins these medals:"
}
name is required; intro (which may use {tier} and {count}),
sentences, and award_lead are optional. Any verdict tier missing from
sentences falls back to the fair judge's sentence for that tier. A
complete example, The Poet, ships at examples/judge-poet.json. With
--json, the report's judge field carries the pack's name. A malformed
pack exits with code 2 and a plain message.
A pack may also carry an awards object that renames awards by their
stable keys (night_owl, burst_mode, screenshot_streak, and the
rest; every award in the JSON report now carries its key). Each entry
may override the display name, the evidence line, or both; the
evidence is a template filled with the award's own stat values, so
"{night_count} hoots at {night_share:.1f}%." renders with the real
numbers. Entries keyed by an unknown award are warned about and
ignored. The Critic (judges/judge-critic.json) shows the feature
off: a dry film-critic judge whose Night Owl is entered into the record
as Nocturne in a Minor Key.
Configuration file
Options you reach for every time can live in a .snapjudgment.toml.
Snap Judgment looks for one in the current directory first; when exactly
one folder is given and the current directory has none, a config file
inside that folder applies. Command-line flags always override the file.
# .snapjudgment.toml
folders = ["~/Pictures/Screenshots"]
judge = "strict"
plea_years = 3
fail_above = "Repeat Offender"
all = false
The supported keys are folders (a list of paths, used when no folder
argument is given), judge (strict | fair | lenient),
judge_file (a custom judge pack, as with --judge-file),
plea_years (an integer), fail_above (a verdict tier name),
all (a boolean), intensity (an integer 0-100 or a band name,
as with --intensity), and court (screenshots | downloads). Python 3.11+ parses the file with tomllib; on
3.9/3.10 a small built-in parser reads the same flat subset of TOML
(top-level key = value lines). A config file that cannot be parsed,
names an unknown judge or tier, or points at a judge pack that does not
load is warned about on stderr and ignored as a whole: a config file
must never break a run.
Shell completions
Completion scripts for bash and zsh live in
completions/: they complete every flag, with judge
voices for --judge and verdict tiers for --fail-above. For bash,
copy completions/snapjudgment.bash into your bash-completion
directory (e.g. ~/.local/share/bash-completion/completions/snapjudgment)
or source it from ~/.bashrc. For zsh, copy
completions/snapjudgment.zsh as _snapjudgment into a directory on
your $fpath and run compinit.
Year over year
--vs-year 2026 compares one year against the most recent year present in
the data (or, when the target is the most recent year, against the previous
year present): counts, verdict tiers, night shares, and sizes per year,
plus a closing line noting improvement, relapse, or no change in behavior.
The plea bargain
--plea-bargain asks what a cleanup would buy you, without touching a
single file. The court computes the hypothetical outcome if you deleted
(a) every duplicate suspect except one keeper per exact size-and-dimension
group, and (b) every screenshot older than --plea-years N years
(default 2), measured from the newest screenshot in the folder: how many
files would go, how much space would come back, and what verdict the
remainder would earn. If the projected tier beats the real one, the court
would accept the plea; if not, it notes for the record that the plea
changes nothing. It is a projection, labeled as such - Snap Judgment
never deletes, moves, or modifies anything it judges.
--cleanup-list FILE turns the plea into paperwork: it writes the
exact files the plea bargain would remove (duplicate extras plus
screenshots older than --plea-years), one sorted path per line under
a # header giving the count and bytes, and enters a cleanup_order
object into the JSON report. It needs no --plea-bargain flag, and
when both are given they always agree, because they are the same
computation. The court issues the order; it does not swing the axe
itself. What you do with the list is your business.
The downloads docket
--court downloads convenes a second court for the folder where good
intentions go to be forgotten. It judges the folder given on the
command line, or ~/Downloads when none is given, and it judges
every file on the surface, any type, non-recursively, from names,
sizes, and dates only. No file is ever opened.
The evidence is the downloads folder's own: total files and size,
installers (.exe, .msi, .dmg, .pkg, .deb, .rpm,
.appimage) and archives, duplicate downloads (the setup.exe,
setup (1).exe, setup (2).exe chains, counted by extra copies), the
oldest and largest files, an extension census, and the share of files
over a year old. The verdict tiers are the docket's own:
| Files | Verdict |
|---|---|
| 0 | No Evidence |
| 1-24 | Tidy Desk |
| 25-99 | Mild Clutter |
| 100-249 | Digital Junk Drawer |
| 250-499 | Landfill Adjacent |
| 500-999 | Hoarding Situation |
| 1,000+ | Superfund Site |
Its awards are its own too: Installer Archaeologist (10 or more
installers), Zip Hoarder (15 or more archives), Double
Downloader (5 or more duplicate extra copies), Ancient Relic
(the oldest file is at least 3 years old), Gigabyte Landfill (5 GB
or more in total), Still Seeding (a .torrent file), Receipt
Keeper DX (an invoice or receipt in a filename), and Time
Capsule (60% or more of the files are over a year old). The
terminal report, --json, --out, --oneline, --fail-above
(against the docket's tiers), --judge, --intensity (with
commentary written for downloads sins), the share cards (--card,
--svg, --png, headed THE DOWNLOADS DOCKET), --badge (colored by
the docket's own ladder), the full HTML report (--html),
--rematch against the last downloads hearing, --year,
--wrapped-kit, --csv (one row per file, categorized as installer,
archive, or other), the --since / --until date filters, and the
court record all work in this court. The cleanup order works here
too, listing only the provable waste: the duplicate-download extra
copies, every group member except the keeper. Only the comparisons
(--vs, --vs-year), the plea bargain, and judge packs
(--judge-file) are refused with a plain error, because they belong
to the screenshots court's evidence. A sample hearing is at
examples/downloads-demo-output.txt. --court can also live in the
config file.
--recursive lets the docket judge subfolders too, not just the
surface. The evidence gains a per-folder breakdown (also the
folders list in JSON), and duplicate-download grouping stays
within each containing folder: a setup.exe in two different
folders is not a duplicate chain.
The grand jury
--grand-jury convenes both courts in one hearing: the screenshots
court and the downloads docket, tried together, with a combined
verdict. Pass both folders (screenshots first, downloads second) or
pass neither, in which case the screenshots court looks in the usual
places and the docket sits on ~/Downloads. One folder alone is a
plain error; the grand jury needs both defendants or none.
Each court issues its compact verdict block, and the hearing closes with THE FULL DOCKET: the combined file count and size, both verdicts side by side, and a standing line in the presiding judge's voice, keyed to the pair of severities. Two tidy folders earn an acquittal. Two crime scenes earn the harshest line the judge has. Anything in between is a split verdict, and it names the worse folder as the problem. A court whose folder is missing or empty reports No Evidence, and the combined report still issues for the other; the exit code is 2 only when neither court has evidence.
--judge and --intensity apply to both courts at once, and
--fail-above is resolved per court against that court's own
ladder, tripping if either verdict ranks above the tier. --json
nests each court's usual object under screenshots and downloads
keys, with a combined summary of files, bytes, and both tiers.
--png, --svg, and --card render a FULL DOCKET share card (both
verdicts, the combined size, and the first award from each court),
and --out mirrors the whole hearing in Markdown. Both hearings
enter the court record as normal entries, so each court's
--rematch keeps working afterward. Single-court procedure (the
comparisons, the plea bargain, the cleanup order, the wrapped kit,
date scopes, --history, judge packs, --csv, the badge, and the
HTML report) does not combine with a grand jury and is refused with
a plain error.
Rematch
--rematch tries this hearing against the last one on record for the
same folders: the count delta since that hearing and whether the verdict
has improved, worsened, or held since. With no prior hearing for the
folders, the court says so. In JSON the comparison rides along as a
rematch object (or null when there is nothing to rematch against).
A badge for your README
--badge badge.svg writes a shields-style verdict badge: a dark
"snap judgment" segment and the tier on a segment colored by severity,
green for Innocent Bystander through to dark red for Unrepentant
Screenshot Felon. Post your card, wear your verdict.
The share cards carry the word too: the HTML, SVG, and PNG cards print a
small pip install snap-judgment line under the footer, so anyone who
sees your verdict knows how to get one of their own.
The wrapped kit
--wrapped-kit DIR scopes the hearing to the current year (or to --year
when given) and writes two files into DIR: wrapped-YYYY.svg, the year's
share card, and post.txt with two ready-to-post drafts built only from
the review's own numbers: a short post of at most 280 characters and a
standard post with the verdict, count, size, and top awards. If the year
has no screenshots, nothing is written and the exit code is 2.
Failing a build on a verdict
--fail-above TIER exits 1 when the actual verdict ranks above TIER in the
tier order, and 0 otherwise. Tier names are case-insensitive and accept
spaces or hyphens ("Repeat Offender", repeat-offender). An unknown tier
exits 2 and prints the valid tier list. The report (or JSON) is still
printed first, so the flag drops straight into CI.
One line
--oneline prints exactly one line and nothing else:
Repeat Offender · 310 screenshots · 15.1 MB · Jan 2024 - Nov 2026
Card, CSV, and report files are still written when their flags are given.
With --json, JSON wins and --oneline is ignored. An empty folder prints
No Evidence · 0 screenshots and exits 2.
GitHub Action
Snap Judgment ships as a composite GitHub Action. It installs the package from this repo, judges a folder, and appends the Markdown verdict to the workflow step summary:
- uses: littlestjames82-sys/snap-judgment@v0.5.0
with:
path: ./screenshots
judge: fair # optional: strict | fair | lenient
fail-above: "Repeat Offender" # optional: fail the step above this tier
Inputs: path (required), judge (default fair), fail-above
(optional). The step's exit code is Snap Judgment's own, so fail-above
can fail the step.
Every hearing is entered into the court record at
~/.snap-judgment/history.jsonl. The next time a folder is judged, the
verdict reports the last hearing's count and whether the collection is up
or down since, and --rematch puts the two hearings side by side.
snapjudgment --history prints the full record.
The verdicts
| Screenshots | Verdict |
|---|---|
| 0 | No Evidence |
| 1-49 | Innocent Bystander |
| 50-199 | Petty Offender |
| 200-499 | Repeat Offender |
| 500-999 | Habitual Hoarder |
| 1,000-2,499 | Felony-Level Archivist |
| 2,500+ | Unrepentant Screenshot Felon |
The awards
- Night Owl - a quarter or more of your screenshots happen between 10 PM and 5 AM
- The 3 AM Club - 10 or more screenshots taken between 2 AM and 4 AM
- Burst Mode - 8 or more screenshots inside a single 60-second window
- The Archivist - your oldest screenshot is at least 3 years old
- Receipt Keeper - half or more of your shots are weekday 9-to-5 evidence
- Repeat Customer - 10 or more files are exact size-and-dimension duplicates of a sibling
- Creature of Habit - a quarter or more of your screenshots fall in a single hour of the day
- Gigabyte Club - your screenshots total a gigabyte or more of evidence
- Time Traveler - at least one screenshot is dated in the future; the court admits it anyway
- The Long Haul - the collection spans 4 or more years
- Lifer - the collection spans 8 or more years
- Ancient Relic - the oldest screenshot sits 10 or more years before the newest
- Anniversary - one month-day accounts for 15 or more screenshots across the years
- Screenshot Streak - 7 or more consecutive days with at least one screenshot
- Clean Stretch - 30 or more consecutive days without a single screenshot; a recorded moment of restraint
- Minimalist - under 50 screenshots total; the court's rare acquittal
Sample output
From a synthetic demo folder of 310 screenshots (see examples/ for the
full report, the HTML, SVG, and PNG share cards, a wrapped-kit example, and
the example judge pack):
THE VERDICT
Repeat Offender
310 screenshots, 15.1 MB of evidence,
spanning Jan 5, 2024 to Nov 10, 2026.
THE EVIDENCE
Total screenshots 310
Total size 15.1 MB (15,799,537 bytes)
Taken at night (10 PM-5 AM) 91 (29.4%)
Busiest hour window 12 screenshots in the hour from Aug 14, 2026 21:14
Formats PNG 100%
Screenshot season Summer (Jun-Aug) - 31.0%
Screenshot anniversary Aug 14 - 14 screenshots across 2 years
THE CHARGES
Desktop / landscape 157 (50.6%)
Phone (tall) 153 (49.4%)
EXHIBITS
Exhibit A - Screenshot 2024-01-05 at 17.59.50.png (Jan 5, 2024)
Exhibit B - Screenshot 2024-01-12 at 11.46.18.png (Jan 12, 2024)
Exhibit C - Screenshot 2024-01-17 at 07.08.34.png (Jan 17, 2024)
Exhibit D - Screenshot 2024-01-21 at 22.29.11.png (Jan 21, 2024)
Exhibit E - Screenshot 2024-01-22 at 14.04.37.png (Jan 22, 2024)
AWARDS
* Night Owl - 91 screenshots between 10 PM and 5 AM (29.4% of the total).
* The 3 AM Club - 32 screenshots taken between 2 AM and 4 AM, when nothing on screen can be urgent.
* Burst Mode - 12 screenshots inside a single 60-second window.
* Repeat Customer - 12 files share an exact size and dimensions with a sibling. The same screenshot, taken again.
* Screenshot Streak - 10 consecutive days with at least one screenshot.
THE SENTENCE
Sentence: probation. The screenshots folder gets a check-in once a month.
Privacy
Snap Judgment works from file metadata only. It reads file names, sizes, modification times, and - solely to learn an image's width and height - the header bytes of the image file. It never decodes image pixels, never runs OCR, and never uploads anything anywhere. What your screenshots show is your business; how many there are is the court's.
License
MIT. Copyright Ryan Cotten / Ghost Developer Studio.
Metadata
Release files for snap-judgment 0.11.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 |
|---|---|---|---|---|
| snap_judgment-0.11.0.tar.gz | 92.9 kB | With provenance | Details for snap_judgment-0.11.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| snap_judgment-0.11.0-py3-none-any.whl | Python 3 | none | any | Details for snap_judgment-0.11.0-py3-none-any.whl |
Total release size: 156.2 kB
Release files / snap_judgment-0.11.0.tar.gz
| Download URL | snap_judgment-0.11.0.tar.gz |
|---|---|
| Size | 92.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
86fbb8a52fea94ca583fa1ba4c5fa8a58b9a8bb6210df299fafe0523e9acb248
|
|
BLAKE2b-256 checksum How to use checksums |
830ab43b3120a7358d79c535a5d3851ac42774fd6a0a0e2e460ccba99480d8ad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logRelease files / snap_judgment-0.11.0-py3-none-any.whl
| Download URL | snap_judgment-0.11.0-py3-none-any.whl |
|---|---|
| Size | 63.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b3bdaf7e6c8858a4ef3acbd8b3d32a4a594b324e3dd297c3a5f21d92537daaf4
|
|
BLAKE2b-256 checksum How to use checksums |
0bce95f12996fe0e475dad5059c2ae8df5404e9b44cd239e871f4e653dfae4de
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logSecurity for snap-judgment 0.11.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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for snap_judgment-0.11.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logA 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.