Show HN：Bookshelf——在 Claude Code 与 Codex 回合之间显示书籍引文

在你的编程 Agent 会话中显示的书籍引文。

Bookshelf 会在你的 Codex 或 Claude Code 会话中，每隔若干个已完成回合显示一条安静、拓宽视角的书籍引文。与其在 Agent 工作时盯着不断刷新的终端输出，你可以获得一次小小的文学重置——所有内容均在本地选择，不会将你的提示词、代码或转录内容发送到任何地方。

它还提供完整的终端书库、阅读列表、搜索和按需的相关引文功能。这些功能是环境展示时刻背后的书库，而非主要功能。已交付总数来自目录，参见目录统计。

访问 Bookshelf 落地页。

环境模式为可选功能，默认关闭：

bookshelf ambient enable --cadence 5 --intent refactor
bookshelf ambient status
bookshelf ambient disable

宿主程序和脚本也可通过环境变量按进程覆盖环境行为，无需编辑配置：BOOKSHELF_AMBIENT_ENABLED（1/0/true/false）、BOOKSHELF_AMBIENT_CADENCE（正整数）和 BOOKSHELF_DATA_HOME（将配置及环境状态重定向到其他目录）。环境变量值优先于已保存的配置；空值或无效值会被忽略。

安装 Agent 集成不会启用环境模式。适配器会处理自身错误，但 Bookshelf 不会对任何宿主回合做出绝对性声明。

如需有意使用，请调用 Bookshelf skill，或运行 bookshelf quote、bookshelf quote --intent refactor 或 bookshelf feedback up|down。

bookshelf quote --intent refactor 是明确的按需调用路径。环境 Stop hook 使用通过 ambient enable --intent 保存的同样明确的主题；它们不会假装一个已完成回合事件包含任务上下文。两条路径都会将允许列表中的 intent 映射到本地标签。两者均不会读取命令、路径、提示词、转录内容、代码、工具参数或模型输出，也不会发起网络请求。环境交付为可选功能，默认关闭；当没有可安全使用且长度受限的引文时，会以失败关闭的方式处理。

相关备选引文会在最近 50 条引文的窗口内轮换，避免重复。环境展示行限制为 220 个 UTF-8 字节和 32 个由空白字符分隔的单词；显式按需命令则保留更宽松的紧凑展示预算。

版本化的 176 用例评估，是针对该意图到标签映射及确定性排序器编写的回归契约。其精度指标用于捕捉排序漂移；这并非关于文学相关性或语义相关性的人类评分声明。

Bookshelf 需要 Python 3.10 或更新版本，且没有运行时依赖。

pipx install git+https://github.com/Amal-David/bookshelf.git
# After the first PyPI release:
# pipx install ambient-bookshelf

随后运行 bookshelf 打开交互式书库。

codex plugin marketplace add Amal-David/bookshelf
codex plugin add bookshelf@bookshelf

Bookshelf 被打包为一个 Codex plugin，包含一个 skill 和一个优雅降级的 Stop hook。Codex 在其应用和 CLI 界面间共享 plugin 配置；当本地节奏到期时，该 hook 会返回精简的 systemMessage。

在 Claude Code 中运行以下命令：

/plugin marketplace add Amal-David/bookshelf
/plugin install bookshelf@bookshelf

该 marketplace 已使用 Claude Code 2.1.212 进行严格验证，并声明了与 Codex 集成相同的可选 Stop 节奏。

pi install git:github.com/Amal-David/bookshelf

Pi 0.57 会从隔离的主目录安装并列出标准 skill 及其 agent_end 扩展。项目并未声明存在实时原生通知。

hermes plugins install Amal-David/bookshelf --enable

Hermes 0.16 会从干净的工作目录安装并加载 Bookshelf，注册标准 skill 及其 transform_llm_output hook。项目并未声明经过认证的实时回合或追加输出。

Bookshelf 在 Codex、Claude Code、Pi 和 Hermes 上，均在本地可用的最强边界验证安装、清单、加载器和适配器行为。

