Book Companion Reader

by Volodymyr Pavlyshyn
5
4
3
2
1
Score: 50/100

Description

Obsidian plugin: read PDF and EPUB on desktop and mobile, with AI explanations, language learning, linked notes and handwriting.

Reviews

No reviews yet.

Stats

1
stars
68
downloads
0
forks
5
days
1
days
1
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
1
total issues
1
open issues
0
closed issues
8
commits

Latest Version

a day ago

Changelog

Version bump only, with no changes since 0.5.0 (iPhone & iPad AI answers through an Apple Shortcut).

README file from

Github

The reader on desktop with the AI panel, and on a phone

Why

E-readers let you tap a word to see what it means. This plugin brings that into Obsidian and goes further. It explains whole passages in context, rewrites hard sentences at your language level, and turns what you read into notes connected to the book, so every book grows a small knowledge system in your vault.

Features

📖 One reader for PDF and EPUB

  • EPUB: page turning like an e-reader (tap the edges, swipe or use the arrow keys) or scrolling. Choose text size, a serif, sans or theme font, and like-Obsidian, sepia, light or dark paper. Images and in-book links work.
  • PDF: crisp pages from Obsidian's own PDF engine, real text selection, zoom, the outline (table of contents) and Go to page. Dark paper darkens PDFs too.
  • Your place is remembered per book, and reading progress shows in the toolbar and the library.
  • Library (📚 ribbon icon): every PDF and EPUB in the vault on one shelf, with generated covers, progress, highlight and word counts, and search.

✨ AI on whatever you select

A toolbar appears over any selection:

Button What you get
Explain what the passage means in its context: references, idioms, why it matters
Simplify the passage rewritten for your level, hard sentences paired with easier versions, and a word list
Word for one to four words: meaning in this sentence, part of speech, translation, an example and easier synonyms
Translate into your native language, with a note on phrases that don't translate literally
Ask your own question, with the passage and its surroundings as context

