Documentation
TinyPrune docs:
set up file lifetimes.
TinyPrune is a local macOS app that moves expired files and folders to Trash using rules you choose. Choose the folders it can manage, give disposable files a lifetime, and check the results in Preview before enabling cleanup.
This guide covers the Swift macOS app, Finder extension, and CLI. macOS is the only supported product and public release focus while it stabilizes. Version 0.2.3 is the latest published macOS release, an ad-hoc signed, not notarized GitHub prerelease. Windows and Linux development is paused; neither is offered for new public installs. See release status. Plain-text facts and documentation links are available for readers and tools; the full guide below is readable without JavaScript.
Install
Current early releases are not Developer ID signed or notarized. macOS asks you to approve a direct download on first launch; see below. Check GitHub Releases for the latest version and release notes.
Download or use Homebrew
Install with Homebrew:
brew install --cask navig-me/tap/tinyprune
Homebrew installs 0.2.3 (build 26). The public cask points to the published 0.2.3 DMG. The direct macOS download is also available.
Or download the DMG from GitHub Releases and move TinyPrune to Applications. The Homebrew cask clears the quarantine flag for you; for a direct download, approve it as follows.
Early builds are unsigned. On first launch, use System Settings > Privacy & Security > Open Anyway. Only open a build you trust. Alternatively, if you installed it in Applications:
xattr -dr com.apple.quarantine /Applications/TinyPrune.app
Open TinyPrune
Homebrew puts TinyPrune.app in your Applications folder. Open it from Launchpad or Spotlight, or run:
open /Applications/TinyPrune.app
TinyPrune lives in the menu bar and in its own window. If you have other copies of the app on your Mac, such as a build folder or Downloads, open the one in Applications so macOS finds the background helper.
First run
- Click Install background agent, then approve TinyPrune in System Settings > General > Login Items & Extensions. The agent does the scheduling; the app is only the window.
- Choose a folder you control and add a template. Set the rule to Preview before enabling cleanup; developer and cache templates start there automatically.
- Review Upcoming, then switch the rule to Active when you are happy.
Build from source
With Apple's Swift development tools installed, run:
git clone https://github.com/navig-me/tinyprune && cd tinyprune && swift Scripts/package-app.swift && open .build/package/TinyPrune.app
Open the app, choose a folder you control, and add a template or your own rule. Start in Preview and review Upcoming before enabling cleanup.
What TinyPrune can change
TinyPrune only manages folders you choose. It reads filesystem metadata for normal operation, not file contents, and does not need an account or cloud service.
Items go to Trash
TinyPrune never permanently deletes files. Eligible items move to macOS Trash.
Keep wins
Keep overrides every expiry rule. A folder cannot be trashed if it contains a protected item.
Before each move, the agent checks the item's identity, current rules, protection, deadline, pause state, permissions, and volume availability again, confirms the item still lives inside a managed folder (not behind a symlinked ancestor), and re-reads the policy immediately before the Trash call. The index schedules work; it does not authorize a move. If a check cannot be completed (for example cleanup is paused, a Preview rule is involved, or the deadline moved), the item is deferred and retried rather than dropped; items that are gone, replaced, kept, or outside managed folders are skipped for good.
Very broad folders
Folders such as your home folder, /Users, /Volumes, /private, or a whole volume can be managed, but their rules are Preview-only: TinyPrune will not enable cleanup on them, and the agent rejects an Active rule with that scope. Dangerous system roots are refused outright, compared case-insensitively after resolving symlinks.
Pause and settings
Pause cleanup globally, for a managed folder, or for a rule. A timed global pause resumes when its time is up. In Settings, you can set the default grace period, protect hidden files, and choose how long to retain activity history. These settings apply to the app, Finder, and CLI.
Activity and restoring items
Activity summarizes only the loaded audit events: items moved to Trash, items skipped for safety, and the last recorded cleanup time. Each move offers Show in Trash to reveal its recorded destination in Finder. Exact original and Trash paths are copyable. If the destination no longer exists, the row says No longer in Trash.
To restore, use Finder’s Put Back in Trash, if available. Items stay in the Trash until you or macOS empty it; TinyPrune does not restore items or empty Trash. Once an item leaves Trash, the audit event does not guarantee it can be recovered.
Exporting and importing rule configuration
In Settings, use Export rule config… and Import rules…. Export is not a complete backup: the restricted YAML format supports only expressible rules shared by every managed root, plus Keep overrides. Export reports how many rules were exported or skipped and lists skipped names and reasons; a partial or zero-rule export requires confirmation. The saved file also lists omissions in comments.
Import opens a review before applying additions, changes, and removals through the agent. Matching configuration-created rules can change, and absent configuration-created rules within the file’s roots can be removed; app-created rules are kept. Surviving app-created rules can therefore gain configuration copies when imported. Folder access must already be granted. New rules start in Preview; existing configuration rules retain their state. A lossless per-root backup format is not currently supported.
Choose what expires and when
A rule specifies a folder, the files or folders to match, and the time basis for expiry. For example, you can target dependencies in inactive projects without expiring the source folder itself.
Old Node modules
Preview- Where
- ~/Developer/**
- What
- Folder named node_modules
- When
- Project inactive for 30 days
- Action
- Move the folder to Trash
Match by exact name or glob, item type, and scope depth. A glob without a / matches the item's name at any depth, like a .gitignore line (*.dmg matches a/b/c.dmg); a glob containing / matches the path relative to the folder, and ** crosses directories. Only *, ?, and ** are supported; there are no character classes, braces, or ! negation. Exact names always match the item's name. Expiry can use age, modification time, or project inactivity. Set an explicit expiry on an individual item, use Keep to protect it, or choose Inherit to return it to the folder's rules.
Keep follows the item by identity and, if the item was renamed or its identity cannot be matched, by its recorded path as well, so it fails toward protection. A Keep on a folder with protect descendants covers everything below it, and a folder is never trashed while any protected item is inside it.
Every decision includes an explanation: the matching rule, time basis, resolved deadline, project context when relevant, any override, and why an item is protected or skipped.
Check the matches before cleanup
A rule saved in Preview runs matching and scheduling without moving anything to Trash. Upcoming shows indexed candidates and their explanations.
Overview totals count all published Active and Preview schedules, not just the visible sample. Upcoming filters by rule and mode before paging; use Load more to review the remaining items. Size estimates remain bounded metadata samples rather than exact totals for every scheduled folder.
- Choose a managed folder and create a rule.
- Use Preview matches in the rule editor for a read-only dry run. It is bounded and cancellable, and does not save changes or trash items.
- Review the matches, deadlines, and explanations. Add Keep or expiry overrides where needed.
- Enable the rule only when the result matches what you want.
Preview counts only what cleanup would actually act on: items that would be skipped (a protected descendant, an unsupported folder action, or an item nested inside an already matched folder) are excluded, and only the top-most match is listed.
The Rules screen also shows scheduled matches and how many are already eligible. A newly saved rule needs time to be indexed. While indexing or when a folder is unavailable, counts can reflect the last published schedules; successful reconciliation replaces them together. Cleanup waits for available folders and completed wake-event replay, then rechecks each candidate before moving it.
First-observed lifetimes survive renames and restarts for the same filesystem identity. Inactivity deadlines can still change after genuine meaningful activity or rule edits; replaying an old event does not restart the timer at replay time. Git bookkeeping and generated dependency changes do not count as meaningful project activity.
Start with a template
Templates create ordinary rules you can edit, pause, duplicate, or delete. Pick a folder and adjust the match and lifetime to suit the files you actually keep there.
| Template | Use it for |
|---|---|
| Downloads | Top-level items only (not subfolders' contents): DMG files after 7 days, ZIP files after 14, other items after 30 days in the folder |
| Screenshots | Screenshot and Screen Shot filenames, 7 days after creation |
| Temporary Workspace | Disposable top-level items in a chosen folder, 3 days after first observation by default |
| Developer Cleanup | Dependencies and build output in inactive projects; Python caches after 7 days without modification |
| Build Artifacts | dist, build, target, coverage and .cache folders after 30 days of project inactivity |
| Xcode Derived Data | ~/Library/Developer/Xcode/DerivedData: immediate child folders, 60 days without modification |
| Xcode Device Support | ~/Library/Developer/Xcode/iOS DeviceSupport: immediate child folders, 180 days without modification |
| Homebrew Downloads | ~/Library/Caches/Homebrew/downloads: completed hash-prefixed tar.gz, tar.xz, tar.bz2, ZIP, DMG and PKG files, 90 days without modification; incomplete downloads excluded |
| npm Cache | ~/.npm/_cacache: package cache files, 90 days without modification |
| Yarn Classic Cache | ~/Library/Caches/Yarn: Yarn 1 cache files, 90 days without modification |
| pip Cache | ~/Library/Caches/pip: HTTP and wheel cache files, 90 days without modification |
| Cargo Registry Cache | ~/.cargo/registry/cache: .crate files only, 90 days without modification |
| Gradle Caches | ~/.gradle/caches: cache files only, 90 days without modification |
| AI Agent Session Logs | ~/.claude/projects (suggested; choose your tool's folder): transcript .jsonl files, 60 days without modification |
| AI Agent Edit Backups | ~/.claude/file-history (suggested): per-session backup files, 30 days without modification |
| AI Agent Debug Logs | A folder you choose: .log and .trace files, 14 days without modification |
Developer and app-cache templates always start in Preview, as do very broad folders such as your home folder. Paths above are defaults, not discovery: choose and authorize the actual cache folder, especially if you changed a tool's configuration. The whole Library folder cannot be managed; specific cache subfolders can.
Caches are rebuilt or downloaded by their owning tool, not by TinyPrune. Removing them can slow builds and break offline installs until packages are downloaded again. Close the owning app and stop builds before enabling cleanup. Modification age does not prove that a cache is unused. Xcode regenerates Derived Data on a build; device symbols require reconnecting the matching device and can be needed to symbolicate older crashes.
No presets are provided for Xcode Archives (release builds and dSYMs), Docker data (volumes and containers), Zoom recordings in ~/Documents/Zoom, screen recordings, or chat downloads: these may be irreplaceable user documents. Teams and Meet exports have no stable local export folder. Slack, Discord and Telegram download locations are configurable or shared with Downloads. Use a deliberately chosen disposable folder and review individual files instead. pnpm's store varies by configuration, volume and version and may contain a database and global virtual store; use pnpm store prune rather than a generic age rule. Yarn 2+ project caches may be checked into source control and are excluded.
Path and recovery references: Xcode folders, Homebrew cache, Homebrew completed downloads, npm cache, Yarn 1 recovery, Yarn macOS path, pip cache, Cargo home, Gradle caches, pnpm store layout.
Use the Finder menu
Enable the TinyPrune Finder extension in System Settings. The menu works inside folders you have chosen to manage.
From Finder, you can Keep an item, set its expiry to tonight, tomorrow, 7 days, 30 days, or a custom date, return it to inherited rules, and ask why it will expire. Folders also offer Protect Folder, Set Folder Lifetime, and Create Rule.
Finder sends actions to the same background agent as the app and CLI. Folder lifetime, rule creation, and custom expiry open the app to finish the action and require a single selected item. Keep, expiry presets, and inherited rules can act on multiple selected items, applied in one batch.
Work from the command line
The tinyprune command talks to the background agent; it does not run a separate cleanup engine. Use it to inspect upcoming items, set overrides, or pause cleanup.
tinyprune status
tinyprune rules
tinyprune upcoming --json
tinyprune activity
tinyprune keep invoice.pdf --descendants
tinyprune expire video.mov 7d
tinyprune inherit foo.zip
tinyprune why node_modules
tinyprune pause
tinyprune resume
Expiry values also accept 12h, 30m, tonight (23:59 today, or 23:59 tomorrow if it is already past 23:59), and tomorrow. Add --json for structured output; each document carries schemaVersion: 1, and errors are JSON too. Unknown flags and extra arguments are usage errors, and swapped expire <path> <when> arguments are detected.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 64 | Usage error (bad flag, missing or extra argument) |
| 65 | Invalid data, such as a bad date, path, or config file |
| 69 | Background agent unavailable |
| 70 | The agent reported an error |
| 78 | Config roots are not inside a managed folder; add them in the app first |
| 75 | Timed out, interrupted, or busy. The request may have been applied; check with tinyprune status before retrying |
Manage rules as code
tinyprune config validate tinyprune.yml
tinyprune config preview tinyprune.yml
tinyprune config apply tinyprune.yml
tinyprune config export
Config uses a restricted YAML format. validate checks it locally, preview compares it with current rules, apply saves the changes, and export writes the current configuration.
Apply only works inside folders already managed in the app, because the app must obtain folder access. Rules created from a config start in Preview unless you pass --active. Apply keeps the current pause state and Keep overrides; if the policy changed while you were applying, the CLI reloads and retries, then reports a conflict.
How updates work
Direct-download builds with a configured Ed25519 public key use Sparkle, including ad-hoc builds without an Apple account. Use Check for Updates… in the application menu. Sparkle verifies EdDSA-signed feeds, release notes, and downloaded updates. Automatic checks follow Check for new versions in Settings, on by default. Update Now opens Sparkle's native confirmation dialog; installation is never automatic.
Homebrew never constructs Sparkle. Homebrew and direct copies without a public key instead use a daily github.com release check, controlled by the same setting. A banner offers Download (direct) or Copy Upgrade Command (brew upgrade --cask tinyprune, Homebrew), plus Release Notes, Skip This Version and Later. This fallback downloads or installs nothing automatically and visibly explains why in-app installation is unavailable. No identifiers are sent.
Pruning stops while a downloadable update is pending. An update cannot interrupt an in-flight Trash operation. If a downloaded update is interrupted, resume it with Check for Updates or manually install and launch its intended key-enabled direct target. Matching-target recovery also works for ad-hoc direct builds and reconciles an already-enabled background agent; an old-app launch, wrong target or failed recovery never silently resumes pruning. Homebrew/no-key copies cannot clear or resume the pending marker. The menu offers Update Safety Status… while an update is blocking cleanup.
EdDSA update authentication does not notarize the app or change first-install Gatekeeper approval. Sparkle replacements are expected not to carry browser-download quarantine, but end-to-end installation remains unverified. Developer ID signing and notarization are not available in current early builds. The update trust decision documents private-key loss/rotation and the remaining acceptance work.
For implementation details, read the contributor guide and release plan. Report problems or suggest improvements on GitHub.
Release status
The latest published macOS release is 0.2.3 (build 26), published on 2026-10-22 and requiring macOS 14 or later on Intel or Apple silicon. It is an ad-hoc signed GitHub prerelease, without Developer ID signing or notarization. Windows and Linux development and new public releases are paused while macOS stabilizes.
0.2.3 adds Settings version/update controls, contextual AI-agent template suggestions, reduced navigation refresh/dashboard work, and website privacy/FAQ updates. A real Homebrew upgrade from 0.2.2 recovered to an available agent after one first-spawn termination by macOS before main (Code Signature Invalid / Launch Constraint Violation). The exact constraint and cause remain unproven; no mitigation shipped. If 0.2.1 crashes on launch, run brew upgrade --cask tinyprune; 0.2.2 fixed that separate app crash.
The live macOS Sparkle feed publishes 0.2.3 (build 26), retaining builds 25, 24, 23 and 22. Protected public verification checked the live XML, release notes and DMG hash/signature with the existing key. This verifies publication and authentication, not production update installation.
Still pending: a production Sparkle in-app install, the new Settings Check for Updates button exercised in the shipped app, Developer ID/notarization, and repeated upgrade/restart stability. The release log and plan record evidence and remaining validation. Maintainers follow the release runbook.
Platform scope
macOS is the only supported product and public release focus. Windows and Linux development is paused while macOS stabilizes; neither is offered for new public installs. Historical unsigned Rust previews are not recommended public installs. Their immutable assets and existing signed update feed remain intact for installed preview users; the signing key is unchanged.
The Rust implementation has recorded CI/container evidence, not general desktop acceptance. The Rust workspace status matrix preserves detailed environments and remaining platform limits. Historical release evidence remains in the release log.
Prune AI agent clutter
Coding agents and LLM tools are generous with disk space. In a week of debugging they can leave behind scratch projects, cloned repositories, git worktrees, virtual environments, node_modules, build output and long logs. Left alone, that adds up to gigabytes you never chose to keep. Lifetime rules let you clean up once in a while without a cleanup day and without touching what matters.
- Give agents one place to work. Create a folder such as
~/agent-scratchand tell your tools to use it for throwaway work. Add it as a managed folder and apply the Temporary Workspace template: disposable top-level items are scheduled 3 days after first observation by default. Raise the lifetime if your sessions run longer. - Expire what can be rebuilt. On your projects folder, apply Developer Cleanup and Build Artifacts. Dependencies and build output (
node_modules,.venv,dist,build,target) expire only after the project has been inactive, and your source folders are not matched. - Trim debug logs. Apply the AI Agent Debug Logs template to the folder where your tools write logs:
.logand.tracefiles expire after 14 days without modification. Or write your own rule with a different pattern or age. A glob without a/matches at any depth below the folder. - Prune what agents keep about themselves. Coding agents store transcripts and undo backups in their own folders. Claude Code, for example, keeps them in
~/.claude/projectsand~/.claude/file-history. The AI Agent Session Logs and AI Agent Edit Backups templates suggest those folders (60 and 30 days without modification). Check where your tool keeps its data and choose that folder. Expired transcripts can no longer be resumed or searched, so Preview first. - Preview, then enable. Use Preview matches on each rule, add Keep to anything worth saving, and switch the rule to Active only when the list is what you expect.
- Check in occasionally. Upcoming shows what is next and Overview shows what has moved to Trash. Items stay in the Trash until you or macOS empty it, so disk space returns only when you empty the Trash.
A git worktree can hold uncommitted changes, and age alone does not prove it is abandoned. Preview first and Keep the ones you need. After a worktree folder is moved to Trash, run git worktree prune in the main repository to clear its stale record.
TinyPrune does not detect which tool created a file, and it never inspects file contents. It acts on the location, name, age and project inactivity you chose, always moves items to Trash instead of deleting them permanently, and rechecks Keep, rules and deadlines immediately before every move.
Frequently asked questions
What is TinyPrune?
TinyPrune is a local macOS app that gives files and folders a lifetime. You choose folders and rules, and when an item expires TinyPrune moves it to the Trash.
Does TinyPrune permanently delete files?
No. TinyPrune only moves items to the macOS Trash. It does not delete anything permanently.
How is TinyPrune different from a Mac cleaner app?
TinyPrune is not a system optimizer. It only touches folders you choose, follows rules you write, explains every decision, and lets you test a rule in Preview first.
Can TinyPrune clean node_modules and other developer folders?
Yes. Rules can match folders such as node_modules or .venv and expire them after a project has been inactive. Developer templates always start in Preview.
Does TinyPrune need an account or network access?
The app has no telemetry and needs no account. Core cleanup reads filesystem metadata only, does not inspect file contents, and does not require network access. Key-enabled direct-download builds, including ad-hoc builds, check their EdDSA-authenticated update feed over HTTPS. Homebrew and no-key copies ask github.com once a day for a newer release and offer a download link or the brew upgrade command. Check for new versions is on by default and can be turned off in Settings; installation always requires user confirmation. The tinyprune.com marketing website, separately, uses Google Analytics and PostHog.
How do I keep a file from being removed?
Mark it Keep from the Finder menu or run tinyprune keep. Keep takes precedence over every rule, and a folder with a kept item inside is never trashed.
Does TinyPrune work on Intel and Apple silicon, and which macOS versions?
It requires macOS 14 or later. Releases are universal binaries for Intel and Apple silicon.
Is TinyPrune available for Linux or Windows?
Not for new public installs. macOS is the only supported product and public release focus. Windows and Linux development is paused while macOS stabilizes. Historical preview assets and their signed update feed are preserved for existing preview users, not recommended for new installs. See platform scope.
How do I install TinyPrune?
Run brew install --cask navig-me/tap/tinyprune, or download the DMG from GitHub Releases. You can also build from source; see Install for details.
How do I clean up after AI coding agents and LLM tools?
Agents create scratch projects, git worktrees, virtual environments, build output and logs faster than you remove them. Give one disposable folder to the agents, apply the Temporary Workspace template there, add Developer Cleanup or Build Artifacts to your projects folder, and review everything in Preview first. See Prune AI agent clutter.
Does TinyPrune know which files an AI agent created?
No. TinyPrune reads only filesystem metadata and does not identify the tool that wrote a file. Rules work on where an item lives, its name, its age and project inactivity, so point agents at a folder you chose and put the rule on that folder.