📚 AI reads books, page by page
Give it a book, and an AI reads it the way you would study one: one page at a time. PDF, EPUB, Word, Markdown and plain text all work.
On every page it writes down what it learned, each note tagged with its page number. Every 20 pages it stops and writes down what it understands so far. When it reaches the last page, it pulls the whole book together into one final summary. You watch it happen live in your terminal, page by page.
✨ Pick who reads: a plan you already have, or an API key
| You have | Run with | Set up once |
|---|
| A ChatGPT plan | --backend codex (Codex CLI) | codex login |
| A Claude plan | --backend claude (Claude Code) | run claude and sign in |
| A Grok plan | --backend grok (Grok Build) | grok login |
| An OpenAI API key | --backend openai (the default) | export OPENAI_API_KEY=... |
| An Anthropic API key | --backend anthropic | export ANTHROPIC_API_KEY=... |
| A Gemini API key | --backend gemini | export GEMINI_API_KEY=... |
| An xAI API key | --backend xai | export XAI_API_KEY=... |
| An OpenRouter key | --backend openrouter | export OPENROUTER_API_KEY=... |
A plan needs no API key: the reader uses the coding CLI that comes with it. Whichever you pick, it still reads one page per call, and the model only ever sees the page in front of it plus the reader's own notes. It never gets the book file, a shell, or any tools (see What the AI can see).
🚀 Quick start
git clone https://github.com/echohive42/AI-reads-books-page-by-page
cd AI-reads-books-page-by-page
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Then try 3 pages of the bundled meditations.pdf, starting at page 31 where Book One begins. Use the line for whatever you have:
python read_books.py --backend codex --start-page 31 --test-pages 3 # ChatGPT plan
python read_books.py --backend claude --start-page 31 --test-pages 3 # Claude plan
python read_books.py --backend grok --start-page 31 --test-pages 3 # Grok plan
python read_books.py --start-page 31 --test-pages 3 # OpenAI API key
python read_books.py --backend anthropic --start-page 31 --test-pages 3 # Anthropic API key
python read_books.py --backend gemini --start-page 31 --test-pages 3 # Gemini API key
python read_books.py --backend xai --start-page 31 --test-pages 3 # xAI API key
python read_books.py --backend openrouter --start-page 31 --test-pages 3 # OpenRouter key
When you are ready for a whole book:
python read_books.py path/to/your_book.pdf --backend codex
An .epub, .docx, .md or .txt file works the same way (see What it can read). Stop it any time with Ctrl+C. Every finished page is saved, and running the same command again carries on from where it stopped.
📖 What it can read
| File | How it is read | Its pages |
|---|
PDF (.pdf) | With PyMuPDF; add --ocr auto for scanned pages | The PDF's own pages |
EPUB (.epub) | The chapters in reading order, straight from the file | Reader pages |
Word (.docx) | The document's paragraphs | Reader pages |
Markdown (.md) and text (.txt) | As written | Reader pages |
EPUB, Word, Markdown and text are read directly with Python's standard library: no conversion to PDF, and nothing extra to install.
Reader pages. These formats have no fixed pages, because their text reflows to fit the screen. So the reader cuts them into pages of about 2,400 characters (roughly one printed page), always at a paragraph break, or at the end of a sentence inside a very long paragraph. The page numbers in the notes and summaries count these reader pages, not the pages of a printed edition. The same file always gives the same pages, so stopping and carrying on is safe.
Not read directly:
- Kindle files (
.mobi, .azw, .azw3): convert the book to EPUB first, for example with the free Calibre app, then read the .epub.
- Old Word files (
.doc): open it in Word or Pages and save it as .docx.
- Books with DRM: only DRM-free books can be read or converted.
✅ What has been tested
Being straight with you about what was run for real:
- Run on real pages (3 pages of
meditations.pdf, with a look back and a final summary): the Claude Code, Codex and Grok Build CLIs.
- EPUB, run on real pages (2 reader pages of a small EPUB made from the first chapter of the Meditations, with a final summary): Claude Code. Word, Markdown and text files go through the same page cutting and have offline tests, but no live run yet.
- Checked against each provider's official docs, but not yet run live: the OpenAI, Anthropic, Gemini, xAI and OpenRouter APIs. Each one has offline tests that run the real SDK and check the exact request the provider would receive and how its answers and errors are handled. The doc pages each backend follows are linked in
backends.py. For Gemini, its real answers to a wrong key, an unknown model and an account with no credit were checked live; no page has been read with it yet.
If you run one of the untested ones, an issue saying how it went would help everyone.
🧠 How it works
The idea is simple: read like a person, not like a search engine. Nobody understands a book by seeing all of it at once. You read a page, connect it to what you already know, and your understanding grows as you go.
Every page is its own model call. For page N, the reader sends:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
