Features

• 📚 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

Screenshots

Quick Start

Install

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.

Usage

# 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-files

For all subcommands, options, environment variables, and examples, see the Configuration Guide.

Documentation

Development

Enable the repository's Git hooks after cloning:

git config core.hooksPath .githooks

Commit 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.

Credits

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.

Disclaimer

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.