Skip to content
matttPublic

About

Clean up after mise en place: find and safely delete developer caches

Topics

Resources

Stars

172 stars

Watchers

2 watching

Forks

Repository files navigation

Plonge

Developer tools and coding agents fill a disk with caches. Each project gets its own node_modules, .build, DerivedData, target, or .venv, and each agent worktree gets another copy. Or else, package managers squirrel away shared caches in various places.

When the disk is full, you need space now. And that's a bad time to delete folders by hand. That folder that looks disposable? Whoops! That actually had work that hadn't been pushed anywhere yet.

Plonge finds disposable caches around your system for you or your agent to plonge away. In projects, it deletes only directories that match its rules and pass its Git checks. For shared caches, it runs each tool's cleanup command or a specific built-in rule. See What Plonge covers for supported tools and known gaps.

Install

With Homebrew:

brew install mattt/tap/plonge

With mise, through its github or go backend:

mise use -g github:mattt/plonge
mise use -g go:github.com/mattt/plonge/cmd/plonge@latest

With Go 1.26 or later:

go install github.com/mattt/plonge/cmd/plonge@latest

The releases page also has archives for macOS and Linux, on amd64 and arm64.

Project scans need Git on PATH. Global cleanup needs the tool named by each rule. The disk command supports macOS and Linux.

Find caches

plonge scan

scan lists each cache with its size, project, last activity, and rule. A cache is a directory that matches a rule, such as node_modules or .venv. Some rules also require a project file: target, for example, must be beside Cargo.toml or pom.xml. A match enters the totals only if it passes the Git checks described below.

By default, Plonge finds projects from mise's record of the config files it has loaded, so a project appears only after mise has loaded a config file in it. To scan a project that mise has not seen, name it with --root. Add --no-mise to leave out mise's record and scan only the roots you name:

plonge scan --root ~/code/app
plonge scan --no-mise --root .

--root can be repeated, and clean takes both options too. A root must be inside a Git work tree. Plonge skips a root outside one, lists it in the scan and clean reports with the reason, and does not search a parent folder for repositories. The report calls each root a project.

Delete project caches

plonge clean
plonge clean --apply

clean lists the caches that it would delete, and --apply deletes them. Use the same options for both runs. scan and clean both print JSON with --json.

By default, only caches in quiet projects qualify. A quiet project has a known last activity time at least 24 hours old; quiet_hours in your rules file changes that period. Activity is the newest time in the root's Git HEAD log and its Claude Code transcripts. Uncommitted edits and builds do not update it, so a quiet status does not prove that a project is unused. A project with more recent or unknown activity is active. --include-active also selects active projects, and --min-size 100MiB skips caches smaller than 100 MiB. Projects that the agent status check reports as busy stay excluded, even with --include-active, and a failed status check blocks project cleanup. A busy project has a Paseo agent with the status running or initializing. The check fails when paseo is on PATH but paseo ls fails, when it lists an entry that is not an object with a known status (initializing, running, idle, error, or closed), or when a running or initializing agent has no working directory.

Plonge also refuses a cache that a running process uses, such as a .venv that a service runs from, because the HEAD log and transcripts do not show a long-running service. A process uses a cache when it has a file open or a library mapped under it, works in it, runs an executable from it, or names a path in it on its command line. --include-active does not override this check. The report names the process:

Refused ~/code/app/.venv: in use by python3.12 (PID 4312), whose command line names bin/python

On macOS, Plonge runs lsof and ps once for each scan; on Linux, it reads /proc. If it cannot list the processes, every project counts as busy. The check does not see a service that is stopped when Plonge runs, a timer or cron job, or a process that starts after the last check. The rule reference describes what the check can miss.

Before each deletion, Plonge checks again that no process uses the cache, and that the path is still a directory, is not a symlink, is inside its root, is ignored by Git, and contains no tracked files. It also refuses a directory that holds an entry that its rule protects; the Mix _build rule, for example, protects releases and dependency sources. Plonge skips a path that does not pass, or reports an error. Cleanup deletes directories and does not run project code. It continues after a deletion error and exits with a nonzero status.

After --apply, the report gives an estimate of the space freed, from cache sizes, and the measured change in free space on your home directory's volume. Other processes can also change that second number.

An ignored cache can contain a dependency cloned from Git, with commits or edits that the enclosing repository cannot see. Plonge therefore refuses a cache that holds a Git repository at any depth, or a directory that it cannot read. The report lists each refused cache and its reason, outside the totals:

Refused ~/code/app/node_modules: contains a Git repository at some-dep

The one exception is Swift Package Manager. In a .build or DerivedData directory beside Package.swift, or a DerivedData directory beside one Xcode workspace or project, Plonge allows dependency clones that are unchanged and that SwiftPM can make again from Package.resolved. It refuses the directory when a clone has edits, extra commits, or any other repository. The rule reference describes the Git check, the SwiftPM conditions, and project discovery and activity.