You can also Study this page (summary, hard sentences and up to 12 words from what's on screen), ask anything about the book in the panel, and ask follow-up questions in the same thread. Answers render as Markdown and can be saved as notes with one tap.

🎓 Language learning

  • Set your native language, the language you're learning and your level (A1 to C2, or native).
  • More than one language? Add each with its own level, for example English C1 and German B1. A book's language is read from the EPUB, or you pick it in the reader's panel, and every explanation, simplification and word list then uses that language's level.
  • Explanations come in simple words of the language you're learning (more practice) or in your native language. You choose.

📚 Your library and the librarian cat

The 📚 ribbon icon opens a library with shelves, and everything you set there is written to each book's page, so it stays in your vault (and in Typed Graph) as plain notes.

  • Shelves: Reading now, Up next, Wishlist, Finished and Set aside, with progress bars, a Continue reading button and a status chip on every book (tap it to move the book).
  • Books without a file too: Add book puts a paper book, an audiobook or a title a friend mentioned on the shelves, with author, genres and why you want to read it. Later you can link a PDF or EPUB to it, and it stays one book. Book files you drop into the vault show up by themselves.
  • Rate and date: rate finished books with stars; start and finish dates are filled in for you. Opening a book from Up next or the wishlist starts it.
  • Reading goal: set how many books you want to finish this year in the settings and watch the bar fill.
  • Suggested to read: ask the librarian cat for books. It looks at what you finished (best rated first), what you're reading and what you want, skips what you waved away, and can focus on something shorter, more by authors I like, easier to read for my level (it knows your language level) or anything you type. Put a suggestion on Up next or the Wishlist, or say Not for me and it won't come back.
  • Library pages: Library pages creates Library, Currently reading, Up next, Wishlist, Suggested reading, Finished and Reading log notes in Books/Library/. They are made of live book-shelf blocks, so they update by themselves, and you can put the same blocks in any note:
```book-shelf
shelf: reading
```

Options: shelf: (reading, to-read, wishlist, finished, abandoned, suggested, all), view: (cards, list, stats), limit:, sort: (recent, title, rating, finished, author), year: and author:. Each author also gets a note listing their books.

  • With Typed Graph: books are Book notes with status, rating, started, finished, written_by and has_genre, so you can ask your library anything, for example which authors you've read most; the Reading log page includes ready-made queries.

🐱 Chat with the cat

Open the Cat tab in the reader panel and talk about the book with the little reading cat, like a book-club friend who is reading along.

  • Ask anything: What is happening on this page? Summarise what I've read so far. Quiz me on this chapter. What does the author mean here?
  • Select a passage and tap Cat to point it at that passage. The passage goes with your next message.
  • The cat sees the page you're on and the whole conversation so far, answers at your language level, and doesn't spoil what comes later.
  • Want to practise? Ask the cat to chat with you in the language you're learning; it will gently correct mistakes.
  • Every discussion is kept as a note in the book's Chats/ folder, linked from the book page under Discussions, with your questions and the cat's answers as callouts and links back to the page. The transcript is updated as you talk, and anything you write below it is kept. Pick an earlier discussion from the list to continue it.
  • On a phone, when your subscription can't be reached, the question goes to your chat app and you paste the answer back, as with the other AI features.

🃏 Flashcards and decks

  • Card (on any selected word) makes a flashcard in one tap: the word in its dictionary form (with the article for German nouns), the translation, a short meaning at your level, an example, and the sentence from the book with the word marked. The card links back to the exact page.
  • Words from Simplify and Study this page can be saved as cards too.
  • Decks: every book gets its own deck, and you can make topic decks (Sailing words, Legal German…) and move cards between them. Choose where new cards go from the Words tab.
  • Practise with a built-in spaced-repetition trainer: see the word in its sentence, show the answer, then Again, Good or Easy. Cards come back after 1, 3, 7, 14 and 30 days. Keys: Space to reveal, 1 2 3 to answer. Works the same on phones.
  • The Flashcards view (ribbon icon 🗂) lists decks with how many cards are due, lets you browse, edit, search and delete cards, and add your own.
  • Book decks also keep a flashcard note (word :: meaning, tagged #flashcards) in the book's folder, and any deck can be saved as a note for the Spaced Repetition plugin.

🗂️ A small system around every book

Each book gets a folder (default Books/<Title>/) containing:

  • a book page with title, author, status, progress, start and last-read dates, and sections for Highlights, Notes, Handwriting, Vocabulary, AI explanations, Discussions and your reading status, rating and dates
  • Chats/: your discussions with the cat, one note each
  • Notes/: one note per thought, with the quote and a link back to the exact spot
  • Handwriting/: your handwritten pages as SVG
  • Vocabulary – <Title>.md: your flashcards

Every entry links back into the book through obsidian://book-reader?file=…&loc=p12, and opening the link jumps to that page.

✍️ Handwriting

  • Write on PDF pages with a pen, highlighter and eraser, five colours, and undo/redo. Strokes stay on their page.
  • Handwritten notes on lined, dotted or blank paper, about the page or a selection. Saved as SVG and embedded in a note. Edit handwriting from the file menu reopens them for more writing.
  • Pen pressure for Apple Pencil, S Pen and other styluses. With pen only on, the stylus draws and your finger scrolls, so a resting palm makes no marks.

📱 Same on phone and desktop

Built for Obsidian mobile from the start: big touch targets, swipe page turns, and the companion panel as a bottom sheet. Nothing needs a desktop except the optional subscription apps described below.

AI: use what you already have

Pick it in Settings → Book Companion Reader → AI service.

Option Where What you need
My Claude subscription (default) computer Claude Code installed; run claude once to sign in with your Claude Pro/Max account
My ChatGPT subscription computer Codex CLI; run codex once to sign in with ChatGPT Plus/Pro
My Google account (Gemini) computer Gemini CLI, signed in. Since mid-2026 Google allows this only for work plans (Gemini Code Assist Standard/Enterprise); with a personal plan, use the chat app or a free Gemini API key
My chat app any device nothing: the question opens in the Claude, ChatGPT or Gemini app, and you paste the answer back
Shortcut (iPhone & iPad) iPhone, iPad a one-time Apple Shortcut using the Claude app's Ask Claude or iOS 26's Use Model → ChatGPT; answers come back by themselves (see below)
Anthropic / OpenAI / OpenRouter any device an API key
Ollama / OpenAI-compatible computer or your network a running local server

On a phone, the subscription options switch to chat-app hand-off automatically: tap Ask Claude, Ask ChatGPT or Ask Gemini, then Paste answer.

iPhone and iPad: answers through a Shortcut

On iOS and iPadOS the reader can skip the copy and paste. It sends the question to an Apple Shortcut, the Shortcut asks your Claude or ChatGPT app, which uses your own subscription, and the answer comes back into the reader by itself.

  1. In the Shortcuts app, make a new Shortcut called Book Companion AI. In its details, turn on Receive input for Text.
  2. Add the AI step:
    • Claude: add Ask Claude (from the Claude app) with Shortcut Input as the prompt.
    • ChatGPT: add Use Model (iOS 26), choose ChatGPT, with Shortcut Input as the request.
  3. Add Stop and Output with the AI's response.
  4. In Settings → Book Companion Reader, turn on Use a Shortcut on iPhone and iPad, then press Test on the phone.

This applies to the subscription options and to My chat app. If the Shortcut is missing, cancelled or fails, the usual Ask Claude / ChatGPT / Gemini buttons appear instead. Gemini's app can't return answers to Shortcuts yet, so it stays copy and paste.

Typed Graph turns your notes into a typed property graph that you can query with openCypher and explore in a graph view. The two plugins are designed to work as a pair:

  • With Typed Graph enabled, Typed notes switches on by itself (Settings → Typed Graph → When Typed Graph is on).
  • The book page becomes a Book from Typed Graph's library ontology (status, format and dates as properties), with written_by:: [[Author]] {role: "author"}.
  • Notes from a selection become ReadingNote + Quote, with note_on:: [[Book]] {loc: "p12"}, quoted_from:: [[Book]] and the page number.
  • Saved AI answers become Explanation with explains:: [[Book]] {loc, action}. Handwritten notes become Handwriting, and word lists become Vocabulary with vocabulary_of.
  • The schema notes are added for you: Types/Book Companion.md, plus Typed Graph's Library.md if your vault has no Book type yet (it is never declared twice).
  • Show in graph (Notes tab or command) opens the book page in Typed Graph's graph view.

For example:

```graph-query
MATCH (n)-[r:note_on|explains]->(b:Book)
RETURN b.title AS book, count(n) AS notes
ORDER BY notes DESC
```
```graph-query
MATCH (q:Quote)-[:quoted_from]->(b:Book)-[:written_by]->(a:Author)
RETURN a.title AS author, b.title AS book, q.title AS quote, q.page AS page
```

These notes are checked against Typed Graph's own engine: the test vault reads back as Books, Quotes, ReadingNotes, Explanations, Handwriting and Vocabulary with every edge in place.

Install

  1. Community plugins: Settings → Community plugins → Browse, search for Book Companion Reader, then install and enable it. Or open it in Obsidian.
  2. Also install Typed Graph for typed, queryable reading notes.
  3. BRAT (beta builds): Add a beta plugin → Volland/book-companion-reader.
  4. Manually: copy main.js, manifest.json and styles.css from the latest release to <vault>/.obsidian/plugins/book-companion-reader/, then reload Obsidian. From a clone: npm install && npm run build && cargo run -- --install "/path/to/vault".

Use

  • Open any .epub. For PDFs, use the file menu → Open in Book Reader, or turn on Open PDFs in this reader.
  • Select text and pick an action from the toolbar. Tap a highlight to explain it, add a note, recolour or remove it.
  • Toolbar: contents · previous/next · position · text and layout (EPUB) or zoom and ✏️ write on the page (PDF) · handwritten note · study this page · book page · companion panel.
  • Commands (assign your own hotkeys): explain, simplify or define the selection, continue reading, add a book, ask the librarian, open the library pages, chat with the cat, discuss the selection with the cat, make a flashcard, open flashcard decks, study flashcards that are due, highlight, new note, handwritten note, write on page, study this page, toggle panel, book page, show in Typed Graph, add book types to Typed Graph schema, next/previous page, contents, open library.

Disclosures

  • Network: text is sent only when you press an AI button, and only to the service you chose in settings: the selection, a little surrounding text, and your language and level settings. With the subscription options, it goes through that app on your computer. With My chat app, it opens in that app's website or app. With the iPhone/iPad Shortcut option, it goes to the Shortcuts app and the AI app your Shortcut uses, and the answer comes back through an obsidian://book-reader-answer link.
  • Accounts and payments: the plugin is free. AI features need an account with an AI service you choose (or a local model), and that service's own terms and prices apply.
  • Local programs (desktop only): the subscription options start the Claude Code, Codex or Gemini command line on your computer to ask your question. Nothing else is run.
  • Your files: the plugin writes only inside its books folder (default Books/) and, with typed notes on, two schema notes in your Typed Graph schema folder. Reading positions, highlights and page handwriting are kept in the plugin's own data. API keys are stored in plain text in the plugin's settings in your vault.
  • Internal API: Open PDFs in this reader uses an unofficial part of Obsidian to replace the built-in PDF viewer. It is off by default.

Development

src/            the plugin (TypeScript): reader view, PDF and EPUB renderers, AI client, notes, handwriting, Typed Graph schema
src/main.rs     a small launcher: preview, --screenshot, --self-test, --install <vault>
test/           a stand-in Obsidian API, a sample book and the self-test
preview/        the real reader running in a browser with the sample book (EPUB and PDF)
website/        the landing page (GitHub Pages)
npm install
npm run build                 # plugin + preview + self-test bundles
npm run selftest              # drives the reader through its core flows
cargo run                     # opens the preview in your browser
cargo run -- --install <vault>
npm run version:bump -- 0.2.0 # then commit and push a tag named 0.2.0 → the release workflow publishes it

License

MIT © Volodymyr Pavlyshyn. Not affiliated with Obsidian, Anthropic, OpenAI or Google.