NickelInkSync: sync your reading position between Kobo, Tolino and KOReader

[rantanplan]

TL;DR: NickelInkSync keeps your place in sideloaded books in step across Kobo, Tolino and KOReader (Kindle: experimental, read-only), using a plain KOSync server. 0.1.0 is out: desktop client + CLI for macOS and Windows, and an experimental on-device plugin for Kobo (firmware 6.0 and 4.x) and Tolino. MIT licensed.

Download: https://github.com/dkuester/NickelIn...ses/tag/v0.1.0

• Kobalt users, please read this first. The plugin switches itself off while Kobalt is installed, so the two never write your reading positions at the same time. You will see one message, "NickelInkSync ist aus", about 20 seconds after the device starts, and a line in the log at every start. Remove Kobalt and the plugin works again after the next restart.
• You can override this (create an empty file `.adds/NickelInkSync/ignore-kobalt`), but then you must turn off Kobalt's own KOSync first. Two syncers writing positions into the same database will fight each other and can corrupt your progress. If you are unsure, don't override.

What it does

Books you copy over USB have no cloud, so each reader only knows its own position. NickelInkSync talks the KOSync protocol (the one KOReader uses), so a Kobo, a Tolino and KOReader can share one progress per book.

- Desktop client and CLI (macOS, Windows): read the positions from a USB-mounted device, send them to your KOSync server, show device vs. server side by side, and write a newer server position back to the device (with a database backup first). Kepubs are matched to their original EPUB, so the same book gets the same identity on every device.
- On-device plugin (Kobo, Tolino; experimental): fetches the server position when you open a book and sends yours when you stop reading. Offline reading is queued and sent later. If a book moved on both sides, the plugin does nothing and tells you ("Konflikt, nicht geladen"); you settle it on the computer. A conflict dialog is planned.
- Tested and supported: Kobo Clara BW (6.0.279225), Kobo Libra 2 (4.38.23852), Tolino Shine Color (5.18.279364). Anything else is unchecked.

Why I built it

I read on several devices from different ecosystems (Kindle, Kobo, Tolino, and a Crosspoint-based XTeink X4), and sideloaded books don't sync their progress between them. For a while I used KOReader on all of them, but I found it too much and not friendly enough for everyday reading, so I wanted to keep each device's native reader and sync the position around it.

I started NickelInkSync before it was clear that [Kobalt](https://github.com/nicoverbruggen/kobalt) could solve many of these problems. It stays a hobby project either way. What I'm most proud of: I learned a lot through extensive device testing about how differently reading progress is stored and what to watch out for when syncing, and I found a way around books that have different MD5 hashes on different devices (a kepub vs. its original EPUB): a manual mapping. I still think that is really a problem the sync server should solve, but until it does, the mapping works.

Before you try it

- It is experimental. Back up `.kobo/KoboReader.sqlite` first. The tool also makes its own backups before writing, and `nickelinksync restore` puts one back.
- The device has to be "prepared" on the computer once (`device prepare` / "Prepare device"), otherwise the plugin only fetches and never sends.
- Not code-signed / notarized: macOS and Windows will warn on first start (steps in the release notes).
- Using NickelStorygraph? Use a current version so it chains correctly with NickelInkSync.

What's next

- 0.1.1: the conflict dialog, the plugin's own screens, Tolino alignment.
- 0.2.0: Kindle reading over MTP, bundled kepubify 5, usability quick wins (accessibility is a goal up to 1.0).
- 0.3.0 (plan only): write the reading progress back to the Kindle, behind a feasibility check.
- Linux AppImage later.

Feedback, bug reports and device test results are very welcome: https://github.com/dkuester/NickelInkSync/issues

AI disclaimer - I've tried to make this info available as obvious as possible. This plugin was only possible with the work of Claude.ai. Everything was architected and tested by me, but in the end I've left behind engineering 25 years ago. All of the test cases are documented and should also be visible in the pull requests.