Global caches

Package managers keep shared caches outside projects:

plonge scan --global
plonge clean --global
plonge clean --global --apply

scan --global adds global caches to the project report. clean --global lists the cleanup action for each one and leaves projects alone, so it cannot be combined with --root, --no-mise, --include-active, or --min-size. All three run each tool's lookup and check commands.

A prune rule uses the tool's policy to select unused or stale data, as mise cache prune and uv cache prune do. A clear rule can remove cached data that is still in use, so later commands may have to download dependencies or rebuild files. Most prune rules report a size marked (whole cache), of which the tool removes only part. Clear rules run only with --include-clear:

plonge clean --global --include-clear
plonge clean --global --include-clear --apply

Global cleanup does not use project activity, and it can interrupt a build that is using a selected cache. Plonge runs each tool from your home directory, without a shell, so project-specific tool settings may not apply. It uses mise exec -- when mise provides the tool, and PATH otherwise, and it skips and reports a tool that is missing. The mise-tools rule skips cleanup when mise cannot load a tracked config that may still exist, because mise could remove a version that the config pins.

Where a tool has no safe cleanup command, a built-in clear rule deletes the contents of one directory. These rules refuse unsafe paths, such as the home directory, a symlink, or a path in or containing a Git repository, and they protect data that a download cannot restore. For example, the Cargo rule leaves Git checkouts alone, the RubyGems rule leaves Bundler's clones of Git sources alone, the Deno rules leave localStorage and REPL history alone, and the Maven rule refuses a repository with locally installed artifacts. On macOS, a prune rule for Xcode selects only build directories whose workspace no longer exists, and refuses one that holds a Git repository with edits or local commits.

See the rule reference for every global action, its path, and its checks. The coverage table explains tool-specific limits.

Add a rule

Write custom rules to $XDG_CONFIG_HOME/plonge/rules.toml, or ~/.config/plonge/rules.toml by default. For example, to add a cache directory used by your build tool:

names = [".build-cache"]
quiet_hours = 72

[beside]
".build-cache" = ["build.toml"]

This matches .build-cache only beside build.toml and makes the quiet period 72 hours. The directory must still pass every project safety check. Choose only directories that your tools can restore: Git cannot protect edits inside an ignored folder that has no repository of its own. Use refuse_inside to protect files within a cache that a rebuild cannot restore.

names and skip add to the defaults. A beside or refuse_inside entry replaces the default for that name, and a global rule replaces the whole default rule with the same id, including its checks. See the rule reference for the full format and the default rules before you replace an entry.

Disk space

Reported cache sizes estimate the space that cleanup could free. On macOS, Plonge counts only the blocks that a cache does not share with files outside it, so a size can be smaller than what du reports. Files linked elsewhere, snapshots, and concurrent changes can change the space freed, and global size totals can overlap. The rule reference explains how sizes are measured.

plonge disk prints the free space on your home directory's volume:

plonge disk
plonge disk --warn-below 20GiB

With --warn-below, Plonge prints a warning only when free space is below that size. Size and disk errors then go to standard error with exit status 0, so a hook that runs the command does not fail. Sizes accept KiB, MiB, GiB, and TiB (or K, M, G, and T) as powers of 1024, and KB, MB, GB, and TB as powers of 1000.

MCP server

plonge mcp serves scan, clean, and disk to coding agents over standard input and output (stdio). scan takes global. clean is a dry run unless apply: true, and takes include_active, min_size, global, and include_clear with the same rules as the command line. The tools find projects through mise and do not accept roots. Their descriptions tell agents to show the dry run and get your approval before apply. The server does not enforce that approval.

To add the server to Claude Code:

claude mcp add plonge -- plonge mcp

Agent skill

skills/plonge/SKILL.md tells coding agents when to use Plonge, to scan first, to show sizes, and to ask you before clean --apply. To install it for Claude Code, copy skills/plonge to ~/.claude/skills/plonge.

Hooks

This Claude Code SessionStart hook shows the agent a warning when free space is low. Add it to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "plonge disk --warn-below 20GiB"
          }
        ]
      }
    ]
  }
}

Development

The repository pins its tools and defines its tasks in mise.toml.

mise install
mise run check

mise run build writes bin/plonge. mise run lint runs gofmt -l and go vet. mise run test runs the tests with gotestsum. mise run check runs lint and test.

License

This project is available under the MIT license. See the LICENSE file for more info.

About

Clean up after mise en place: find and safely delete developer caches

Topics

Resources

Stars

172 stars

Watchers

2 watching

Forks

Releases

Used by

Contributors

Languages