Reading Buddy

Read an English book in your browser and discuss it with Claude Code or Codex CLI, which always know which sentence you are looking at.

Chrome tab (any web page)
  └─ extension: visible paragraphs + selected text ──POST──▶ hub (127.0.0.1:8737)
                                                               └─ MCP /mcp ──▶ Claude Code / Codex CLI
                                                                                 reading_now, reading_section,
                                                                                 reading_note, reading_list

• Pull-based, token-cheap. The extension keeps the hub up to date; the AI fetches "what is on screen" only when you ask a question (one call, ~1–2k tokens).

• Nothing leaves your machine. The hub listens on localhost only. No API keys: the AI is whatever CLI you already use.

• Works on any HTML page — the extension reads the DOM directly, so paywalled or login-only pages work too. No fetching or HTML parsing on the server.

• Several books at once. The hub remembers the last position per URL; each session can pin itself to one book with the book filter.

Setup

Requirements: macOS (launchd for the resident hub; the hub itself is plain Node), Node ≥ 20, Chrome.

git clone https://github.com/244t/reading-buddy && cd reading-buddy
npm install
npm run ext              # builds extension/dist
sh deploy/install.sh     # resident hub via launchd (or: npm run hub)

1. Extension: open chrome://extensions, enable Developer mode, Load unpacked → extension/dist. Reload any tab you were already reading (content scripts are not injected into existing tabs). The toolbar badge shows on once the hub receives data.

2. Claude Code:

   claude mcp add -s user --transport http reading-buddy http://127.0.0.1:8737/mcp
   cp -r skills/read ~/.claude/skills/     # adds the /read skill

3. Codex CLI (or any other MCP-capable agent):

   codex mcp add reading-buddy --url http://127.0.0.1:8737/mcp

   and add a few lines like these to your own AGENTS.md (global ~/.codex/AGENTS.md or per project):

   ## Reading partner
   The user reads books in Chrome. When they refer to what they are reading ("this sentence",
   "here", "this word"), call the MCP tool `reading_now` before answering; the selected text is
   what they mean. Use `reading_section` for questions beyond the screen, `reading_note` when
   they say "note this", and pass `book: "<url or title substring>"` if the session is about one book.

Check: select some text in the page, then curl -s localhost:8737/state.

Related MCP server: Co-Reading MCP

Usage

Open the book in Chrome, start claude anywhere, type /read (or /read sre-book to pin a book). The assistant confirms which page you are on, then answer questions like "what does toil mean in this sentence?" — it calls reading_now first and answers with the selected text and surrounding paragraphs in context. Say "note this" to append the conclusion to ~/.local/state/reading-buddy/notes/<page>.md.

The /read skill answers in Japanese by default; edit skills/read/SKILL.md to change the language or the discussion style.

MCP tools

book is a case-insensitive substring of the URL or title; omit it to use the tab you looked at last.

Configuration

Logs: ~/Library/Logs/reading-buddy-hub.log. Restart after editing the hub: launchctl kickstart -k gui/$(id -u)/com.reading-buddy.hub.

Development

npm run hub:dev                    # hub with reload (stop the launchd one first)
npm run watch -w extension         # rebuild extension on change, then click "reload" in chrome://extensions
npm run typecheck -w hub && npm run typecheck -w extension

License

MIT