| name | config-gc |
| description | Claude Code 配置的垃圾回收。定期扫描 ~/.claude（skills、memory、hooks、permissions、MCP servers、caches）中冗余、过期、孤立或低价值的项目，然后逐项确认清理。用于用户说“clean up my config”、“config GC”、“too many skills”、“audit my setup”、“my .claude is bloated”，或请求定期配置审查时。 |
| metadata | {"origin":"ECC"} |
Config GC — Claude Code 配置垃圾回收
借用运行时垃圾回收的思路：定期扫描不再被引用、冗余、过期或低价值的对象，并回收空间。关键区别是：这里的回收必须有人参与。不要自治删除。
何时激活
- 用户要求清理、审计或瘦身 Claude Code 配置
- 用户抱怨 skills 太多、hooks 太吵或 session 启动慢
- 到了每月/定期 config review
- 安装大型 skill pack（例如本 repo）后，用来调和与既有配置的重叠
不要用于：清理项目源码（那是重构）、清空聊天历史或卸载 Claude Code 本身。
设计理念
- Append-only configs 会泄漏。 Skills、memory files、hooks 和 permission entries 只会不断增加。不定期审查就会静默腐烂。
- 定期审计胜过一次性清空。 每约 30 天扫描一次，每次提出一小批候选。
- 按通道使用不同策略。 每种累积类型（skills、hooks、permissions 等）都有自己的过期信号，不要一条规则套全部。
- 先软删除。 重命名为
.disabled > 移到 ~/.claude/_gc_trash/ > 真删除。始终保留 undo path。
- 强制 human-in-the-loop。 每个候选都有自己的
[y/n/skip] 确认。没有 “yes to all” 捷径。
- 保留日志。 每次 GC run 追加到
~/.claude/gc_log.md：动了什么、为什么、如何撤销。
扫描通道
| # | 通道 | 路径 | 过期 / 冗余信号 |
|---|
| 1 | Skills | ~/.claude/skills/*/ | 名称高度重叠；近期 transcripts 从未触发；领域与用户实际工作不匹配；破损或空 SKILL.md |
| 2 | Memory | ~/.claude/**/memory/*.md + index | 同一主题多个 index entries；内容与更新条目矛盾；日期已过；index 缺失的 orphan files；应合并的低于 100 词片段 |
| 3 | Hooks | ~/.claude/hooks/ + settings | 磁盘上有脚本但没有 hook config 引用；旧版本已被重写取代 |
| 4 | Permissions | settings.json / settings.local.json 中的 permissions.allow | 重复 entries；已被 wildcard 覆盖的具体条目（如已有 Bash(*) 时的 Bash(git push)）；过往实验的一次性授权 |
| 5 | MCP servers | ~/.claude.json 或项目 .mcp.json | 无法连接的 servers；功能重复；长期不用 |
| 6 | Scheduled reminders / jobs | 用户存放位置 | 已触发的一次性任务超过 30 天；目标脚本已不存在的 jobs |
| 7 | Project history | ~/.claude/projects/*/ | 陈旧 handoff snapshots；已被新状态取代的 session records |
| 8 | Runtime caches | cache/、file-history/、logs/、shell-snapshots/ | 按大小和 mtime 排序；建议清理超过 30 天且较大的项目 |
工作流
- Scan 所有通道（或用户指定子集）。收集候选：path、channel、触发信号、size、last-modified。
- Rank 按置信度排序（broken/orphaned = high；只是旧 = low），以编号表格展示。每次最多约 20 个候选——GC 是周期性的，不是穷尽式。
- 逐项确认。 对每个候选显示证据，然后询问
[y/n/skip]。用户可以随时停止。
- 软删除确认项：skills/hooks 优先
.disabled 重命名，文件移到 _gc_trash/<date>/。Permission entries 位于 JSON（不能写 comments）：备份 settings 文件，在 gc_log.md 中逐字记录每个 removed entry，然后用 jq 从 allow 数组删除。只有用户明确要求时才硬删除。
- Log 到
~/.claude/gc_log.md：timestamp、处理项、undo instructions。
- Report：回收大小、仍健康的通道、建议下次审查日期。
示例扫描命令
孤立 hook scripts（channel 3）——磁盘上存在但没有 hook config 引用的 scripts：
for f in ~/.claude/hooks/*; do
name=$(basename "$f")
grep -rq "$name" ~/.claude/settings.json ~/.claude/settings.local.json 2>/dev/null \
|| echo "ORPHAN: $f"
done
冗余 permission entries（channel 4）——重复项，以及被 wildcard 遮蔽的具体授权：
jq -r '.permissions.allow[]' ~/.claude/settings.local.json | sort | uniq -d
if jq -e '.permissions.allow | index("Bash(*)")' ~/.claude/settings.local.json >/dev/null; then
jq -r '.permissions.allow[]' ~/.claude/settings.local.json \
| grep '^Bash(' | grep -vF 'Bash(*)'
fi
最大的陈旧 caches（channel 8）——使用 du -k 而不是 GNU-only find -printf，因此 macOS/BSD 也能用：
find ~/.claude/file-history ~/.claude/shell-snapshots -type f -mtime +30 \
-exec du -k {} + 2>/dev/null | sort -rn | head -20
带 undo path 的软删除（只捕获一次日期，避免日志和目录不一致）：
gc_date=$(date +%Y-%m-%d)
mkdir -p ~/.claude/_gc_trash/$gc_date
mv ~/.claude/skills/dead-skill ~/.claude/_gc_trash/$gc_date/
echo "$(date -Iseconds) moved skills/dead-skill -> _gc_trash/$gc_date/ (undo: mv back)" >> ~/.claude/gc_log.md
删除已确认冗余的 permission entry（JSON 无 comments——先备份、记录，再编辑）：
cp ~/.claude/settings.local.json ~/.claude/settings.local.json.bak
echo "$(date -Iseconds) removed permission entry: Bash(git push) (undo: restore from .bak or re-add)" >> ~/.claude/gc_log.md
jq '.permissions.allow -= ["Bash(git push)"]' ~/.claude/settings.local.json.bak \
> ~/.claude/settings.local.json
反模式
- 批量批准。 问“delete all 15? [y/n]”违背设计。一个项目，一个决定。
- 第一轮硬删除。 没有
_gc_trash/ 副本或 .disabled 重命名，就是做错了。
- 把“旧”当成“死”。 一个 60 天没用的 skill 可能是季节性需求（税季、季度复盘）。年龄是信号，不是结论——这就是为什么需要人确认。
- 靠截断清理 memory。 合并两个矛盾 memory files 需要读两者并保留更新事实，不是删除更长的那个。
- 触碰
~/.claude 外的任何东西（或项目 .claude/）。Config GC 不会跑进源码树。
最佳实践
- 大量新增后运行，而不只是按日历运行：安装 50-skill pack 正是与现有 skills 产生重叠的时候。
- 两个 skills 重叠时，优先禁用 trigger description 较弱的那个——它大概率本来就不会触发。
- Permission cleanup 是单位时间价值最高的通道：冗余 allow-entries 会让安全审查更难。
- 永久保留
gc_log.md。它很小，而“我什么时候禁用了那个 hook，为什么”比你想的更常出现。
相关技能
skill-stocktake — 审计 skill 质量；config-gc 审计 skill 是否应存在。对 GC 后保留下来的运行 stocktake。workspace-surface-audit — 加法侧：建议安装什么。config-gc 是同一生命周期的减法半边。configure-ecc — 用它安装 skills 后，运行 config-gc 来调和与既有配置的重叠。continuous-learning — 产生此技能后续审计的 memory files。security-review — 与 permissions 通道搭配很好。
