Hardcover Sync for KOReader

Your Hardcover library, right on your e-reader.

Track your reading on Hardcover, browse your shelves, and find your next book without leaving KOReader. Built for e-ink, with offline reading in mind.

Download the latest release · Changelog · Report an issue

Home	Reader panel	Book details
Save a quote	Write a note	Journal feed
Shelves	Vibes	For you recommendations
Community reviews	Reading goals	Reading stats

Captured from the current plugin in desktop KOReader at 1264 × 1680, 300 DPI (Kindle Paperwhite size). Real book covers from Open Library; sample account data. The reader backdrop uses a public-domain passage from The Time Machine.

What you can do

• Keep Hardcover up to date. Sync progress automatically or manually, change reading status, and rate books from the reader panel.
• Browse your library. Search Hardcover, sort your shelves, explore your own and followed lists, and discover recommendations through Vibes.
• Save quotes and take notes. Send highlighted passages to your journal, or write your own reflections with page numbers, tags, and privacy controls. The Journal feed brings them together with progress, finished books, and reviews. Saved entries work offline; new notes, quotes, and edits sync later.
• Go beyond the cover. Read synopses and community reviews, explore a series, and manage a book’s shelf and list membership.
• Keep reading offline. Progress and library changes queue for later sync. Shelves and lists are saved on-device; browsed reviews stay available offline too. Download covers ahead of time in Settings.
• Follow your progress. Create and edit reading goals, check your pace, and explore charts of your reading history, ratings, genres, and authors.

Install

1. Download hardcoversync.koplugin.zip from the latest release.
2. Extract it and copy the hardcoversync.koplugin folder into KOReader’s plugins folder.
3. Restart KOReader.

You can also install through the KOReader App Store plugin: search for Hardcover Sync. If it is hidden, enable include zero-star forks in the App Store settings.

Switching from the original plugin? Remove hardcoverapp.koplugin first: the two must not be installed together. Your settings carry over.

Get started

1. In KOReader’s file browser menu, choose Hardcover to open Home.
2. Open Settings → Account → Sign in to Hardcover. Follow the displayed web address on your phone or computer, enter the code, and approve. No API key or config file needed.
3. Open a book and choose Hardcover → Link this book in the reader menu. Search for the matching book and choose an edition if needed.
4. Use Status to mark it Currently Reading, then Progress to set your position and enable Track automatically if you want automatic updates.

Home’s bottom tabs open Library, Goals, and Stats. You can also assign Hardcover: Home to a KOReader gesture or quick menu.

Automatic linking by ISBN or Hardcover metadata, batch linking of books on your device, and sync frequency are available in Settings. Progress is mapped to the Hardcover edition’s page count, so page numbers may differ from KOReader’s.

Using Bookshelf 6.2? Its micro-module picker includes Hardcover reading memories, TBR rediscovery, authors read, books read, five-star books and rereads, alongside the goal and stats cards. Open Hardcover’s Stats screen once to load reading history, and Want to Read for TBR rediscovery. The cards then work offline; covers appear when cached. Totals cover your whole Hardcover history, not just this device. Memories shows this month in earlier years; TBR rediscovery chooses books added to Hardcover before this month that are still on Want to Read.

Each card’s Module settings applies only to that placement. Memories offers Window (This day, This week, This month) and Reach (Last year, All previous years). This week means the seven-day anniversary window centered on today. If a day has no match, it tries the week, then the month; an empty week tries the month. The header names the window actually used, and fallback never broadens Reach. Month-only finish dates qualify only for the month. Memories can show its cached cover and hide its rating; Memories and TBR can hide Another and independently choose the card’s tap action: book details, Stats/Want to Read, Hardcover Home, another saved book, or refresh from Hardcover. “Another” works offline; refresh needs internet and keeps saved data if the request fails. Goal cards can switch between bar and ring without replacing them, and totals can hide their icon. Existing placements keep their defaults.

Year in bars offers Layout (Upright columns or Stacked rows) and Metric (Pages or Books). Pages and upright columns remain the defaults. Stacked rows show monthly totals where space allows; short cells keep the bars and thin out labels. When page counts are unavailable, the chart keeps its existing fallback to books.

The four totals automatically put the icon above the number in portrait cards and beside it in square or wide cards. The Icon setting applies to both layouts; very small cards prioritize the number and label.

Advanced: use your own OAuth app or API token

Copy hardcover_config.example.lua to hardcover_config.lua in the plugin folder. Most users do not need this.

• Your own OAuth app: register a public app of type Mobile, desktop, or CLI, with Device Authorization Grant enabled. Allow read:catalog read:catalog:search read:me:content read:library read:social write:library, set client_id in the config, then sign in normally. If you change the client ID later, sign out and back in.
• Personal API token: get one from Hardcover’s API settings, set token, and leave client_id empty. Keep the file private and replace the token when it expires.

Development

Run ./spec/run_all.sh for syntax checks, specs, and harnesses. Render screens with spec/emu/run.sh; see the emulator guide for setup and scenarios. Build a release zip with ./spec/package_release.sh.

Credits & license

Built on Billiam’s hardcoverapp.koplugin. Thank you for the original tracking plugin.

Licensed under AGPL-3.0. The original plugin’s MIT notice is retained for the code inherited from it.