Repository navigation
Home
Jimmy Pautz edited this page Nov 5, 2026
·
32 revisions
This plugin brings Kindle-style X-Ray features to KOReader. It uses AI to track characters, build plot timelines, and provide historical context while you read.

- AI-Powered Insights: Supports Google Gemini (3.8 Flash, 3.6 Flash, 3.5 Flash Lite), OpenAI (GPT-6 Luna, GPT-5.6), DeepSeek (Flash & V4 Pro), Claude (Sonnet 5.5, Sonnet 5, Haiku 5.5), and Custom API providers (like OpenRouter).
- Phone & PC Quick Setup: Set API keys in seconds via QR code scanning or web browser with end-to-end zero-knowledge encryption, completely eliminating on-screen e-ink typing.
- Anthology & Short Story Collections: Full support for anthologies and story collections. Automatically detects story boundaries from the Table of Contents, scopes character lists, glossaries, and timelines to individual stories, disambiguates same-named characters across stories, and isolates duplicate scans.
- Character Tracking & Story Arcs: View bios, roles, and occupations. Track how characters and lore evolve across chapters with the interactive Story Arc progression viewer. Supports manual or automated Merging Duplicates with AI suggestions and consolidated summaries.
- Glossary & Terminology: Tracks special terms, items, factions, or concepts unique to the book's world (such as magic systems or sci-fi jargon).
- Series Context & Series Manager: Automatically detects books in a series (Book 2+) and fetches a recap of previous books to populate characters, locations, terms, and timeline data. Organize rosters, edit volume metadata, and support fractional indices (e.g. novellas numbered #1.5) with the built-in Manage Series tool.
- Customizable Detail & Font Scaling: Choose between short, default, or deep AI descriptions, and adjust popup font sizes to match your reading preferences.
- Linked Entries: Automatically connect related characters and locations through smart cross-referencing.
- Plot Timeline: Keeps track of major events chapter by chapter.
- Historical Context: Pulls real-world info for historical figures and locations.
- Mention Scanning: Find every occurrence of a character or location throughout the book for quick navigation, complete with page numbers and context snippets.
- Spoiler Protection, Intra-Chapter Gating & Prefetch Horizon: "Spoiler-free" mode guarantees future twists aren't revealed. State changes unlock at the exact intra-chapter page milestone, chapter timeline events remain hidden until you finish the chapter, and secret aliases remain masked from lookups until their reveal page. Enable the Offline Prefetch Horizon to pre-generate upcoming chapters (1–5 chapters ahead) or pre-generate the whole book with strict offline spoiler shielding.
- Auto Fetching & Clean Rebuild: Automatically fetches data in the background when you get to a new chapter with intelligent silent network route checks, plus an option to perform a clean data rebuild at any time.
- X-Ray Mode, Direct Open & Inline Fetching: Get instant lookups via inline footnote-style popups or traditional cards; enable Auto-Popup on Highlight for immediate lookup when selecting known entities; missing entries can be fetched on-the-fly.
- Unit Conversion: Automatically scans books for measurements (length, weight/mass, temperature, volume, speed, area) with non-blocking asynchronous background execution, book format filtering (Manga, Cookbooks, Poetry, etc.), instant cache restore, Cyrillic/written numbers recognition, and displays metric or imperial conversions in inline tooltips.
- Images & Maps Gallery: Browse illustrations, maps, and schematics in Mosaic, Grid, or List views. Features full-screen zoom, 360° rotation, color inversion for dark maps, background minimization, and cross-book series reference maps.
- Offline First: You only need internet to fetch the data initially. After that, everything is saved locally.
- Multilingual: Works in 19 languages, including English, German, French, Spanish, Brazilian Portuguese, Russian, Ukrainian, Turkish, Simplified Chinese, Dutch, Hungarian, Polish, Indonesian, Arabic, Italian, Serbian, Japanese, Slovak, and Czech (featuring declension-aware name matching).
- Get Started: How to install it and set up your API keys.
- API Key Setup Options: Comprehensive guide to all 5 methods of entering API keys (Phone/PC, QR code, Wi-Fi, text file drop, and on-screen).
- Core Content & Features: A look at Characters, Story Arcs, Timeline, Glossary, Series recap & Series Manager, and Images & Maps.
- Lookups & Navigation: In-text lookups, Direct Open auto-popups, footnote popup UI, font scaling, gestures, hardware keys, and Mention scanning.
- Data Management & Settings: Merging duplicates, Manage Series, verbosity settings, and language localization.
- AI Providers & Models: Details on supported APIs, models (including GPT-6 Luna), and reasoning effort.
- Spoiler Protection: How the plugin keeps you safe from spoilers, offline prefetch horizons, and extraction guardrails.
- Fetching Data: Guide to initial fetching, full-book pre-generation, background auto-updates, targeted fetching, and clean rebuilds.
- Advanced Configuration & Maintenance: Custom endpoints, config files, formats, logs, and maintenance tools.
- Community User Patches: Add-ons and KOReader user patches (e.g., Entity Footnotes in-text underlines).
If you run into any issues or have ideas for new features, feel free to open an issue on GitHub.