Warning
This software is unfinished. Keep your expectations low.
A reading home for KOReader: browse your library, follow your reading habits, and collect achievements. Add an optional self-hosted dashboard to see your reading history in a browser.
The plugin works offline. KOReader handles document rendering, saved positions and reading activity.
Stable plugin release · VPS setup · Development
- A cozy pixel reading home, searchable local library and one-tap resume.
- Reading time, pages, streaks, daily journals and book details.
- Yearly heatmaps, monthly book timelines and reading goals.
- Book journeys, breaks and returns.
- 42 achievements with corner notifications and custom definitions.
- EPUB, PDF, MOBI, FB2, TXT and other formats supported by KOReader.
- Optional Go/Svelte dashboard with device pairing and automatic statistics sync over Wi-Fi.
Release status: v0.7.0 adds automatic background statistics sync over Wi-Fi, with quiet retries and a saved on/off toggle. Ongoing development is on develop. XP is reserved for future progression.
Requires a jailbroken Kindle with KOReader. Keep its Reading statistics plugin enabled. Other KOReader platforms have not been verified.
- Download the plugin release ZIP, or build a source checkout with
python3 scripts/build.py. - Fully exit KOReader, then connect the Kindle over USB.
- Copy the contents of
kindlevel.kopluginintokoreader/plugins/kindlevel.koplugin/, replacing shipped files while keeping personal files. Avoid nesting another plugin folder inside it. - Start KOReader and open Tools → Kindlevel. Check the version in Kindlevel's Settings footer.
Development builds also include kindlevel-recovery.koplugin: copy this folder beside the main plugin in koreader/plugins/. It provides a separate Tools → Kindlevel recovery menu for Wi-Fi repair and offline rollback, even if Kindlevel cannot load. See updates and recovery.
Three original sample books are included. Select your library through Settings → Choose books folder. For automatic opening, enable Show home on file browser entry and set KOReader's Start with option to file browser.
Kindlevel reads native statistics through read-only connections. Its goals and unlocks are stored separately; reading positions stay in KOReader's document settings.
On a VPS with Docker, Compose and Python 3, from a v0.7.0 source checkout:
sudo ./scripts/setup-server.sh http://YOUR_VPS_IPOpen the displayed address, create your account using the printed setup code, and select Your Kindle → Pair a Kindle. Install v0.7.0 or newer on the Kindle, then connect through Settings → Web dashboard. Statistics sync automatically while KOReader is awake and Wi-Fi is connected.
The server runs in one container with SQLite. HTTP does not encrypt login or sync traffic. Fresh-server setup, backups and troubleshooting.
Sync currently uploads book metadata, statistics and achievements. Book files, covers and highlights are planned. Connection details.
From v0.5.0, Settings → Check for updates installs newer stable GitHub releases over Wi-Fi. Older versions need one USB upgrade. Update guide.
Preview the actual plugin with Python 3.12+ and Docker:
python3 scripts/preview.pyOpen http://127.0.0.1:8765. For a local dashboard preview, run docker compose up --build -d and open http://localhost:8080.
Native reader flows are tested in KOReader's Linux ARM64 runtime; the dashboard is checked on desktop and mobile browsers. Physical device behavior still needs testing.
- Device testing and touch/e-ink tuning.
- Book files, covers and highlights synced with the self-hosted web app.
- Highlight review.
- XP, levels and character outfits.
- Reading suggestions based on available time.
Include your device, KOReader version, reproduction steps and relevant crash.log output in bug reports. Do not include device tokens, setup codes or personal databases.
Custom achievements · Developer guide
AGPL-3.0-or-later. Sample stories and badge artwork are original to this project. See NOTICE for attribution.