Codex 与 Claude hook 会解析各自已安装的 plugin 根目录，skill 的 scripts/quote.py 包装器则相对于自身解析随附的 Python 包；两者都不要求全局安装 bookshelf 命令。旧版手动 bookshelf/skill/hook.py 和 codex_notify.py 路径仅为兼容性适配器，已不建议用于新安装。

protocol/ambient-companion-v1.schema.json 及其示例作为惰性协议数据随项目提供，供集成方使用。Bookshelf 不会在运行时导入它们，环境交付也绝不会发起网络请求。

生成的目录统计区分已编目的书籍与被引文引用的作品。旧版记录被明确标记为 legacy-unverified；585 条带有主要来源链接的 v2 记录仍等待人工审查，并保留其仓库链接、来源定位信息、提取快照摘要、摘录摘要、权利信息和待审查元数据。这些来源链接并未固定到不可变的提交版本，因此不得将 v2 记录描述为已经过来源验证。引文带有上下文标签，用于优先匹配调试、构建、审查或交付等工作中的相关条目。这并非声称所有引文均已验证或经过策展。有关来源和更正政策，请参阅 DATA.md。

收藏、阅读列表、统计数据、hook 计数器和环境设置均保存在名为 bookshelf 的平台应用数据目录中。

观看全分辨率终端演示。

该录制内容是在一次经过认证的 Claude Code 2.1.217 会话中完成，使用 Opus 4.8，并在一次性 rewrite-prod-in-rust-by-lunch crate 中运行。Claude 读取真实的 README 与 Rust 源代码，将有风险的回滚窗口从零改为 30 分钟，运行真实的 Cargo 测试套件且两个测试均通过，写下它自己的干部署笑话，随后触发实际的 Bookshelf Stop hook。准备工作和工具操作经过压缩处理，之后画面适度放大，并对引文进行四秒高亮停留。账户标识符已被隐藏；除此以外，Agent 的操作、输出和单次 Stop 事件均未经修改。由于公开 plugin 仅支持 Stop，它如实展示每个已完成响应对应一条引文。

落地页源代码位于 site/。它采用与演示相同的森林、纸张和玫瑰视觉系统构建。

python3 -m unittest discover -s tests -v
python3 -m compileall -q bookshelf hooks scripts tests
python3 -m pip wheel . --no-deps --no-build-isolation --wheel-dir dist

有关目录更正和代码贡献，请参阅 CONTRIBUTING.md。

应用程序代码采用 MIT 许可证。书名、作者姓名、摘要和引文文本具有独立的来源与权利考量，详见 DATA.md。

Book quotes that appear inside your coding-agent sessions.

Bookshelf puts a quiet, perspective-widening book quote inside your Codex or Claude Code session every few completed turns. Instead of staring at terminal churn while an agent works, you get one small literary reset—selected locally, without sending your prompts, code, or transcript anywhere.

It also includes a full terminal library, reading lists, search, and on-demand relevant quotes. Those are the library behind the ambient moment, not the main event. Shipped totals come from the catalog: see catalog counts.

Visit the Bookshelf landing page.

Ambient mode is optional and off by default:

bookshelf ambient enable --cadence 5 --intent refactor
bookshelf ambient status
bookshelf ambient disable

Hosts and scripts can also override ambient behavior per process through the environment, no config edit needed: BOOKSHELF_AMBIENT_ENABLED (1/0/ true/false), BOOKSHELF_AMBIENT_CADENCE (positive integer), and BOOKSHELF_DATA_HOME (redirects config and ambient state to another directory). Environment values win over saved config; blank or invalid values are ignored.

Installing an agent integration does not enable ambient mode. Adapters contain their own errors, but Bookshelf does not make an absolute claim about any host turn.

For deliberate use, invoke the Bookshelf skill or run bookshelf quote, bookshelf quote --intent refactor, or bookshelf feedback up|down.

bookshelf quote --intent refactor is the explicit on-demand path. Ambient Stop hooks use the equally explicit theme saved by ambient enable --intent; they do not pretend a completed-turn event contains task context. Both paths map an allow-listed intent to local tags. Neither reads commands, paths, prompts, transcripts, code, tool arguments, model output, or makes a network call. Ambient delivery is optional, off by default, and fails closed when a safe bounded quote is unavailable.

