npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

smartcompact

v0.1.10

Published

Compact long agent sessions earlier, at a finished piece of work, to cut cost without losing results (Claude Code, pi, Codex)

Readme

SmartCompact

English · 中文

npm GitHub stars License

SmartCompact 让编程 agent 的长会话早点压缩,挑在做完一件事之后的停顿处。 在 18~60 个连续开发任务上,成本降低 7%~44%,隐藏验收测试没有损失,会话越长省得越多。最长的一组(60 个任务,原生组上下文到 82 万~96 万)里,很早之前随口提到的细节,180 道记忆题少答对 6 道(测试报告)。

agent 每发一次请求,都要把整段上下文重新读一遍,上下文越长,每一步越贵。原生的自动压缩要等到快满了才触发(Claude Code 接近 100 万,Codex 可以配到 80 万),而且不看时机,常常发生在一件事做到一半的时候。SmartCompact 支持 Claude Code(终端和桌面 App)、Pi 和 Codex 命令行:

  • 挑对时机压缩。 上下文超过允许压缩线(默认 20 万)以后,只要上次压缩以来做完过一件事(一次提交、测试通过、任务完成),之后又没开始改文件,就在这一轮结束时压缩。
  • 不在做到一半时压缩。 只在一轮结束时判断,从不在一轮中间主动压缩;测试失败、构建失败或连续报错时先等着。还要等你空闲 3 分钟没发消息才压,来回讨论时不会被打断。
  • 不设自己的上限。 一直没做完一件事,多半是在干一件大活,这时正需要大上下文。插件不去打断,压缩按平台原生规则来,和没装插件时一样。
  • 用进度笔记接上。 改过的文件、最近的提交和测试结果、记下的用户要求和决定,以及模型最后一条回复,压缩后补回给模型。
  • 不做白费的压缩。 预计腾不出足够空间时不压缩,避免刚压缩完又压缩。

实验结果

同一个代码库、连续 18~30 个开发任务(后面的任务会修改前面任务的结果),每个平台装与不装各跑 3 次。验收由脚本跑模型看不到的隐藏测试;每轮结束问几道记忆题,包括很早之前随口提到的细节。

| 平台(模型) | 原生压缩点 | 成本 | 任务验收 | 记忆题 | |---|---|---|---|---| | Codex(gpt-6-astra) | 80 万 | −19% | 两组都 18/18 | 两组都 54/54 | | Pi(gpt-5.5) | 约 25.6 万 | −11%~−22% | 两组都 18/18 | 原生 51/54,插件 53/54 | | Claude Code(Haiku 5.5,30 个任务) | 接近 100 万 | −7%(波动较大) | 两组都 30/30 | 两组都 90/90 | | Claude Code(Haiku 5.5,60 个任务) | 接近 100 万 | −44% | 原生 59~60/60,插件 60/60 | 原生 180/180,插件 174/180 |

成本按各家价格比例折算成"缓存读取 token 当量"。原生压缩得越晚、会话涨得越快,省得越多;会话没超过 20 万时插件不起作用,也没有额外开销。压缩后模型要多花一些请求重新熟悉代码,这部分已计入上面的成本。样本小,只用了一个代码库和一种任务类型;方法、数据和局限见测试报告。

安装

Claude Code(2.1.295 及以上)

/plugin marketplace add coffeecoproject/SmartCompact
/plugin install smartcompact@smartcompact

装好后新开会话生效。/smartcompact pause 可以暂停当前会话的插件。

Pi

pi install npm:smartcompact

Pi 默认配置下,插件在一轮结束(agent_settled)时挑刚做完一件事的时机压缩。如果你把 reserveTokens 调大、让 Pi 的原生压缩提前,插件会在那个点按工作状态决定是否推迟。

Codex 命令行(0.162 及以上,Node.js 22.18 及以上)

codex plugin marketplace add coffeecoproject/SmartCompact
codex plugin add smartcompact@smartcompact

下次启动 Codex 时按提示信任插件的 4 个 hook。hook 会自己找 22.18 及以上的 Node.js(PATH、nvm、Homebrew,也可以用 SMARTCOMPACT_NODE 指定),找不到就什么都不做。更新时运行 codex plugin marketplace upgrade smartcompact,再执行一次上面的 codex plugin add。以前用 node scripts/codex.ts install 装过的,先在那份仓库里运行一次 node scripts/codex.ts uninstall,避免 hook 运行两遍。

