Skip to main content
plugin

screenshot-janitor — Claude Code plugin: what it does, how to install

screenshot-janitor tracks screenshots taken during a Claude Code session and prompts you to move them to the system Trash before exiting.

MIT ★ 1,013 updated 2026-08-12

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add ccplugins/awesome-claude-code-plugins
/plugin install screenshot-janitor@awesome-claude-code-plugins
Open on GitHub

What screenshot-janitor does

When you share screenshots with Claude, image files rapidly accumulate on your desktop. This plugin sets up a SessionStart hook to log when your terminal session begins, isolating only newly created images. Before exiting, a Stop hook prompts you once to clean them up, though you can also trigger the cleanup manually using /cleanup-screenshots.

Safety is a core constraint: the plugin never invokes rm. Files are routed to the OS Trash through Finder, AppleScript, gio trash, or trash-cli, so accidental removals remain recoverable. The tool relies on standard shell commands like bash and find, requiring neither Python nor jq. Custom directories and filename patterns can be configured in ~/.claude/screenshot-janitor/config.sh.

The plugin runs exclusively on macOS and Linux; Windows environments are unsupported.

What it helps with

  • clear temporary screenshots left on Desktop after Claude sessions
  • move session-specific captures directly to system Trash
  • prevent desktop clutter without deleting images permanently

Example prompts for the agent

  • /cleanup-screenshots
  • Check screenshots created during this session and clean them up
  • Show screenshots taken since this session started

How to install screenshot-janitor

Plugin marketplace

/plugin marketplace add ccplugins/awesome-claude-code-plugins
/plugin install screenshot-janitor@awesome-claude-code-plugins

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about screenshot-janitor

How to install screenshot-janitor in Claude Code?

Run /plugin marketplace add ccplugins/awesome-claude-code-plugins in Claude Code, then run /plugin install screenshot-janitor@awesome-claude-code-plugins. Restart Claude Code or run /hooks to complete setup.

What does screenshot-janitor do?

It tracks screenshots added while your Claude Code session runs and asks to move them into the Trash before you quit.

Can files trashed by screenshot-janitor be recovered?

Yes. The plugin moves files to the standard operating system Trash instead of running rm, allowing full recovery.

Source text

screenshot-janitor · MIT
# 🧹 screenshot-janitor

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-blue)
![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-8A2BE2)
[![GitHub stars](https://img.shields.io/github/stars/MECoban/screenshot-janitor?style=social)](https://github.com/MECoban/screenshot-janitor/stargazers)

A [Claude Code](https://claude.com/claude-code) plugin that keeps your Desktop clean.

You share a lot of screenshots with Claude during a session — and they pile up
forever afterward. **screenshot-janitor** notices the screenshots created during
each session and, before you leave, **asks** whether to move them to the Trash.
Approve, and they're gone (recoverable from the Trash). Decline, and it won't
nag you again.

> Safe by design: it **never** runs `rm`. Files go to the system Trash and can be restored.

## Demo

<!-- Record a short clip of the end-of-session "clean up?" prompt, save it as docs/demo.gif, then uncomment the line below: -->
<!-- ![screenshot-janitor in action](docs/demo.gif) -->

> 🎥 _Demo GIF coming soon._ The end-of-session flow: Claude asks **"move these N screenshots to the Trash?"** → you approve → done.

---

## Install

```text
/plugin marketplace add MECoban/screenshot-janitor
/plugin install screenshot-janitor
```

That's it. The skill **and** the hooks are wired up automatically — no manual
`settings.json` editing. Restart Claude Code (or open `/hooks` once) to activate.

## How it works

| Piece | What it does |
|-------|--------------|
| `SessionStart` hook | Opens a per-session folder and records the start time, so each session only deals with **its own** screenshots. |
| `Stop` hook | If this session created screenshots, reminds you **once** to clean them up before you go. |
| `cleanup-screenshots` skill | Finds the screenshots, shows a clear list (name, size, time), asks for approval, and moves the approved ones to the Trash. |

You can also run it any time:

```text
/cleanup-screenshots
```

## Platforms

- **macOS** — scans `~/Desktop`, recognizes `Screenshot *`, `Ekran Resmi *`,
  `CleanShot *`, etc. Trashes via the `trash` CLI or Finder/AppleScript.
- **Linux** — scans `~/Pictures/Screenshots`, `~/Pictures`, `~/Desktop`,
  recognizes GNOME/KDE naming. Trashes via `gio trash` or `trash-cli`.

Zero runtime dependencies (no `jq`, no Python) — just `bash`, `find`, `stat`.

## Configuration

Don't edit the plugin files (they're overwritten on update). Instead create
`~/.claude/screenshot-janitor/config.sh` and override what you need:

```bash
# Extra folders to scan
SCAN_DIRS=( "$HOME/Desktop" "$HOME/Pictures/Screenshots" )

# Filename globs that count as screenshots
NAME_PATTERNS=( "Screenshot *" "CleanShot *" )

# Don't remind until the session is at least this old (seconds). 0 = remind ASAP.
MIN_AGE_SECONDS=300
```

## State & privacy

Per-session bookkeeping lives in `~/.claude/screenshot-janitor/`. Nothing leaves
your machine. The plugin reads filenames/sizes/timestamps only — never the image
contents.

## Uninstall

```text
/plugin uninstall screenshot-janitor
```

Optionally remove leftover state: `rm -rf ~/.claude/screenshot-janitor`.

## License

MIT © MECoban

© MECoban · MIT · ccplugins/awesome-claude-code-plugins

Similar plugins

All plugins for Automation and no-code: n8n, Zapier, Make →

From the same set184

The whole set →

Project sponsors

Companies that keep this analytics open