reclaimable 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. checksums.yaml +7 -0
  2. data/.claude/launch.json +11 -0
  3. data/.gitignore +11 -0
  4. data/.gitlab-ci.yml +16 -0
  5. data/AGENTS.md +88 -0
  6. data/CLAUDE.md +1 -0
  7. data/Gemfile +3 -0
  8. data/LICENSE +674 -0
  9. data/README.md +160 -0
  10. data/Rakefile +28 -0
  11. data/ai-skill/reclaimable/SKILL.md +94 -0
  12. data/benchmark/README.md +59 -0
  13. data/benchmark/experiments/lstat_scanner.rb +11 -0
  14. data/benchmark/experiments/ractor_scanner.rb +92 -0
  15. data/benchmark/experiments/verify_bulk_list.rb +34 -0
  16. data/benchmark/lib/fixture.rb +104 -0
  17. data/benchmark/lib/results.rb +62 -0
  18. data/benchmark/reports/00-baseline.md +75 -0
  19. data/benchmark/reports/01-jit.md +70 -0
  20. data/benchmark/reports/02-ractor.md +58 -0
  21. data/benchmark/reports/03-getattrlistbulk.md +84 -0
  22. data/benchmark/reports/04-others.md +52 -0
  23. data/benchmark/reports/05-outside-root.md +56 -0
  24. data/benchmark/reports/06-round2-discussion.md +374 -0
  25. data/benchmark/reports/06-round2.md +194 -0
  26. data/benchmark/reports/README.md +46 -0
  27. data/benchmark/results/baseline.yml +126 -0
  28. data/benchmark/results/bulk-list.yml +126 -0
  29. data/benchmark/results/final-yjit.yml +126 -0
  30. data/benchmark/results/final.yml +126 -0
  31. data/benchmark/results/ractor-exp.yml +38 -0
  32. data/benchmark/results/round2-after.yml +126 -0
  33. data/benchmark/results/round2-before.yml +126 -0
  34. data/benchmark/results/src-baseline.yml +32 -0
  35. data/benchmark/results/src-bulk-list.yml +32 -0
  36. data/benchmark/results/src-pair-none1.yml +38 -0
  37. data/benchmark/results/src-pair-none2.yml +38 -0
  38. data/benchmark/results/src-pair-yjit1.yml +38 -0
  39. data/benchmark/results/src-pair-yjit2.yml +38 -0
  40. data/benchmark/results/src-ractor-exp.yml +32 -0
  41. data/benchmark/results/src-round2-after1.yml +52 -0
  42. data/benchmark/results/src-round2-after2.yml +52 -0
  43. data/benchmark/results/src-round2-before1.yml +52 -0
  44. data/benchmark/results/src-round2-before2.yml +52 -0
  45. data/benchmark/results/yjit.yml +126 -0
  46. data/benchmark/results/zjit.yml +126 -0
  47. data/benchmark/run.rb +149 -0
  48. data/bin/reclaimable +10 -0
  49. data/doc/performance.md +179 -0
  50. data/lib/reclaimable/ai_skill.rb +138 -0
  51. data/lib/reclaimable/bulk_list.rb +91 -0
  52. data/lib/reclaimable/cache_dump.rb +125 -0
  53. data/lib/reclaimable/cli.rb +168 -0
  54. data/lib/reclaimable/cloud_files.rb +33 -0
  55. data/lib/reclaimable/config.rb +100 -0
  56. data/lib/reclaimable/i18n.rb +24 -0
  57. data/lib/reclaimable/locations.rb +89 -0
  58. data/lib/reclaimable/output.rb +154 -0
  59. data/lib/reclaimable/paths.rb +36 -0
  60. data/lib/reclaimable/report.rb +504 -0
  61. data/lib/reclaimable/ruby_abi.rb +69 -0
  62. data/lib/reclaimable/scan_cache.rb +97 -0
  63. data/lib/reclaimable/scanner.rb +440 -0
  64. data/lib/reclaimable/util.rb +34 -0
  65. data/lib/reclaimable.rb +42 -0
  66. data/locale/ja/LC_MESSAGES/reclaimable.mo +0 -0
  67. data/man/reclaimable.1.ronn +302 -0
  68. data/man/reclaimable.en.1 +234 -0
  69. data/man/reclaimable.ja.1 +452 -0
  70. data/po/ja/reclaimable-docs.po +668 -0
  71. data/po/ja/reclaimable.po +510 -0
  72. data/rakelib/benchmark.rake +22 -0
  73. data/rakelib/docs/japanese.rb +132 -0
  74. data/rakelib/docs/man_page.rb +73 -0
  75. data/rakelib/docs/site.rb +187 -0
  76. data/rakelib/docs/sources.rb +94 -0
  77. data/rakelib/docs/translation.rb +157 -0
  78. data/rakelib/docs.rake +62 -0
  79. data/rakelib/gettext.rake +30 -0
  80. data/rakelib/i18n.rake +199 -0
  81. data/reclaimable.gemspec +56 -0
  82. data/site/index.md +142 -0
  83. data/site/layout.html.erb +60 -0
  84. data/site/style.css +82 -0
  85. metadata +231 -0
