Thanks for considering a contribution! reclaim is a tool that deletes
files, so the bar for changes is higher than usual. This guide explains how
to propose changes safely.
- Ways to contribute
- Project layout
- Local development
- Adding a cleanup rule (no code required)
- Code changes
- Testing requirements
- Pull request checklist
- Reporting bugs
- Reporting security issues
- Style guide
- Releases
The most useful contributions, in roughly increasing order of effort:
- Report a bug with a minimal repro and your
--version. - Suggest a new cleanup target — open an issue with the path, what writes to it, what regenerates it, and proof it's safe to delete.
- Submit a YAML rule for a tool we don't cover (this is the easiest code-free contribution — see below).
- Improve docs — typos, missing keybindings, clearer explanations.
- Fix a bug with a test that reproduces it.
- Add a feature from the Roadmap — please open an issue to discuss first so we don't duplicate work.
We don't accept:
- Rules that delete user data outside conventional cache locations (browser profiles, mail archives, photos, Downloads).
- Rules that auto-run shell commands a user hasn't seen (e.g.
rm -rfviacmd:). Shell rules are reserved for vendor-supplied cleaners (brew cleanup,npm cache clean). - Telemetry or any kind of "phone home."
reclaim/
├── main.go # CLI entry point + argument parsing
├── internal/
│ ├── rules/ # YAML loader + types (catalog embedded at build)
│ │ ├── catalog.yaml # ★ The cleanup rule catalog ★
│ │ ├── load.go
│ │ └── types.go
│ ├── scanner/ # Filesystem walking + git staleness
│ │ ├── scanner.go # Path resolution, dir size, pattern matching
│ │ ├── git.go # Last-commit detection
│ │ └── *_test.go
│ ├── engine/ # Apply / delete / safety
│ │ ├── engine.go # Apply() entrypoint
│ │ ├── safety.go # CheckPathSafe — refuses unsafe paths
│ │ ├── log.go # ~/.reclaim/logs/ JSONL writer
│ │ └── *_test.go
│ └── ui/ # Bubble Tea TUI
│ └── tui.go
├── packaging/
│ └── homebrew/reclaim.rb # Homebrew formula template
├── .github/workflows/
│ ├── ci.yml # vet + build + test
│ └── release.yml # tag → cross-compiled tarballs + GitHub Release
└── go.mod / go.sum
Prereqs: Go 1.21+ and a Mac (Linux works for most things, but the catalog targets macOS paths).
git clone https://github.com/ImadRashid/reclaim
cd reclaim
go build -o reclaim . # produces ./reclaim
./reclaim --version
./reclaim --plain # see what it found, without deleting
./reclaim # interactive TUI
# Run tests
go test ./...
go test -race ./... # catch concurrency issues
# Run vet (CI does this too)
go vet ./...
# Build for another platform
GOOS=linux GOARCH=arm64 go build -o reclaim-linux-arm64 .This is the most common contribution and does not require Go knowledge.
Open internal/rules/catalog.yaml and add an entry. Two shapes:
For caches that always live at the same path:
- id: my-tool-cache
category: package-caches # see "categories:" at top of file
paths:
- ~/Library/Caches/my-tool # ~ is expanded; multiple paths allowed
safety: safe # safe | confirm | dangerous
regenerates: true # true means it auto-rebuilds; tell users
description: My tool's download cache. Re-downloads on next use.
detect: dir-exists # only consider it if the dir existsFor per-project caches discovered by walking the filesystem:
- id: my-project-cache
category: project-caches
scan_for: .my-cache # directory name to look for
scan_root: ~/Desktop/Projects # where to start walking
scan_max_depth: 5 # don't recurse forever
path_contains: src # OPTIONAL: substring match on full path
requires_sibling: package.json # OPTIONAL: only match if a sibling file exists
safety: safe
regenerates: true
description: Per-project My-tool build cache
detect: scanFor tools that have their own cleanup command (rare; needs review):
- id: docker-system-prune
category: container-caches
safety: confirm
regenerates: true
description: Run `docker system prune` to drop dangling images and build cache.
detect: command
detect_command: "docker info >/dev/null 2>&1" # only show if daemon responds
action: shell
action_command: "docker system prune -f --filter until=720h"(The older single-field form — cmd: xcrun simctl delete unavailable with
detect: command — still works, but new rules should use
detect_command + action: shell so visibility and action are explicit.)
| Field | Type | Required | Notes |
|---|---|---|---|
id |
string | ✓ | Unique within catalog. kebab-case. |
category |
string | ✓ | Must match one of the categories: at top of file. |
paths |
[]string | for dir-exists |
Absolute paths or ~/... |
scan_for |
string | for scan |
Directory basename, or a|b for alternatives |
scan_root |
string | for scan |
Root of the walk |
scan_max_depth |
int | Default 5 | |
path_contains |
string | Restrict matches to paths containing this substring | |
requires_sibling |
string | Match only if this file/dir exists in the same parent | |
safety |
enum | ✓ | safe | confirm | dangerous |
regenerates |
bool | True if the path is recreated by normal use | |
cmd |
string | for command |
Shell command, only for vendor cleaners (legacy; prefer action: shell) |
description |
string | ✓ | One sentence; first 60 chars are shown in plain mode |
detect |
enum | ✓ | dir-exists | scan | command |
detect_command |
string | With detect: command — rule is only shown if this probe exits 0 |
|
action |
enum | remove (default, deletes matched paths) | shell (runs action_command) |
|
action_command |
string | for action: shell |
Vendor cleanup command; stdout/stderr shown to the user |
warn_if_running |
[]string | Skip deletion if any of these processes is running | |
activity_check |
bool | If true, scanner annotates hits with git staleness | |
process_check |
string | Skip the rule's hits if this process is running |
safeis for paths that regenerate automatically with zero user-visible loss. Build caches, package downloads, browser asset caches.confirmis for things a thoughtful user might want to inspect first. Examples:node_modules(regenerates but takes minutes), Trash, virtualenvs.dangerousis anything that loses real data: profiles, archives, history, mail, anything inDocuments/Desktop/Downloads.
When in doubt, use a more conservative tier. We'd rather miss a few MB than delete something a user wanted.
- Branch off
main. Use a descriptive name:add-deno-cache,fix-tui-scroll. - Keep PRs focused. One feature/fix per PR. Big PRs are hard to review.
- New rule →
internal/rules/catalog.yamlonly. No Go changes needed. - New rule field →
internal/rules/types.gofirst, then wire it intoscannerand/orengineas appropriate. - TUI tweak →
internal/ui/tui.go. - New CLI flag →
main.go(parseArgs+printHelp). - New safety check →
internal/engine/safety.go+ a test.
- Don't add network calls. The only permitted network access is the
once-daily update check in
internal/update(a single GET to the GitHub releases API, opt-out via--no-update-check/RECLAIM_NO_UPDATE_CHECK=1, never blocks, never downloads anything). Everything else runs fully offline. - Don't add telemetry, crash reporting, or analytics.
- Don't shell out to
rm. Useos.RemoveAll(it's safer and gives us errors). - Don't bypass
CheckPathSafe. If your code path needs to delete, it goes throughengine.Apply. - Don't introduce CGO. We want a single static binary.
- Every PR must pass
go vet ./...andgo test ./.... - New rules don't need Go tests, but paste a sample of
./reclaim --plainoutput in the PR description showing your rule fires correctly on a real machine. - New code in
engine(anything that decides to delete) must have a unit test, including a negative test that proves it refuses an unsafe input. - Use
t.TempDir()for any test that creates files. Never write to a hardcoded path.
Before submitting, verify each:
-
go vet ./...is clean -
go test ./...passes -
go test -race ./...passes (if you touched anything concurrent) - If you added a rule, you tested it with
./reclaim --plainand pasted the output in the PR description - If you added user-facing behavior, you updated
README.mdand/orCHANGELOG.md - If you changed safety logic, you added a test that proves it rejects unsafe input
- No new external dependencies, or you've justified them in the PR
- Commit messages explain why, not just what
Open an issue with:
reclaim --version- macOS version (
sw_vers) - Exact command you ran
- What you expected
- What happened (paste the output, including any error)
- If the bug involves the TUI, a screen recording or screenshot helps
If reclaim deleted something it shouldn't have, also include:
- The relevant log line(s) from
~/.reclaim/logs/YYYY-MM-DD.jsonl - Whether the affected path was in the catalog or scanned dynamically
We treat unwanted deletion as a critical bug.
Don't open a public issue for security problems — see SECURITY.md.
- Follow standard Go conventions. We don't run
gofumpt, butgofmtis required (CI enforces viago vet). - Package names are short and lowercase. No
utilorhelperspackages. - Comments are for why, not what. The code says what.
- Errors flow up. The only
os.Exitisdie()inmain.go. - No
panic()in normal code paths. Use it for "this can't happen" only.
- Two-space indentation.
- Group rules by category, in the same order as
categories:at the top. - IDs are kebab-case.
- Descriptions are one sentence, present tense ("Cleans X" not "Will clean X").
Releases are cut by maintainers with one command:
scripts/release.sh v0.2.0The script verifies a clean main, renames the ## Unreleased CHANGELOG
section to the new version, commits, tags, and pushes. The release.yml
workflow then:
- Cross-compiles
darwin/arm64,darwin/amd64,linux/arm64,linux/amd64 - Creates
.tar.gzarchives withREADME.md+LICENSE - Generates
.sha256files - Publishes a GitHub Release with notes extracted from
CHANGELOG.md - Fills the version + SHAs into
packaging/homebrew/reclaim.rband pushes the result to thehomebrew-taprepo (via theTAP_GITHUB_TOKENsecret), sobrew upgrade reclaimpicks it up immediately.
Contributors don't need to do any of this — just merge to main.
Thanks again for contributing. If anything in this guide is unclear, that's a bug in the docs — please open an issue or PR to fix it.