Relevant alternatives rotate before repeats inside a 50-quote recent window. Ambient lines are capped at 220 UTF-8 bytes and 32 whitespace-delimited words; the explicit on-demand command retains its wider compact-display budget.

The versioned 176-case evaluation is an authored regression contract for that intent-to-tag mapping and the deterministic ranker. Its precision metrics catch ranking drift; they are not a human-rated claim of literary or semantic relevance.

Bookshelf requires Python 3.10 or newer and has no runtime dependencies.

pipx install git+https://github.com/Amal-David/bookshelf.git
# After the first PyPI release:
# pipx install ambient-bookshelf

Then run bookshelf to open the interactive library.

codex plugin marketplace add Amal-David/bookshelf
codex plugin add bookshelf@bookshelf

Bookshelf is packaged as a Codex plugin with a skill and a fail-soft Stop hook. Codex shares plugin configuration across its app and CLI surfaces; the hook returns a compact systemMessage when the local cadence is due.

Run these inside Claude Code:

/plugin marketplace add Amal-David/bookshelf
/plugin install bookshelf@bookshelf

The marketplace validates strictly with Claude Code 2.1.212 and declares the same optional Stop cadence used by the Codex integration.

pi install git:github.com/Amal-David/bookshelf

Pi 0.57 installs and lists the canonical skill plus its agent_end extension from an isolated home. A live native notification is not claimed.

hermes plugins install Amal-David/bookshelf --enable

Hermes 0.16 installs and loads Bookshelf from a clean working directory, registering the canonical skill plus its transform_llm_output hook. A live authenticated turn and appended output are not claimed.

Bookshelf validates install, manifest, loader, and adapter behavior at the strongest locally available boundary for Codex, Claude Code, Pi, and Hermes.

The Codex and Claude hooks resolve their own installed plugin roots, and the skill's scripts/quote.py wrapper resolves the bundled Python package relative to itself; neither requires a globally installed bookshelf command. The old manual bookshelf/skill/hook.py and codex_notify.py paths are compatibility adapters only and are deprecated for new installs.

protocol/ambient-companion-v1.schema.json and its example are shipped as inert protocol data for integrators. Bookshelf does not import them at runtime and ambient delivery never makes network requests.

The generated catalog counts distinguish catalogued books from works referenced by quotes. Legacy records are explicitly marked legacy-unverified; 585 primary-source-linked v2 records remain pending human review and retain their repository link, source locator, extraction-snapshot digest, excerpt digest, rights, and review-pending metadata. Those source links were not pinned to immutable commits, so the v2 records must not be described as source-verified. Quotes carry context tags used to prefer relevant entries for work such as debugging, building, reviewing, or shipping. This is not a claim that all quotes are verified or curated. See DATA.md for provenance and the correction policy.

Favorites, reading lists, statistics, hook counters, and ambient settings remain local under the platform application-data directory named bookshelf.

Watch the full-resolution terminal demo.

The recording is an authenticated Claude Code 2.1.217 session with Opus 4.8 in the disposable rewrite-prod-in-rust-by-lunch crate. Claude reads the real README and Rust source, changes the risky rollback window from zero to 30 minutes, runs the real Cargo test suite with both tests passing, writes its own dry deploy joke, and then triggers the actual Bookshelf Stop hook. The setup and tool work are compressed before a modest zoom and four-second highlighted hold on the quote. The account identifier is redacted; the agent's actions, output, and single Stop event are otherwise untouched. Because the public plugin is Stop-only, it truthfully shows one quote per completed response.

The landing-page source lives in site/. It is built from the same forest, paper, and rose visual system as the demo.

python3 -m unittest discover -s tests -v
python3 -m compileall -q bookshelf hooks scripts tests
python3 -m pip wheel . --no-deps --no-build-isolation --wheel-dir dist

See CONTRIBUTING.md for catalog corrections and code contributions.

The application code is MIT licensed. Book titles, author names, summaries, and quoted text have separate provenance and rights considerations described in DATA.md.