@@ -0,0 +1,302 @@
1
+ reclaimable(1) -- find what is eating disk space on your Mac, without deleting anything
2
+ =======================================================================================
3
+
4
+ ## SYNOPSIS
5
+
6
+ `reclaimable` [`-n` <count>] [`-s` <mb>] [`-d` <directory>] [`-o` <directory>] [`-j` <threads>] [`--no-save`] [`--fresh`]
7
+
8
+ ## DESCRIPTION
9
+
10
+ **reclaimable** is a read-only command-line tool for macOS that lists what is
11
+ taking up storage and what you can probably reclaim: regenerable caches, build
12
+ artifacts, gems left behind by old Ruby versions, container disk images, large
13
+ files, and Time Machine local snapshots. It sorts the findings by size.
14
+
15
+ It never deletes anything and never needs `sudo`. It only reads what the
16
+ logged-in user can read, and leaves the decision of what to remove to you.
17
+
18
+ It walks the start directory (your home directory by default) once, in
19
+ parallel, and builds every section of the report from that single scan.
20
+ Scan results are cached, so a second run skips directories that have not
21
+ changed.
22
+
23
+ Messages and the report are in Japanese when your locale is Japanese, and in
24
+ English otherwise. See [ENVIRONMENT][].
25
+
26
+ ## OPTIONS
27
+
28
+ * `-n` <count>:
29
+ Number of entries shown in each ranking. Default: 20.
30
+
31
+ * `-s` <mb>:
32
+ Smallest size, in megabytes, that counts as a "large file". Default: 1024.
33
+
34
+ * `-d` <directory>:
35
+ Directory to start scanning from. Default: your home directory.
36
+
37
+ * `-o` <directory>:
38
+ Directory to save the report and the log in.
39
+ Default: the log directory (see [FILES][]), which is
40
+ `~/Library/Logs/reclaimable` on macOS.
41
+
42
+ * `--save`, `--no-save`:
43
+ Also save the report and the log to files. Default: save.
44
+
45
+ * `-j` <threads>:
46
+ Number of threads that scan in parallel, from 1 to 64.
47
+ Default: the number of CPUs, up to 8.
48
+
49
+ * `--fresh`:
50
+ Ignore the cached scan results and scan everything again.
51
+
52
+ * `--freeze` <directory>:
53
+ Measure <directory> once, save its size to the config file, and skip it in
54
+ later scans. Use this for large folders that never change, such as an old
55
+ copy of a website with many small files. Later scans use the saved size
56
+ instead of reading the folder. Give it again to measure the folder again.
57
+ It can be given more than once. With this option, reclaimable only updates
58
+ the config file and does not make a report.
59
+
60
+ * `--unfreeze` <directory>:
61
+ Remove <directory> from the frozen folders, so it is scanned again.
62
+ It can be given more than once.
63
+
64
+ * `--dump-cache` [<format>]:
65
+ Print the cached scan results for the start directory (`-d`) and exit,
66
+ without scanning. <format> is `text` (a table for people, the default),
67
+ `json`, or `yaml`. Each folder has its modification time, the total size of
68
+ the small files directly in it, the names of its subfolders, and the names
69
+ of its large files. The cache itself is a binary file (Ruby's Marshal,
70
+ compressed with gzip), so use this option to see what it holds.
71
+
72
+ * `--config` <file>:
73
+ Config file to use. Default: see [FILES][].
74
+
75
+ * `--ai-skill`:
76
+ Show the skill for AI agents, where it is, and how to install it, and
77
+ exit. Nothing is written. See [AI AGENT SKILL][].
78
+
79
+ * `--install-ai-skill` [<directory>]:
80
+ Install the skill for AI agents in the skill directory <directory>, as
81
+ <directory>`/reclaimable`, and exit. Files that are already there are
82
+ overwritten. Without <directory>, reclaimable asks where to install it. It
83
+ can be given more than once. See [AI AGENT SKILL][].
84
+
85
+ * `--man`:
86
+ Show this manual, in Japanese when your locale is Japanese and in English
87
+ otherwise.
88
+
89
+ * `-h`, `--help`:
90
+ Show a short usage message.
91
+
92
+ ## REPORT
93
+
94
+ The report has these sections, in this order:
95
+
96
+ * Whole disk:
97
+ `df -h` for the data volume.
98
+
99
+ * Largest folders:
100
+ The largest folders directly under the start directory, and what is inside them.
101
+
102
+ * Usually regenerable:
103
+ Known cache and download locations of 100 MB or more, such as `~/Library/Caches`,
104
+ the Homebrew cache, npm/pnpm/yarn/bun caches, Cargo registries, Xcode DerivedData,
105
+ iOS simulators, Ollama and Hugging Face models, gem documentation, and iPhone
106
+ backups, each with a note on what happens if you remove it.
107
+
108
+ * Build artifacts and dependencies:
109
+ `node_modules`, `.venv`, `venv`, `.build`, `.dart_tool`, and Cargo `target`
110
+ folders of 50 MB or more, with the date each was last modified, so you can
111
+ spot projects you no longer touch.
112
+
113
+ * Ruby gems:
114
+ `vendor/bundle` and user gem directories, split by Ruby version, marking
115
+ the ones left behind by Ruby versions that are no longer used or installed.
116
+ `vendor/bundle` is split by ABI version (such as 4.0.0). User gem directories
117
+ are named by ABI version, or by full version (such as 4.0.9) when chruby
118
+ manages them; both are matched against the installed Rubies. For user gem
119
+ directories, the size of their documentation is also shown.
120
+
121
+ * Containers:
122
+ Data folders and disk images of Docker Desktop, Colima, Lima, OrbStack,
123
+ Podman, and Rancher Desktop, both the real usage and the apparent size of the
124
+ sparse disk images, plus `docker system df` for each running Docker engine.
125
+ Contexts that point to the same engine are shown only once.
126
+
127
+ * Large files:
128
+ Files of at least the `-s` size, outside the Trash.
129
+
130
+ * Time Machine local snapshots:
131
+ `tmutil listlocalsnapshots /`.
132
+
133
+ * Estimates from other tools:
134
+ `brew cleanup -n`, `ollama list`, `rustup toolchain list`, and unavailable
135
+ iOS simulators.
136
+
137
+ * Frozen folders:
138
+ Folders frozen with `--freeze`, with the size and the date they were
139
+ measured. Large files and build artifacts inside them do not appear in the
140
+ sections above. A folder is marked when it has changed since it was
141
+ measured (files were added, removed, or renamed directly inside it).
142
+ This section appears only when there are such folders.
143
+
144
+ * Unreadable locations:
145
+ Folders that could not be read and are therefore missing from the totals.
146
+
147
+ * Cloud-only folders:
148
+ Folders whose contents live only in iCloud Drive, Google Drive, or other
149
+ cloud storage. They were not read and use almost no local space.
150
+ This section appears only when there are such folders.
151
+
152
+ ## FILES
153
+
154
+ Where each kind of file goes is decided in this order. If the XDG environment
155
+ variable for that kind is set to an absolute path, the directory under it is
156
+ used on any system (see [ENVIRONMENT][]). Otherwise, macOS uses the places
157
+ under `~/Library` that Apple's conventions give, and other systems such as
158
+ Linux use the XDG defaults.
159
+
160
+ * Log directory:
161
+ `$XDG_STATE_HOME/reclaimable` if `XDG_STATE_HOME` is set. Otherwise
162
+ `~/Library/Logs/reclaimable` on macOS and `~/.local/state/reclaimable`
163
+ elsewhere. It holds the report, <YYYYmmdd-HHMMSS>`.report.txt`, and the
164
+ log, <YYYYmmdd-HHMMSS>`.log`, one of each per run. The log has failed
165
+ commands, every unreadable location, and timings.
166
+
167
+ * Cache directory:
168
+ `$XDG_CACHE_HOME/reclaimable` if `XDG_CACHE_HOME` is set. Otherwise
169
+ `~/Library/Caches/reclaimable` on macOS and `~/.cache/reclaimable`
170
+ elsewhere. It holds cached scan results, one file per start directory. A
171
+ cache older than 7 days is ignored. `--dump-cache` shows what a cache holds.
172
+
173
+ * Config file:
174
+ `$XDG_CONFIG_HOME/reclaimable/config.yml` if `XDG_CONFIG_HOME` is set.
175
+ Otherwise `~/Library/Application Support/reclaimable/config.yml` on macOS
176
+ and `~/.config/reclaimable/config.yml` elsewhere. It is in YAML and holds
177
+ the frozen folders: for each, the size, the modification time of the
178
+ folder, and when it was measured. Paths start with `~`. `--freeze` and
179
+ `--unfreeze` write it. You can also edit it by hand, but comments are lost
180
+ when they rewrite it.
181
+
182
+ A config file with one frozen folder looks like this:
183
+
184
+ frozen:
185
+ "~/archive/old-site":
186
+ bytes: 19579686912
187
+ mtime: 1683312343701143794
188
+ measured_at: '2026-11-15T23:15:44+09:00'
189
+
190
+ ## ENVIRONMENT
191
+
192
+ * `XDG_CONFIG_HOME`:
193
+ Base directory for the config file. See [FILES][].
194
+
195
+ * `XDG_STATE_HOME`:
196
+ Base directory for the report and the log. See [FILES][].
197
+
198
+ * `XDG_CACHE_HOME`:
199
+ Base directory for the scan cache. See [FILES][].
200
+
201
+ * `LC_ALL`, `LC_MESSAGES`, `LANG`:
202
+ The language of messages and the report, checked in this order. If the first
203
+ one that is set starts with `ja` (for example `ja_JP.UTF-8`), they are in
204
+ Japanese. Otherwise they are in English. To get English once, run
205
+ `LC_ALL=C reclaimable`.
206
+
207
+ ## NOTES
208
+
209
+ Folders such as Desktop, Documents, Downloads, and Mail are protected by macOS
210
+ privacy controls. Unless your terminal app has Full Disk Access, they cannot be
211
+ read, and they are listed at the end of the report. To include them, give the
212
+ terminal app Full Disk Access in System Settings and run again. `sudo` is not
213
+ needed.
214
+
215
+ reclaimable does not download files that live only in the cloud. Reading such
216
+ a folder would normally make macOS download it, so reclaimable turns that off
217
+ for its own process and lists those folders in the report instead. If it
218
+ cannot turn it off, it skips `~/Library/Mobile Documents` and
219
+ `~/Library/CloudStorage` and says so.
220
+
221
+ Sizes are the space actually used on disk (allocated blocks), not the apparent
222
+ file size. Files that live only in the cloud (Dropbox or iCloud "online only")
223
+ and sparse files are counted smaller than they look in Finder.
224
+
225
+ ## EXAMPLES
226
+
227
+ Scan your home directory and save the report:
228
+
229
+ $ reclaimable
230
+
231
+ Show the top 50 entries and treat files of 500 MB or more as large:
232
+
233
+ $ reclaimable -n 50 -s 500
234
+
235
+ Scan only `~/src`, ignore the cache, and do not save files:
236
+
237
+ $ reclaimable -d ~/src --fresh --no-save
238
+
239
+ Freeze a large folder that never changes, so later scans skip it:
240
+
241
+ $ reclaimable --freeze ~/archive/old-site
242
+
243
+ ## INSTALLATION
244
+
245
+ reclaimable needs Ruby 4.0 or later. Its only runtime gem dependency is
246
+ gettext, for translated messages.
247
+
248
+ $ gem install reclaimable
249
+
250
+ To read this manual from the installed gem, run `reclaimable --man`. It opens
251
+ the Japanese version when your locale is Japanese, and the English version
252
+ otherwise.
253
+
254
+ $ reclaimable --man
255
+
256
+ You can also read it with gem-man. When asked which manual to open, choose
257
+ `reclaimable.en.1` for English or `reclaimable.ja.1` for Japanese.
258
+
259
+ $ gem install gem-man
260
+ $ gem man reclaimable
261
+
262
+ ## AI AGENT SKILL
263
+
264
+ The gem includes a skill for AI agents such as Claude Code and Codex, in the
265
+ Agent Skills format (<https://agentskills.io>). It tells the agent how to run
266
+ reclaimable, how to read the report, and never to delete anything without
267
+ asking you. The gem does not install it for you.
268
+
269
+ To see the skill and the commands that install it by hand:
270
+
271
+ $ reclaimable --ai-skill
272
+
273
+ To let reclaimable install it:
274
+
275
+ $ reclaimable --install-ai-skill
276
+
277
+ It lists the skill directories that exist, `~/.claude/skills` (Claude Code)
278
+ and `~/.agents/skills` (Codex and other agents), and asks which to use. You
279
+ can choose more than one, or enter another directory. It asks again before it
280
+ overwrites a skill that is already installed. When standard input is not a
281
+ terminal, it does not ask: it shows how to give the directory and exits with
282
+ an error.
283
+
284
+ To install it without being asked, give the skill directory. This is the form
285
+ for scripts and for agents:
286
+
287
+ $ reclaimable --install-ai-skill=~/.claude/skills
288
+
289
+ The skill is copied to `reclaimable` in that directory. If that is a symbolic
290
+ link, nothing is written. The copy is not updated with the gem, so install it
291
+ again after you update reclaimable.
292
+
293
+ ## LICENSE
294
+
295
+ reclaimable is free software, released under the GNU General Public License,
296
+ version 3 or (at your option) any later version.
297
+
298
+ ## SEE ALSO
299
+
300
+ df(1), du(1), tmutil(8), brew(1), docker(1)
301
+
302
+ <https://kitaitimakoto.gitlab.io/reclaimable/>
@@ -0,0 +1,234 @@
1
+ .\" generated with Ronn-NG/v0.10.1
2
+ .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
3
+ .TH "RECLAIMABLE" "1" "November 2026" "reclaimable 0.1.0"
4
+ .SH "NAME"
5
+ \fBreclaimable\fR \- find what is eating disk space on your Mac, without deleting anything
6
+ .SH "SYNOPSIS"
7
+ \fBreclaimable\fR [\fB\-n\fR \fIcount\fR] [\fB\-s\fR \fImb\fR] [\fB\-d\fR \fIdirectory\fR] [\fB\-o\fR \fIdirectory\fR] [\fB\-j\fR \fIthreads\fR] [\fB\-\-no\-save\fR] [\fB\-\-fresh\fR]
8
+ .SH "DESCRIPTION"
9
+ \fBreclaimable\fR is a read\-only command\-line tool for macOS that lists what is taking up storage and what you can probably reclaim: regenerable caches, build artifacts, gems left behind by old Ruby versions, container disk images, large files, and Time Machine local snapshots\. It sorts the findings by size\.
10
+ .P
11
+ It never deletes anything and never needs \fBsudo\fR\. It only reads what the logged\-in user can read, and leaves the decision of what to remove to you\.
12
+ .P
13
+ It walks the start directory (your home directory by default) once, in parallel, and builds every section of the report from that single scan\. Scan results are cached, so a second run skips directories that have not changed\.
14
+ .P
15
+ Messages and the report are in Japanese when your locale is Japanese, and in English otherwise\. See \fIENVIRONMENT\fR\.
16
+ .SH "OPTIONS"
17
+ .TP
18
+ \fB\-n\fR \fIcount\fR
19
+ Number of entries shown in each ranking\. Default: 20\.
20
+ .TP
21
+ \fB\-s\fR \fImb\fR
22
+ Smallest size, in megabytes, that counts as a "large file"\. Default: 1024\.
23
+ .TP
24
+ \fB\-d\fR \fIdirectory\fR
25
+ Directory to start scanning from\. Default: your home directory\.
26
+ .TP
27
+ \fB\-o\fR \fIdirectory\fR
28
+ Directory to save the report and the log in\. Default: the log directory (see \fIFILES\fR), which is \fB~/Library/Logs/reclaimable\fR on macOS\.
29
+ .TP
30
+ \fB\-\-save\fR, \fB\-\-no\-save\fR
31
+ Also save the report and the log to files\. Default: save\.
32
+ .TP
33
+ \fB\-j\fR \fIthreads\fR
34
+ Number of threads that scan in parallel, from 1 to 64\. Default: the number of CPUs, up to 8\.
35
+ .TP
36
+ \fB\-\-fresh\fR
37
+ Ignore the cached scan results and scan everything again\.
38
+ .TP
39
+ \fB\-\-freeze\fR \fIdirectory\fR
40
+ Measure \fIdirectory\fR once, save its size to the config file, and skip it in later scans\. Use this for large folders that never change, such as an old copy of a website with many small files\. Later scans use the saved size instead of reading the folder\. Give it again to measure the folder again\. It can be given more than once\. With this option, reclaimable only updates the config file and does not make a report\.
41
+ .TP
42
+ \fB\-\-unfreeze\fR \fIdirectory\fR
43
+ Remove \fIdirectory\fR from the frozen folders, so it is scanned again\. It can be given more than once\.
44
+ .TP
45
+ \fB\-\-dump\-cache\fR [\fIformat\fR]
46
+ Print the cached scan results for the start directory (\fB\-d\fR) and exit, without scanning\. \fIformat\fR is \fBtext\fR (a table for people, the default), \fBjson\fR, or \fByaml\fR\. Each folder has its modification time, the total size of the small files directly in it, the names of its subfolders, and the names of its large files\. The cache itself is a binary file (Ruby's Marshal, compressed with gzip), so use this option to see what it holds\.
47
+ .TP
48
+ \fB\-\-config\fR \fIfile\fR
49
+ Config file to use\. Default: see \fIFILES\fR\.
50
+ .TP
51
+ \fB\-\-ai\-skill\fR
52
+ Show the skill for AI agents, where it is, and how to install it, and exit\. Nothing is written\. See \fIAI AGENT SKILL\fR\.
53
+ .TP
54
+ \fB\-\-install\-ai\-skill\fR [\fIdirectory\fR]
55
+ Install the skill for AI agents in the skill directory \fIdirectory\fR, as \fIdirectory\fR\fB/reclaimable\fR, and exit\. Files that are already there are overwritten\. Without \fIdirectory\fR, reclaimable asks where to install it\. It can be given more than once\. See \fIAI AGENT SKILL\fR\.
56
+ .TP
57
+ \fB\-\-man\fR
58
+ Show this manual, in Japanese when your locale is Japanese and in English otherwise\.
59
+ .TP
60
+ \fB\-h\fR, \fB\-\-help\fR
61
+ Show a short usage message\.
62
+ .SH "REPORT"
63
+ The report has these sections, in this order:
64
+ .TP
65
+ Whole disk
66
+ \fBdf \-h\fR for the data volume\.
67
+ .TP
68
+ Largest folders
69
+ The largest folders directly under the start directory, and what is inside them\.
70
+ .TP
71
+ Usually regenerable
72
+ Known cache and download locations of 100 MB or more, such as \fB~/Library/Caches\fR, the Homebrew cache, npm/pnpm/yarn/bun caches, Cargo registries, Xcode DerivedData, iOS simulators, Ollama and Hugging Face models, gem documentation, and iPhone backups, each with a note on what happens if you remove it\.
73
+ .TP
74
+ Build artifacts and dependencies
75
+ \fBnode_modules\fR, \fB\.venv\fR, \fBvenv\fR, \fB\.build\fR, \fB\.dart_tool\fR, and Cargo \fBtarget\fR folders of 50 MB or more, with the date each was last modified, so you can spot projects you no longer touch\.
76
+ .TP
77
+ Ruby gems
78
+ \fBvendor/bundle\fR and user gem directories, split by Ruby version, marking the ones left behind by Ruby versions that are no longer used or installed\. \fBvendor/bundle\fR is split by ABI version (such as 4\.0\.0)\. User gem directories are named by ABI version, or by full version (such as 4\.0\.9) when chruby manages them; both are matched against the installed Rubies\. For user gem directories, the size of their documentation is also shown\.
79
+ .TP
80
+ Containers
81
+ Data folders and disk images of Docker Desktop, Colima, Lima, OrbStack, Podman, and Rancher Desktop, both the real usage and the apparent size of the sparse disk images, plus \fBdocker system df\fR for each running Docker engine\. Contexts that point to the same engine are shown only once\.
82
+ .TP
83
+ Large files
84
+ Files of at least the \fB\-s\fR size, outside the Trash\.
85
+ .TP
86
+ Time Machine local snapshots
87
+ \fBtmutil listlocalsnapshots /\fR\.
88
+ .TP
89
+ Estimates from other tools
90
+ \fBbrew cleanup \-n\fR, \fBollama list\fR, \fBrustup toolchain list\fR, and unavailable iOS simulators\.
91
+ .TP
92
+ Frozen folders
93
+ Folders frozen with \fB\-\-freeze\fR, with the size and the date they were measured\. Large files and build artifacts inside them do not appear in the sections above\. A folder is marked when it has changed since it was measured (files were added, removed, or renamed directly inside it)\. This section appears only when there are such folders\.
94
+ .TP
95
+ Unreadable locations
96
+ Folders that could not be read and are therefore missing from the totals\.
97
+ .TP
98
+ Cloud\-only folders
99
+ Folders whose contents live only in iCloud Drive, Google Drive, or other cloud storage\. They were not read and use almost no local space\. This section appears only when there are such folders\.
100
+ .SH "FILES"
101
+ Where each kind of file goes is decided in this order\. If the XDG environment variable for that kind is set to an absolute path, the directory under it is used on any system (see \fIENVIRONMENT\fR)\. Otherwise, macOS uses the places under \fB~/Library\fR that Apple's conventions give, and other systems such as Linux use the XDG defaults\.
102
+ .TP
103
+ Log directory
104
+ \fB$XDG_STATE_HOME/reclaimable\fR if \fBXDG_STATE_HOME\fR is set\. Otherwise \fB~/Library/Logs/reclaimable\fR on macOS and \fB~/\.local/state/reclaimable\fR elsewhere\. It holds the report, \fIYYYYmmdd\-HHMMSS\fR\fB\.report\.txt\fR, and the log, \fIYYYYmmdd\-HHMMSS\fR\fB\.log\fR, one of each per run\. The log has failed commands, every unreadable location, and timings\.
105
+ .TP
106
+ Cache directory
107
+ \fB$XDG_CACHE_HOME/reclaimable\fR if \fBXDG_CACHE_HOME\fR is set\. Otherwise \fB~/Library/Caches/reclaimable\fR on macOS and \fB~/\.cache/reclaimable\fR elsewhere\. It holds cached scan results, one file per start directory\. A cache older than 7 days is ignored\. \fB\-\-dump\-cache\fR shows what a cache holds\.
108
+ .TP
109
+ Config file
110
+ \fB$XDG_CONFIG_HOME/reclaimable/config\.yml\fR if \fBXDG_CONFIG_HOME\fR is set\. Otherwise \fB~/Library/Application Support/reclaimable/config\.yml\fR on macOS and \fB~/\.config/reclaimable/config\.yml\fR elsewhere\. It is in YAML and holds the frozen folders: for each, the size, the modification time of the folder, and when it was measured\. Paths start with \fB~\fR\. \fB\-\-freeze\fR and \fB\-\-unfreeze\fR write it\. You can also edit it by hand, but comments are lost when they rewrite it\.
111
+ .P
112
+ A config file with one frozen folder looks like this:
113
+ .sp
114
+ .RS 4
115
+ .nf
116
+ frozen:
117
+ "~/archive/old\-site":
118
+ bytes: 19579686912
119
+ mtime: 1683312343701143794
120
+ measured_at: '2026\-11\-15T23:15:44+09:00'
121
+ .fi
122
+ .RE
123
+ .SH "ENVIRONMENT"
124
+ .TP
125
+ \fBXDG_CONFIG_HOME\fR
126
+ Base directory for the config file\. See \fIFILES\fR\.
127
+ .TP
128
+ \fBXDG_STATE_HOME\fR
129
+ Base directory for the report and the log\. See \fIFILES\fR\.
130
+ .TP
131
+ \fBXDG_CACHE_HOME\fR
132
+ Base directory for the scan cache\. See \fIFILES\fR\.
133
+ .TP
134
+ \fBLC_ALL\fR, \fBLC_MESSAGES\fR, \fBLANG\fR
135
+ The language of messages and the report, checked in this order\. If the first one that is set starts with \fBja\fR (for example \fBja_JP\.UTF\-8\fR), they are in Japanese\. Otherwise they are in English\. To get English once, run \fBLC_ALL=C reclaimable\fR\.
136
+ .SH "NOTES"
137
+ Folders such as Desktop, Documents, Downloads, and Mail are protected by macOS privacy controls\. Unless your terminal app has Full Disk Access, they cannot be read, and they are listed at the end of the report\. To include them, give the terminal app Full Disk Access in System Settings and run again\. \fBsudo\fR is not needed\.
138
+ .P
139
+ reclaimable does not download files that live only in the cloud\. Reading such a folder would normally make macOS download it, so reclaimable turns that off for its own process and lists those folders in the report instead\. If it cannot turn it off, it skips \fB~/Library/Mobile Documents\fR and \fB~/Library/CloudStorage\fR and says so\.
140
+ .P
141
+ Sizes are the space actually used on disk (allocated blocks), not the apparent file size\. Files that live only in the cloud (Dropbox or iCloud "online only") and sparse files are counted smaller than they look in Finder\.
142
+ .SH "EXAMPLES"
143
+ Scan your home directory and save the report:
144
+ .sp
145
+ .RS 4
146
+ .nf
147
+ $ reclaimable
148
+ .fi
149
+ .RE
150
+ .P
151
+ Show the top 50 entries and treat files of 500 MB or more as large:
152
+ .sp
153
+ .RS 4
154
+ .nf
155
+ $ reclaimable \-n 50 \-s 500
156
+ .fi
157
+ .RE
158
+ .P
159
+ Scan only \fB~/src\fR, ignore the cache, and do not save files:
160
+ .sp
161
+ .RS 4
162
+ .nf
163
+ $ reclaimable \-d ~/src \-\-fresh \-\-no\-save
164
+ .fi
165
+ .RE
166
+ .P
167
+ Freeze a large folder that never changes, so later scans skip it:
168
+ .sp
169
+ .RS 4
170
+ .nf
171
+ $ reclaimable \-\-freeze ~/archive/old\-site
172
+ .fi
173
+ .RE
174
+ .SH "INSTALLATION"
175
+ reclaimable needs Ruby 4\.0 or later\. Its only runtime gem dependency is gettext, for translated messages\.
176
+ .sp
177
+ .RS 4
178
+ .nf
179
+ $ gem install reclaimable
180
+ .fi
181
+ .RE
182
+ .P
183
+ To read this manual from the installed gem, run \fBreclaimable \-\-man\fR\. It opens the Japanese version when your locale is Japanese, and the English version otherwise\.
184
+ .sp
185
+ .RS 4
186
+ .nf
187
+ $ reclaimable \-\-man
188
+ .fi
189
+ .RE
190
+ .P
191
+ You can also read it with gem\-man\. When asked which manual to open, choose \fBreclaimable\.en\.1\fR for English or \fBreclaimable\.ja\.1\fR for Japanese\.
192
+ .sp
193
+ .RS 4
194
+ .nf
195
+ $ gem install gem\-man
196
+ $ gem man reclaimable
197
+ .fi
198
+ .RE
199
+ .SH "AI AGENT SKILL"
200
+ The gem includes a skill for AI agents such as Claude Code and Codex, in the Agent Skills format (\fIhttps://agentskills\.io\fR)\. It tells the agent how to run reclaimable, how to read the report, and never to delete anything without asking you\. The gem does not install it for you\.
201
+ .P
202
+ To see the skill and the commands that install it by hand:
203
+ .sp
204
+ .RS 4
205
+ .nf
206
+ $ reclaimable \-\-ai\-skill
207
+ .fi
208
+ .RE
209
+ .P
210
+ To let reclaimable install it:
211
+ .sp
212
+ .RS 4
213
+ .nf
214
+ $ reclaimable \-\-install\-ai\-skill
215
+ .fi
216
+ .RE
217
+ .P
218
+ It lists the skill directories that exist, \fB~/\.claude/skills\fR (Claude Code) and \fB~/\.agents/skills\fR (Codex and other agents), and asks which to use\. You can choose more than one, or enter another directory\. It asks again before it overwrites a skill that is already installed\. When standard input is not a terminal, it does not ask: it shows how to give the directory and exits with an error\.
219
+ .P
220
+ To install it without being asked, give the skill directory\. This is the form for scripts and for agents:
221
+ .sp
222
+ .RS 4
223
+ .nf
224
+ $ reclaimable \-\-install\-ai\-skill=~/\.claude/skills
225
+ .fi
226
+ .RE
227
+ .P
228
+ The skill is copied to \fBreclaimable\fR in that directory\. If that is a symbolic link, nothing is written\. The copy is not updated with the gem, so install it again after you update reclaimable\.
229
+ .SH "LICENSE"
230
+ reclaimable is free software, released under the GNU General Public License, version 3 or (at your option) any later version\.
231
+ .SH "SEE ALSO"
232
+ df(1), du(1), tmutil(8), brew(1), docker(1)
233
+ .P
234
+ \fIhttps://kitaitimakoto\.gitlab\.io/reclaimable/\fR