Tome
Integrations

KOReader plugin

TomeSync is Tome's KOReader plugin. It records reading sessions (time, pages, device), syncs your position both ways with the web reader, lets you browse and download whole series from inside KOReader, and survives offline reading.

Reading time —

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.

KOReader + TomeSync Web reader in browser Tome server Your dashboard sessions + position sessions + position stats, series, library

Offline-first

Sessions queue locally on your device and flush to Tome the moment you're back online. Plane, metro, basement — no data lost.

Browse and download series

Open the wrench menu → TomeSync → Browse Series. Pick a series, hit "Download rest of series". Files arrive organised by book-type folder, properly named.

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.