- 📚 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-filesis 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
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.
# 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 |
| Authentication | Password authentication for serve mode |
| 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 |
| Syncthing Setups | Community-contributed device sync guides |
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.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
