KOReader plugin

TomeSync is Tome's purpose-built KOReader plugin — not a KOSync wrapper. Other self-hosted servers implement the KOSync protocol on the server and have you configure KOReader's built-in sync. TomeSync is a dedicated .koplugin that records reading sessions, syncs positions bidirectionally with the web reader, lets you browse and bulk-download series directly from your e-reader, and survives offline reading.

30-second install

1. In Tome, open Settings → KOReader.
2. Click Download Plugin. You'll get a .koplugin file pre-configured with your server URL and a fresh API key.
3. Drop it into KOReader's plugins/ folder.
4. Restart KOReader. TomeSync registers itself in the wrench menu.

What it does

Reading-session tracking

Every time you read, TomeSync records the session — start time, end time, pages turned, device. This is what powers the stats screens: streaks, time-of-day heatmaps, reading pace, completion estimates. Plain KOSync only syncs where you stopped; TomeSync tracks what you did to get there.

Bidirectional position sync

Read on KOReader in bed, pick up on the web reader in the morning, come back to KOReader the next night. Position follows you both directions automatically.

Highlights & notes sync

Highlights and notes you make in KOReader sync to Tome — and to your other KOReader devices. They also show up in a Highlights & Notes section on the book's detail page (the highlighted text, your note, and the chapter). The highlight's position is its identity, so the same passage marked on two devices is one highlight; edits resolve last-write-wins and deletes propagate (a highlight removed on one device won't reappear from another). Device-to-device sync needs both devices to have the Tome-served copy of the book.

The sync is bidirectional with the web reader too: device highlights are painted in Tome's built-in reader, and a highlight created on the web is adopted by KOReader at the book's next sync — the plugin locates the passage natively and turns it into a first-class KOReader highlight. Note edits and deletes made on the web win on every device at its next sync.

Ratings & reviews sync

KOReader has a native Book status screen with a 1–5 star rating and a review. The plugin keeps it in step with the rating and review on Tome's book detail page, both ways: rate a book on the web and it appears in KOReader the next time you open it (for a book that came from Tome); rate it in KOReader and it flows up to Tome when you close or suspend. Ratings are per user and private to you, and your reading status (reading / finished) is left untouched — that syncs separately. The plugin tracks the last value it synced, so normally only the side that changed is sent; if a rating changed on both the web and the device since the last sync, Tome wins.

Offline-first

When your server is unreachable, sync silently skips with zero delay — no freezing, no error dialogs. Sessions save to disk and flush automatically the next time you open the lid with a working connection. Up to 50 sessions can queue offline, surviving KOReader restarts. After 3 consecutive failures, the plugin backs off for the rest of the session to avoid unnecessary timeouts.

Series browser and bulk download

TomeSync lets you browse and download your library's series directly from KOReader — no browser needed.

From the home screen (no book open): open the wrench menu → TomeSync → Browse Series. A list shows every series in your library with book counts and authors. Tap a series to download all volumes at once.

From inside a book:

• Download full series — every book in the current book's series.
• Download rest of series — only volumes after your current one (based on series index).

Downloads are organized by book type and series: <home_dir>/<book_type>/<Series Name>/Vol. N — Title.ext (e.g. books/manga/One Piece/Vol. 1 — One Piece.epub). Format preference is epub → kepub.epub → cbz → pdf → mobi → azw3. Books already on the device are skipped. A live progress popup shows each download, and a summary reports downloaded/skipped/failed counts when finished.

Send to KOReader Beta

Browsing pulls books from the device; Send to KOReader pushes the other way — queue a book from the web and it lands on your e-reader, no email and no Amazon Send-to-Kindle. It's the KOReader-native counterpart to email send-to-device: the file arrives in its original format, filed into your library folders, instead of being converted and dropped into a stock reader you've bypassed.

On any book (or a multi-select on the dashboard), use the Send to KOReader split button — the caret still offers Send via email…. There's nothing to pair: it queues to your account's inbox, and every KOReader you've connected pulls from the same queue.

Delivery is not instant — it's a pull, not a push. The plugin shows an Inbox (N) badge in the TomeSync menu; queued books arrive the next time KOReader checks in (shortly after launch), or tap Inbox to pull them now. Each book is filed exactly like a series download — by book type and series, or under its author for standalones — and marked delivered once it's on the device.

When it syncs

TomeSync hooks into KOReader's lifecycle events:

• Open a book — pulls the latest position from the server. If the server is ahead, jumps there. Also reconciles the book's rating.
• Every 50 page turns — heartbeat push of current position.
• Close the lid (suspend) — pushes position, highlights, and a rating set this session, and records a reading session.
• Open the lid (resume) — starts a new session, pushes position, flushes any queued offline sessions.
• Close a book — pushes final position, highlights, and a rating set this session, and records a session.

Sessions shorter than 10 seconds are filtered out.

Keeping the plugin updated

Once installed, TomeSync updates itself from your server — no re-download, no file copying. In KOReader's TomeSync menu:

• Check for updates — pulls the latest plugin from your server. If a newer build exists, it installs and asks you to restart KOReader.
• Auto-check on launch — opt-in toggle. When on, TomeSync quietly checks shortly after startup and prompts only when an update is available.

Your server URL, API key, and reading history carry over automatically — updates never touch them.

Stable book IDs (vs KOSync hashes)

KOSync identifies books by the MD5 of the file. Edit metadata, re-save, redownload — the hash changes and the sync history orphans. TomeSync uses Tome's canonical book ID, resolved from the filename via /api/tome-sync/resolve. Your reading history survives file changes.

Manual install (advanced)

If for some reason you want to install the plugin manually:

cd ~/.koreader/plugins
cp ~/Downloads/tomesync.koplugin.zip .
unzip tomesync.koplugin.zip

Troubleshooting

• "Test connection" fails — most often the server URL is wrong or the API key was revoked. Re-download the plugin from Settings.
• Reading sessions not showing in stats — sessions flush on next sync. Pull-to-refresh in KOReader's TomeSync menu.
• See full troubleshooting.