- 📚 Library Overview (Books + Comics): Browse currently reading, completed, and unread books, comics, and other documents
- 🗂️ Metadata Entries: Browse KOReader reading data even without the original document, including PDF and DjVu sidecars; edit metadata, covers, and annotations when writeback is enabled
- 🗄️ Library Archives: Preserve reading data and covers after both the document and sidecar disappear; returning sources restore the entry automatically (details)
- 🎨 Modern UI: Clean design powered by Tailwind CSS with readable typography and responsive layout
- 📖 In-App Reader (EPUB/FB2/MOBI/CBZ): Open supported files directly in KoShelf with keyboard navigation, progress scrubber controls, and inline highlight notes
- 📝 Annotations, Highlights & Ratings: KOReader highlights, notes, ratings, and review notes together on each item’s details page, including page-numbered PDF annotations
- ✏️ Metadata Writeback: Edit annotations, review notes, ratings, reading status, custom metadata, and covers in KoShelf, with revision checks to prevent overwriting external changes and support for recoverable KOReader backups (serve mode, opt-in)
- 📊 Reading Statistics: Track your reading habits with detailed statistics including reading time, pages read, customizable activity heatmaps, and weekly breakdowns
- 📅 Reading Calendar: Monthly calendar view showing your reading activity with items read on each day and monthly statistics
- 🎉 Yearly Recap: Celebrate your reading year with a timeline of completions, monthly summaries (finished items, hours read), and rich per-item details
- 📈 Per-Item Statistics: Detailed statistics for each item including session count, average session duration, reading speed, last read date, and a page-level reading activity heatmap
- 🔍 Search & Filter: Search through your library by title, author, or series, with filters for reading status
- ⬇️ Original File Downloads: Download documents that are present, including formats KoShelf cannot parse or render; static exports support downloads with
--include-files - 🔐 Optional Authentication: Use password authentication with session management, or delegate authentication to explicitly trusted reverse proxies such as Home Assistant ingress or an SSO gateway (setup)
- 🚀 Static Site: Generates a complete static website you can host anywhere
- 🖥️ Server Mode: Built-in web server with live file watching, configurable bind address, and sub-path hosting through a trusted reverse proxy
- 📱 Responsive: Optimized for desktop, tablet, and mobile with adaptive grid layouts
Home Assistant — One-click install
Docker Compose — Community-maintained image via koshelf-docker. See the Installation Guide for a sample docker-compose.yml.
Prebuilt binaries — Download from the releases page (Linux GNU/musl, Windows MSVC, and macOS for x86_64 and ARM64).
For detailed installation instructions (building from source, first-time CLI guide, Windows Defender notes), see the Installation Guide.
# Start a web server (live file watching, requires --data-path)
koshelf serve -i ~/Library --data-path ~/koshelf-data
# Generate a static site
koshelf export ~/my-reading-site -i ~/Library
# Generate a static site with downloadable original files
koshelf export ~/my-reading-site -i ~/Library --include-filesFor all subcommands, options, environment variables, and examples, see the Configuration Guide.
| Guide | Description |
|---|---|
| Installation | Home Assistant, Docker, prebuilt binaries, building from source |
| Configuration | Subcommands, CLI options, environment variables, config file, examples |
| KoReader Setup | Metadata storage options (sdr/hashdocsettings/docsettings), deployment setup, reading statistics from multiple devices |
| Authentication | Password and trusted-proxy authentication, sub-path hosting, write protection |
| Supported Data | Supported formats and extracted metadata fields |
| Stable Page Metadata | KOReader stable page metadata & synthetic page scaling |
| Static Export | Generated site directory structure |
| API Reference | REST API endpoints, parameters, and response schemas |
| Releasing | Release tags, artifacts, signing, notarization, checksums, and attestations |
| Syncthing Setups | Community-contributed device sync guides |
Enable the repository's Git hooks after cloning:
git config core.hooksPath .githooksCommit messages must use the type(scope): description format, for example
feat(reader): add keyboard navigation. Add ! after the scope for a breaking
change, for example feat(api)!: remove deprecated endpoint.
Design and feature inspiration comes from KoInsight, an excellent alternative that focuses on reading statistics and can also act as a KOReader sync server.
The calendar view is powered by EventCalendar, a lightweight JavaScript event calendar library.
This was built for personal use and relies heavily on AI-generated code. While I've tested everything and use it daily, I take no responsibility for any issues you might encounter. Use at your own risk.