{"slug": "show-hn-bookshelf-book-quotes-that-appear-between-claude-code-and-codex-turns", "title": "Show HN: Bookshelf – book quotes that appear between Claude Code and Codex turns", "summary": "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.", "body_md": "**Book quotes that appear naturally inside your coding-agent sessions.**\n\nBookshelf 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.\n\nIt also includes a full terminal library, reading lists, search, and on-demand\nrelevant quotes. Those are the library behind the ambient moment, not the main\nevent. Shipped totals come from the catalog: see [catalog counts](/Amal-David/bookshelf/blob/main/docs/catalog-counts.md).\n\n[Visit the Bookshelf landing page](https://bookshelf-8dz.pages.dev/).\n\nAmbient mode is optional and off by default:\n\n```\nbookshelf ambient enable --cadence 5 --intent refactor\nbookshelf ambient status\nbookshelf ambient disable\n```\n\nInstalling 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.\n\nFor deliberate use, invoke the Bookshelf skill or run `bookshelf quote`\n\n,\n`bookshelf quote --intent refactor`\n\n, or `bookshelf feedback up|down`\n\n.\n\n`bookshelf quote --intent refactor`\n\nis the explicit on-demand path. Ambient\n`Stop`\n\nhooks use the equally explicit theme saved by `ambient enable --intent`\n\n;\nthey do not pretend a completed-turn event contains task context. Both paths\nmap an allow-listed intent to local tags. Neither reads commands, paths,\nprompts, transcripts, code, tool arguments, model output, or makes a network\ncall. Ambient delivery is optional, off by default, and fails closed when a\nsafe bounded quote is unavailable.\n\nRelevant 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.\n\nThe 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.\n\nBookshelf requires Python 3.10 or newer and has no runtime dependencies.\n\n```\npipx install git+https://github.com/Amal-David/bookshelf.git\n# After the first PyPI release:\n# pipx install ambient-bookshelf\n```\n\nThen run `bookshelf`\n\nto open the interactive library.\n\n```\ncodex plugin marketplace add Amal-David/bookshelf\ncodex plugin add bookshelf@bookshelf\n```\n\nBookshelf is packaged as a Codex plugin with a skill and a fail-soft `Stop`\n\nhook. Codex shares plugin configuration across its app and CLI surfaces; the\nhook returns a compact `systemMessage`\n\nwhen the local cadence is due.\n\nRun these inside Claude Code:\n\n```\n/plugin marketplace add Amal-David/bookshelf\n/plugin install bookshelf@bookshelf\n```\n\nThe marketplace validates strictly with Claude Code 2.1.212 and declares the\nsame optional `Stop`\n\ncadence used by the Codex integration.\n\n```\npi install git:github.com/Amal-David/bookshelf\n```\n\nPi 0.57 installs and lists the canonical skill plus its `agent_end`\n\nextension\nfrom an isolated home. A live native notification is not claimed.\n\n```\nhermes plugins install Amal-David/bookshelf --enable\n```\n\nHermes 0.16 installs and loads Bookshelf from a clean working directory,\nregistering the canonical skill plus its `transform_llm_output`\n\nhook. A live\nauthenticated turn and appended output are not claimed.\n\nBookshelf validates install, manifest, loader, and adapter behavior at the strongest locally available boundary for Codex, Claude Code, Pi, and Hermes.\n\nThe Codex and Claude hooks resolve their own installed plugin roots, and the\nskill's `scripts/quote.py`\n\nwrapper resolves the bundled Python package relative\nto itself; neither requires a globally installed `bookshelf`\n\ncommand. The old\nmanual `bookshelf/skill/hook.py`\n\nand `codex_notify.py`\n\npaths are compatibility\nadapters only and are deprecated for new installs.\n\n`protocol/ambient-companion-v1.schema.json`\n\nand its example are shipped as\ninert protocol data for integrators. Bookshelf does not import them at runtime\nand ambient delivery never makes network requests.\n\nThe [generated catalog counts](/Amal-David/bookshelf/blob/main/docs/catalog-counts.md) distinguish catalogued\nbooks from works referenced by quotes. Legacy records are explicitly marked\n`legacy-unverified`\n\n; 585 primary-source-linked v2 records remain pending human\nreview and retain their repository link, source locator, extraction-snapshot\ndigest, excerpt digest, rights, and review-pending metadata. Those source links\nwere not pinned to immutable commits, so the v2 records must not be described\nas source-verified.\nQuotes carry context tags used to prefer relevant entries for work such as\ndebugging, building, reviewing, or shipping. This is not a claim that all\nquotes are verified or curated.\nSee [DATA.md](/Amal-David/bookshelf/blob/main/DATA.md) for provenance and the correction policy.\n\n```\nbookshelf\n```\n\n| Key | Action |\n|---|---|\n`Up` / `Down` / `j` / `k` |\nNavigate |\n`Enter` / `Right` |\nOpen a book |\n`Tab` / `Shift+Tab` |\nCycle genres |\n`/` |\nSearch |\n`c` |\nOpen reading lists |\n`r` |\nPick a random book |\n`f` |\nToggle favorite |\n`m` |\nMark as read |\n`w` |\nAdd to want-to-read |\n`?` |\nShow help |\n`q` |\nGo back or quit |\n\nFavorites, reading lists, statistics, hook counters, and ambient settings remain\nlocal under the platform application-data directory named `bookshelf`\n\n.\n\n[Watch the full-resolution terminal demo](https://bookshelf-8dz.pages.dev/#demo).\n\nThe recording is an authenticated Claude Code 2.1.217 session with Opus 4.8 in\nthe disposable `rewrite-prod-in-rust-by-lunch`\n\ncrate. Claude reads the real\nREADME and Rust source, changes the risky rollback window from zero to 30\nminutes, runs the real Cargo test suite with both tests passing, writes its own\ndry deploy joke, and then triggers the actual Bookshelf `Stop`\n\nhook. The setup\nand tool work are compressed before a modest zoom and four-second highlighted\nhold on the quote. The account identifier is redacted; the agent's actions,\noutput, and single Stop event are otherwise untouched. Because the public\nplugin is Stop-only, it truthfully shows one quote per completed response.\n\nThe landing-page source lives in [ site/](/Amal-David/bookshelf/blob/main/site). It is built from the same\nforest, paper, and rose visual system as the demo.\n\n```\npython3 -m unittest discover -s tests -v\npython3 -m compileall -q bookshelf hooks scripts tests\npython3 -m pip wheel . --no-deps --no-build-isolation --wheel-dir dist\n```\n\nSee [CONTRIBUTING.md](/Amal-David/bookshelf/blob/main/CONTRIBUTING.md) for catalog corrections and code\ncontributions.\n\nThe application code is MIT licensed. Book titles, author names, summaries, and\nquoted text have separate provenance and rights considerations described in\n[DATA.md](/Amal-David/bookshelf/blob/main/DATA.md).", "url": "https://wpnews.pro/news/show-hn-bookshelf-book-quotes-that-appear-between-claude-code-and-codex-turns", "canonical_source": "https://github.com/Amal-David/bookshelf", "published_at": "2026-07-23 22:06:47+00:00", "updated_at": "2026-07-23 22:22:40.006725+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents"], "entities": ["Bookshelf", "Amal David", "Claude Code", "Codex", "Pi", "Hermes"], "alternates": {"html": "https://wpnews.pro/news/show-hn-bookshelf-book-quotes-that-appear-between-claude-code-and-codex-turns", "markdown": "https://wpnews.pro/news/show-hn-bookshelf-book-quotes-that-appear-between-claude-code-and-codex-turns.md", "text": "https://wpnews.pro/news/show-hn-bookshelf-book-quotes-that-appear-between-claude-code-and-codex-turns.txt", "jsonld": "https://wpnews.pro/news/show-hn-bookshelf-book-quotes-that-appear-between-claude-code-and-codex-turns.jsonld"}}