compact-tool

给 Claude Code 的上下文管家：状态栏常驻显示上下文占用百分比，快满时自动提醒，一条命令先存档、再压缩——重要信息不丢。

---

✨ 它是什么

compact-tool 是一个 Claude Code 插件，专治一个老问题：聊着聊着上下文满了——要么被强制压缩丢掉中途的关键信息，要么干脆忘了及时 /compact。

它做三件事：

	功能	触发
👀	看 —— 状态栏常驻显示「上下文已用 X%」，带进度条、按阈值变色	自动（需手动启用一行配置）
🔔	提醒 —— 占用超过 85% 时自动提醒	自动（装完即生效）
💾	一键存档+压缩 —— /compact-tool:save 先存档再压缩	手动

🎯 为什么需要它

直接 /compact 只是把对话压短，「任务做到哪、为什么这么决定、待办还有啥」会一起被压没。/compact-tool:save 在压缩之前先把这些沉淀到记忆文件——相当于「先存档、再压缩」。

🌍 适配环境

凡是能跑 Claude Code 的地方都支持：

• ✅ 终端 CLI（macOS / Linux / Windows+WSL）
• ✅ VS Code 扩展
• ✅ JetBrains 扩展
• ✅ Claude Code 桌面 app
• ✅ claude.ai/code 网页版

hook、slash command、statusLine 都是 Claude Code 引擎层功能，与 IDE 前端无关。

🚀 安装

# 1. 添加 marketplace
claude plugin marketplace add haix716/compact-tool

# 2. 安装插件
claude plugin install compact-tool@compact-tool

或在 Claude Code 交互界面：

/plugin marketplace add haix716/compact-tool
/plugin install compact-tool@compact-tool

装完即生效——下次发消息时 hook 就开始监控，/compact-tool:save 即可使用。

⚙️ 可选：启用百分比状态栏

statusLine 属于 Claude Code 用户级配置，plugin 无法自动注册，需手动加一行。编辑 ~/.claude/settings.json：

极简版（一行，零依赖）

"statusLine": {
  "type": "command",
  "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
}

增强版（进度条 + 变色，用本仓库脚本）

"statusLine": {
  "type": "command",
  "command": "bash /绝对路径/compact-tool/plugin/scripts/statusline.sh"
}

🔧 配置

提醒阈值和窗口大小可在 settings.json 的 env 里调：

变量	默认	说明
COMPACT_TOOL_THRESHOLD	85	占用超过此百分比则提醒
COMPACT_TOOL_WINDOW	200000	上下文窗口大小（tokens）

📖 使用

平时：正常聊天。状态栏看百分比，超过 85% 会自动提醒。

该压缩了：

/compact-tool:save

它会 ① 总结进展 → ② 写入记忆文件 → ③ 执行 /compact → ④ 报告结果。

只想压缩、不想存档：直接 /compact。

🔧 工作原理

• 提醒 hook（UserPromptSubmit）：每次发消息时解析会话 transcript，取最后一条 assistant 记录的 token 用量估算占用，超阈值则输出提醒。
• /save：slash command（skill 形态），由 Claude 按既定步骤执行存档 + 压缩。
• statusLine：读取 Claude Code 提供的 context_window.used_percentage 字段渲染。

⚠️ 已知限制

• 提醒基于 transcript 估算，受异步写入影响可能略有延迟；statusLine 的 used_percentage 更准。
• 第三方 API 网关若不返回 usage 字段，状态栏显示 n/a（提醒 hook 仍基于 transcript 工作）。
• statusLine 不能做成可点击按钮——「一键」靠 /compact-tool:save 命令实现。
• 接近上限时 Claude Code 本身也会自动 compact，本工具是补充而非替代。

❓ FAQ

Q：重启后 hook 还在吗？ A：在。plugin 装好后持久生效，且本版本基于 transcript 实时估算、不依赖临时计数器文件，重启不丢。

Q：命令为什么是 /compact-tool:save 而非 /save？ A：plugin 命令带命名空间前缀，避免多插件冲突。

Q：和内置 /compact 有何区别？ A：/compact 只压缩；/compact-tool:save 先把进展存进记忆再压缩，信息更安全。

🗑 卸载

/plugin uninstall compact-tool@compact-tool

📄 License

MIT © 2026 hxy