Show HN: Bookshelf – book quotes that appear between Claude Code and Codex turns

Bookshelf, a new open-source tool by developer Amal David, inserts curated book quotes into coding-agent sessions for Claude Code and Codex after every few completed turns, operating entirely locally without sending prompts, code, or transcripts anywhere. The tool includes a terminal library, reading lists, search, and on-demand quotes, with ambient mode optional and off by default, and requires Python 3.10 or newer with no runtime dependencies.

Book quotes that appear naturally 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 /Amal-David/bookshelf/blob/main/docs/catalog-counts.md . Visit the Bookshelf landing page https://bookshelf-8dz.pages.dev/ . Ambient mode is optional and off by default: bookshelf ambient enable --cadence 5 --intent refactor bookshelf ambient status bookshelf ambient disable 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 /Amal-David/bookshelf/blob/main/docs/catalog-counts.md 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 /Amal-David/bookshelf/blob/main/DATA.md for provenance and the correction policy. bookshelf | Key | Action | |---|---| Up / Down / j / k | Navigate | Enter / Right | Open a book | Tab / Shift+Tab | Cycle genres | / | Search | c | Open reading lists | r | Pick a random book | f | Toggle favorite | m | Mark as read | w | Add to want-to-read | ? | Show help | q | Go back or quit | 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 https://bookshelf-8dz.pages.dev/ 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/ /Amal-David/bookshelf/blob/main/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 /Amal-David/bookshelf/blob/main/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 /Amal-David/bookshelf/blob/main/DATA.md .