Features

• 📚 Library Overview (Books + Comics): Displays your currently reading, completed, and unread items (ebooks + comics)
• 🎨 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: All your KoReader highlights, notes, star ratings, and review notes (summary note) are shown together on each book's details page
• ✏️ Metadata Writeback: Edit annotations, review notes, ratings, and reading status directly in KoShelf and sync changes back to your KOReader sidecar files (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 original item files from item detail pages, including static exports when --include-files is enabled
• 🔐 Optional Authentication: Password-protect server mode with session-based auth, login rate limiting, password rotation, and session management
• 🚀 Static Site: Generates a complete static website you can host anywhere
• 🖥️ Server Mode: Built-in web server with live file watching for use with 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 (Windows x64, macOS, Linux x64/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

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.