komga-readlists

Automatically build Komga read lists from the CBL reading orders you own in full — and keep them current as your library grows.

It pulls the community CBL reading-list collection, matches every reading order against your Komga library, and for each one where you own 100% of the issues, creates (or refreshes in place) a Komga read list in proper reading order. Reading orders you're missing issues from are skipped — and summarised in a coverage report so you can see exactly which ones you're closest to completing.

Why "complete only"?

A partial reading list is a frustrating reading experience — you hit a gap and the story stops. By only materialising the orders you own end-to-end, every read list in Komga is actually readable start to finish. As a downloader (Kapowarr, etc.) fills in the gaps, the next scheduled run notices the newly-complete orders and adds them automatically. The coverage report lists the near-complete ones (≥75%) so you know what to chase next.

How matching + refresh works

Each .cbl is sent to Komga's ComicRack matcher, which maps every entry to a book in your library. Completeness = every entry matched. Existing lists are updated in place (an atomic PATCH, no delete-then-recreate gap), so your curated lists are never at risk of being lost mid-update, and re-runs never create duplicates.

What it does

• Matches the full CBL reading-order collection against your Komga library
• Creates/refreshes a read list only where you own 100% of the issues, in reading order
• In-place refresh — no duplicates, no delete gap; lists grow as your library does
• Writes a coverage report (complete + near-complete with missing counts)
• Dry-run by default; designed for a weekly cron
• Stdlib-only Python, no dependencies

Roadmap

• Configurable completeness threshold (import near-complete orders too)
• Publisher/folder scoping
• Optional per-era "missing issues" export to feed a grabber

Built with Claude

This tool was built with the help of Claude (Anthropic's Claude Opus 4.8).

License

GPL-3.0-or-later. Copyleft — share improvements forward.