Codex 的 hook 不能推迟一轮中间的压缩,所以插件在一轮结束时判断,需要压缩就通过 Codex 的共享后台服务(交互界面默认会用它)在会话空闲时发起。codex exec 默认不走共享后台服务,Codex App(ChatGPT.app)目前走不了,这时插件只补回进度笔记,压缩仍按 Codex 原生规则。想让它们早点压缩,可以在 config.toml 顶部加上 Codex 自带的 model_post_turn_compact_threshold_percent:上下文超过可用窗口的这个百分比时,在一轮结束后压缩(窗口 87.2 万时设 31,约 26 万;详见测试报告)。

参数

| 参数 | 默认 | 含义 | |---|---|---| | 允许压缩线 | 200000 | 超过它、做完过一件事后,在一轮结束时压缩 | | 最少腾出空间 | 60000 | 预计腾出的空间少于它时不压缩 | | 空闲等待 | 180 | 决定压缩后,等你空闲这么多秒才压;期间发了消息或命令就取消 |

  • Claude Code:插件配置项 allowLineTokens、minFreedTokens、compactIdleSeconds,留空用默认值。
  • Pi:命令行开关 --smartcompact-allow-line、--smartcompact-min-freed、--smartcompact-idle-seconds。
  • Codex:环境变量 SMARTCOMPACT_ALLOW_LINE、SMARTCOMPACT_MIN_FREED、SMARTCOMPACT_IDLE_SECONDS。

查看效果

  • Claude Code 和 Pi:/smartcompact(或 /smartcompact report)查看允许压缩线、原生压缩点、识别到的阶段节点和成本估算;/smartcompact pause / resume 暂停或恢复当前会话。模型还可以调用 checkpoint 工具记下用户的要求和决定,压缩后和进度笔记一起补回。
  • Codex:node ~/.codex/plugins/cache/smartcompact/smartcompact/<版本>/adapters/codex/report.ts <会话 ID>(Node.js 22.18 及以上),记录在 ~/.codex/smartcompact/。

常见问题

怎么判断"做完一件事"? 靠识别 agent 执行的命令。看的是上次压缩以来有没有做完过一件事,不要求正好在这一轮:一轮结束本身就是停顿点,非要等下一次提交,多半只是多花钱。但做完之后又开始改文件,就算在做下一件事,要等它做完。提交只要真的执行了 git commit 且工具调用没报错就算;测试命令接了管道(| tail)又没开 pipefail 时退出码不可信,不算测试结果。

压缩后模型会不会忘事? 随口提到的细节有时会丢。进度笔记只记文件、提交、测试和模型主动记下的要求和决定;用户要求单独一栏,不会因为后来记的内容多了被挤掉,超过 30 条才丢最旧的。用户在对话里随口交代的细节,靠压缩时要求摘要原样保留用户说过的具体信息。Pi 上这样做明显减少了丢失,但不能保证不丢。

会改 Claude Code 自己的设置吗? 不会,原生自动压缩点保持原样(接近 100 万)。0.1.2 及以前的版本会在会话里设置 CLAUDE_CODE_AUTO_COMPACT_WINDOW,把原生压缩点挪到约 26 万(子进程也会继承),并且到了那里不等做完一件事也压缩。0.1.3 去掉了这两点:大活不会再在固定大小处被打断。升级前就开着的会话还留着旧设置,新开一个会话就没有了。

上下文窗口小的模型有用吗? 只有原生压缩点比 20 万高出一截时才有用。窗口只有 20 万时,原生先压(Claude Code 约 16.7 万),插件根本不会出手。Codex 默认窗口 27.2 万,原生约 24.5 万压,插件只有 20 万~24.5 万这一小段可用,省得不多,除非把 model_auto_compact_token_limit 调高。允许压缩线可以调低(allowLineTokens、--smartcompact-allow-line、SMARTCOMPACT_ALLOW_LINE),但调低后的效果没有评测过。

怎么卸载?

  • Claude Code:/plugin uninstall smartcompact@smartcompact。
  • Pi:pi remove npm:smartcompact。
  • Codex:codex plugin remove smartcompact@smartcompact。

开发

sh scripts/check.sh

运行结构校验、core 依赖边界检查和全部测试。目录:

  • plugin/:Claude Code 插件;plugin/src/core/ 是和平台无关的决策、信号、进度笔记和成本估算,其他适配都复用它。
  • adapters/pi/、adapters/codex/:Pi 和 Codex 的适配。
  • eval/:对照评测脚本(Claude、Pi、Codex 各一个),任务格式见 eval/day.py;评测用的题目和隐藏测试来自内部项目,没有放进仓库。
  • DESIGN.md:设计说明;docs/TEST-REPORT.md:测试报告;docs/EVALUATION.md:对照评测的英文说明。

许可证

MIT,见 LICENSE。