dorkhub
show your thing

koassistant.koplugin

A powerful AI assistant integrated into KOReader.

zeeyado
Lua★ 175⑂ 8 forksGPL-3.0updated 2 days ago
chatgpt-apiclaude-aideepseeke-inke-readerereadergemini-apikoplugin
visit the demogit clone https://github.com/zeeyado/koassistant.koplugin.gitzeeyado/koassistant.koplugin
README.mdfork it — it’s yours

KOAssistant

GitHub Release License: GPL-3.0 Translation Status

Powerful, customizable AI assistant for KOReader.

New to KOAssistant? The Wiki has short getting-started guides. Help expand it.

Note: This README is the main documentation for now, and is being migrated to the Wiki. It was substantially refreshed in July 2026 to match the current code; if you spot anything out of date, or want to help with the wiki migration and docs cleanup, contributions are appreciated.

AI explains highlighted text X-Ray browser Dictionary integration Settings and menu

  • Highlight text → translate, explain, define words, analyze passages, connect ideas, save content directly to KOReader's highlight notes/annotations
  • Generate images → turn a highlight into an image using OpenAI, xAI, or Gemini image models; generated images are kept on-device in a browsable Generated Images gallery (tap to view, hold to delete) and associated with the book they came from
  • While reading → reference guides (summaries, browsable X-Ray with character tracking, cross-references, chapter distribution, Section X-Rays for focused chapter/part analysis, AI Wiki for per-item encyclopedia entries, local (offline) X-Ray lookup, X-Ray (Simple) prose overview from AI knowledge, recap, book info, notes analysis), analyze your highlights/annotations, explore the book/document (author, context, arguments, similar works), generate discussion questions
  • X-Ray that keeps up → optional Automatic X-Ray (per-book or global: background auto-update as you read, auto-create early in a book), checkpoints (pre-build spoiler-safe X-Ray versions for the whole book, snapped to chapter ends, silently swapped in as you read), and version history (browse, restore, or delete earlier X-Ray snapshots, with a keep-count setting)
  • Session controls (chips) → a configurable chip row in the input dialog — Domain, Web search, AI Book Tools, Quick Answer, Scope, Attach, and Spoiler-free — each tap-toggles for the current chat and hold-opens its defaults; choose which chips appear via the input gear menu
  • See its sources → a Show Sources viewer (web URLs, search queries, and book-tool lookups) alongside Show Reasoning, plus per-message "searched the web" and "searched the book" indicators
  • Research Mode → automatic academic enhancements for papers with DOI: discipline-agnostic academic X-Ray (7 research categories), web search override, research-aware system prompts. Zero configuration, DOI detection triggers everything
  • Notebooks → per-book markdown notebooks for curating AI insights and personal notes (including one-tap "Add to Notebook" from the highlight menu and other selection popups), with Obsidian vault integration (three save locations: alongside book, central folder, or custom folder like an Obsidian vault)
  • Library → scan-based actions (what to read next, reading patterns, discover new books), multi-book comparison, collection analysis, with an end-of-book suggestion popup
  • General chat → AI without book/document context
  • Web search → AI can search the web for current information (Anthropic, Gemini, OpenAI, xAI, Perplexity, OpenRouter), with an effort dial (quick / standard / thorough)
  • AI Book Tools → let the AI search and read the open book on demand to ground its answers (gather-then-generate by default, or an interactive agentic loop)
  • Multilingual → chat in any of 47 languages the AI understands, and use the KOAssistant UI in over 20 languages

19 built-in providers (Anthropic, OpenAI, Gemini, Ollama, and more) plus custom OpenAI-compatible providers. Fully configurable: custom actions, behaviors, domains, per-action model overrides. Reasoning/thinking is configured per model (stance dial + per-model overrides). One-tap auto-update keeps the plugin current. Personal reading data (highlights, annotations, notebooks) is opt-in, not sent to the AI unless you enable it.

Status: Active development. issues, discussions, and translations welcome. If you are somewhat technical and don't want to wait for tested releases, you can run off main branch to get the latest features. Breakage may happen. Also see Assistant Plugin; both can run side by side.

Table of Contents

User Essentials

New to KOAssistant? Start here for the fastest path to productivity:

  1. Quick Setup: Install, add API key, restart (5 minutes)
  2. Privacy Settings: Some features require opt-in; configure what data you share
  3. Recommended Setup: Configure gestures and explore key features (10 minutes)
  4. Free Tiers: Don't want to pay? See free provider options

You can also test your setup: Web inspector for experimenting

Want to go deeper? The rest of this README covers all features in detail.

Note: The README is intentionally verbose and somewhat repetitive to ensure you see all features and their nuances. Use the table of contents to jump to specific topics. A more concise structured documentation system is planned (contributions welcome).

Prefer a minimal footprint? KOAssistant is designed to stay out of your way. The main menu is tucked under Tools (page 2), and all default integrations (file browser buttons, highlight menu items, dictionary popup, gesture actions) can be disabled via Settings → Menus & Buttons. Use only what you need.

Quick Setup

Get started in 3 steps:

1. Install the Plugin

Download koassistant.koplugin.zip from the latest Release → Assets, or to run the latest from main branch: Code -> Download Zip, or clone the repo:

git clone https://github.com/zeeyado/koassistant.koplugin

Extract or copy the koassistant.koplugin folder to your KOReader plugins directory:

Kobo/Kindle:  /mnt/onboard/.adds/koreader/plugins/koassistant.koplugin/
Android:      /sdcard/koreader/plugins/koassistant.koplugin/
macOS:        ~/Library/Application Support/koreader/plugins/koassistant.koplugin/
Linux:        ~/.config/koreader/plugins/koassistant.koplugin/

For the plugin to be installed correctly, the file structure should look like this (no nested folder, and foldername must be koassistant.koplugin exactly; remove "-main" or similar if you downloaded the zip from head):

koreader
└── plugins
    └── koassistant.koplugin
        ├── _meta.lua
        ├── main.lua
        └── ...

This is the only time you need to install manually. After this, KOAssistant updates itself: when a new version is available, you'll see release notes with an "Update Now" button. One tap and it handles everything (download, install, preserve your settings). See Updating the Plugin for details.

Alternative: You can also install KOAssistant directly from within KOReader using the App Store plugin, which lets you browse, install, and update KOReader plugins without a computer. It can install from releases or from the latest main branch code.

2. Add Your API Key

Option A: Via Settings

  1. Go to Tools → KOAssistant → API Keys
  2. Tap any provider to enter your API key
  3. Keys are shown semi-blurred in your settings

Option B: Via Configuration File

Make a copy of apikeys.lua.sample and name it apikeys.lua

cp apikeys.lua.sample apikeys.lua

Edit apikeys.lua and add your API key(s):

return {
    anthropic = "your-key-here",  -- console.anthropic.com
    openai = "",                  -- platform.openai.com
    -- See apikeys.lua.sample for all 19 providers
}

Note: GUI-entered keys take priority over file-based keys. The API Keys menu shows [set] for GUI keys and (file) for keys from apikeys.lua. Provider pickers only list providers that have a key configured (plus local/no-key providers like Ollama), so the menus stay short.

See Supported Providers for full list with links to get API keys.

Free Options Available: Don't want to pay? Groq, Gemini, and Ollama offer free tiers. See Free Tier Providers.

3. Restart KOReader

Find KOAssistant Settings in: Tools → Page 2 → KOAssistant and follow the Setup Wizard.

4. Configure Privacy Settings (Optional)

Some features require opt-in to work. Go to Settings → Privacy & Data to configure. See Privacy & Data for details.

Quick option: Use Preset: Full to enable all data sharing at once. Text extraction is enabled separately.

Recommended Setup

Setup Wizard

On first launch, KOAssistant walks you through a 5-step setup wizard:

  1. Welcome: Brief introduction
  2. Language Setup: Detects your KOReader UI language and asks if you want to use it as your AI language. For non-English users, it confirms the detected language (e.g., "Use Français?"). For English users, it offers to keep English or choose a different language. You can also pick from the full list of 47 supported languages. This sets your primary interaction language for all AI responses, translations, and dictionary lookups.
  3. Emoji Display Test: Shows emoji icons used throughout the plugin. If they render correctly on your device, tap "Yes, enable" to turn on all emoji features (menu icons, panel icons, data access indicators). If you see blank boxes or question marks, tap "No, skip". See the Emoji Font Setup section for instructions on enabling emoji support in KOReader.
  4. Gesture Setup: Offers to assign Quick Settings and Quick Actions panels to tap bottom-right corner (or shows a tip if the gesture slot is already taken)
  5. Getting Started Tips: Pointers to privacy settings and action management

The wizard runs once and won't appear again. If you re-run the wizard (by resetting the setup flag), it skips the language step if you've already configured a language. You can always change language, emoji, and gesture settings later in Settings.

Getting Started Checklist

After the setup wizard, complete these steps for the best experience:

  • Configure privacy settings: Enable data sharing for features you want (Settings → Privacy & Data). See Privacy & Data
  • Set up gestures (if you skipped the wizard). See Configure Quick Access Gestures
  • Explore the highlight menu: 11 actions included by default (Translate, Look up in X-Ray, Explain, ELI5, Elaborate, Summarize, Connect, Fact Check, AI Wiki, Grammar, Counterpoint); add more via Manage Actions → hold action → "+ Highlight Menu", or via Settings → Menus & Buttons → Highlight Menu Actions
  • Try Dictionary Bypass: Single-word selections go straight to AI dictionary (Settings → Dictionary Settings → Bypass KOReader Dictionary)
  • Try Highlight Bypass: Multi-word selections trigger instant translation (Settings → Highlight Settings → Enable Highlight Bypass)
  • Set your languages (if you skipped the wizard): KOAssistant auto-detects from your KOReader UI language, but you can configure additional languages or change your primary (Settings → AI Language Settings)
  • Add custom actions to gestures: Any book/general action can become a gesture (Manage Actions → hold → "+ Gesture Menu", requires restart)
  • Pin actions to file browser: Add frequently-used book actions directly to the long-press menu (Manage Actions → hold → "+ File Browser")
  • Try Generate Image: Turn a highlighted passage into an AI-generated illustration (highlight menu → Generate Image; requires an OpenAI, xAI, or Gemini image model). See Image Generation

Tip: Edit built-in actions to always use the provider/model of your choice (regardless of your main settings); e.g. Dictionary actions benefit from a lighter model for speed.

Configure Quick Access Gestures

Automatic setup: The setup wizard offers to assign both panels to tap bottom-right corner: Quick Settings in the file browser and Quick Actions in the reader. Accept to set up both gestures automatically (requires KOReader restart). If the bottom-right corner is already assigned to another action, you'll get an informational tip instead.

Manual setup (same gesture, two contexts):

  1. In File Browser: Go to Settings → Gesture Manager, pick a gesture (e.g., tap bottom-right corner), select KOAssistant: Quick Settings
  2. In Reader (open any book or document): Go to Settings → Gesture Manager, pick the same gesture, select KOAssistant: Quick Actions

Now the same tap gives you Quick Settings in the file browser and Quick Actions while reading. Both panels include most functions you need, plus buttons to open Settings and other features. In reader mode, each panel has a button to switch to the other.

Recommended: Two Quick Access Panels

KOAssistant provides two distinct quick-access panels for different purposes:

1. Quick Settings (available everywhere)

Quick Settings panel

Assign "KOAssistant: Quick Settings" to a gesture for one-tap access to a two-column settings panel with commonly used options:

  • Provider & Model: Quick switching between AI providers and models
  • Behavior & Domain: Change communication style, knowledge context, and Research Mode
  • Temperature & Reasoning: Adjust creativity level, and set the reasoning stance (Minimal/Default/Maximum) or override the current model's reasoning (reasoning is per-model — the stance is a global preference each model honors as far as it can)
  • Web Search: Toggle AI web search on or off (this sets the global default; per-chat control lives in the input dialog's Web chip). Annotated "N/A" when the active provider can't search
  • Book Tools: Set the AI Book Tools posture (off / manual / auto) for the current book or globally, so the AI can look things up in the book to answer
  • Language: Set the primary response language
  • Translate & Dictionary: Translation and dictionary language settings
  • Highlight Bypass & Dictionary Bypass: Toggle bypass modes on/off
  • Text Extraction: Toggle book text extraction on/off (must be enabled once via Settings → Privacy & Data first)
  • Chat History, Browse Notebooks & Browse Artifacts: Quick access to saved chats, notebooks, and cached artifacts
  • Library Chat/Action: Launch library actions by selecting books from your reading history
  • General Chat/Action: Start a context-free conversation or run a general action
  • Continue Last Chat: Resume your most recent conversation
  • Manage Actions: Edit and configure your actions
  • More Settings...: Open the full settings menu

In reader mode, two additional buttons appear (items naturally shift to accommodate):

  • Book Chat/Action: Start a chat about the current book or access book actions
  • Quick Actions...: Switch to the Quick Actions panel for reading features

The panel has a gear icon (top-left) that opens a small menu with Sort Items (reorder and show/hide the tiles) and Align Buttons (left-align vs. centered). The same tile manager is also reachable via Settings → Menus & Buttons → Quick panels → Quick Settings Items.

2. Quick Actions (reader mode only)

Quick Actions panel

Assign "KOAssistant: Quick Actions" to a gesture for fast access to reading-related actions:

  • Default actions: X-Ray, Recap, About, Document Summary, Analyze Notes, Extract Key Insights, Key Arguments, Discussion Questions, Quiz, Suggest from Library
  • Artifact button: "View Artifacts" appears when any artifacts exist, opening a picker showing each cached artifact with progress % and age (e.g., "X-Ray (100%, 3d ago)"). The picker aggregates the per-action artifacts (X-Ray, X-Ray (Simple), Summary, Analysis, Recap, About, Analyze Notes) plus any pinned artifacts, a Generated Images entry (opens the per-book image gallery), and a Previous X-Ray Versions entry (archived X-Ray snapshots) when those exist
  • Utilities: Translate Page, Book Chat/Action, Continue Last Chat, General Chat/Action, Chat History, Notebook, View Artifacts, Book Settings, Quick Settings

You can add any book action to Quick Actions via Action Manager → hold action → "+ Quick Actions". The panel has a gear icon (top-left) that lets you choose between managing Panel Actions (reorder/remove actions) or Panel Utilities (show/hide/reorder utility buttons). These managers are also reachable via the hamburger menu in Manage Actions and via Settings → Menus & Buttons → Quick panels. Defaults can also be removed.

Tip: For quick access, assign Quick Settings and Quick Actions to their own gestures (e.g. corner tap). This gives you one-tap access to these panels from anywhere. Alternatively, you can add them to a KOReader QuickMenu alongside other actions (see below).

Alternative: Build a KOReader QuickMenu For full customization, assign multiple KOAssistant actions to one gesture and enable "Show as QuickMenu" to get a selection menu with any actions you want, in any order, mixed with non-KOAssistant actions:

  • Chat History, Continue Last Chat, General Chat/Action, Book Chat/Action
  • Toggle Dictionary Bypass, Toggle Highlight Bypass
  • Translate Page, Settings, etc.

Unlike KOAssistant's built-in panels (Quick Settings, Quick Actions) which show two buttons per row, KOReader's QuickMenu shows one button per row but allows mixing KOAssistant actions with any other KOReader actions.

Direct gesture assignments You can also assign individual actions directly to their own gestures for instant one-tap access:

  • "Translate Page" on a multiswipe for instant page translation
  • "Toggle Dictionary Bypass" on a tap corner if you frequently switch modes
  • "Continue Last Chat" for quickly resuming conversations

Add your own actions to gestures Any book or general action (built-in or custom) can be added to the gesture menu. See Custom Action Gestures for details.

Important: KOReader has two separate gesture configurations:

  • File Browser gestures: Configure from the file browser (Settings → Gesture Manager)
  • Reader gestures: Configure while a book or document is open (Settings → Gesture Manager)

You must set up gestures in both places if you want access from both contexts. Reader-only gestures (like Quick Actions, Translate Page, Book Chat/Action) will appear grayed out if you try to add them to File Browser gestures. This is expected. General gestures (like Quick Settings, Chat History) work in both contexts and can be added to either or both.

Key Features to Explore

After basic setup, explore these features to get the most out of KOAssistant:

Feature What it does Where to configure
Behaviors Control response style (concise, detailed, custom) Settings → Actions & Prompts → Manage Behaviors
Domains Add project-like context to conversations Settings → Actions & Prompts → Manage Domains
Actions Create your own prompts and workflows Settings → Actions & Prompts → Manage Actions
Quick Actions Fast access to reading actions while in a book or document Gesture → "KOAssistant: Quick Actions"
Research Mode Automatic academic enhancements when DOI detected (academic X-Ray, web search, research prompts) Automatic, no configuration needed
X-Ray Browser Browsable reference guide with Section X-Rays, AI Wiki, version history, chapter tracking Quick Actions → X-Ray
Highlight Menu Actions in highlight popup (11 defaults including Translate, Explain, ELI5) Settings → Menus & Buttons → Highlight Menu Actions
Image Generation Turn a highlighted passage into an AI-generated illustration Highlight menu → Generate Image
Notebooks Per-book markdown notes with Obsidian vault support Settings → Notebook Settings
Dictionary Integration AI-powered word lookups when selecting single words Settings → Dictionary Settings
Bypass Modes Instant AI actions without menus Settings → Dictionary/Highlight Settings
Reasoning/Thinking Per-model reasoning depth, via a global stance (Minimal/Default/Maximum) or per-model overrides Settings → Advanced → Reasoning
Backup & Reset Backup settings, restore, and reset options Settings → Backup & Reset
Languages Configure multilingual responses (native script pickers) Settings → AI Language Settings

See detailed sections below for each feature.

Tips for Better Results

  • Good document metadata improves AI responses. Use Calibre or similar tools to ensure titles, authors, and identifiers (including DOI for academic papers) are correct. DOI triggers Research Mode with academic X-Ray categories and web-enriched analysis.
  • Shorter tap duration makes text selection in KOReader easier: Settings → Taps and Gestures → Long-press interval
  • Choose models wisely: Fast models (like Haiku 4.5, Gemini 3.5-flash) for quick queries; powerful models (like Sonnet 5, Opus 4.8) for deeper analysis. You can set different models for different actions, see Tuning Built-in Actions.
  • Try different behavior styles: 23 built-in behaviors include provider-inspired styles (Claude, GPT, Gemini, Grok, DeepSeek, Perplexity), all work with any provider. Change via Quick Settings or Settings → Actions & Prompts → Manage Behaviors.
  • Combine behaviors with domains: Behavior controls how the AI communicates; Domain provides what context. Try Perplexity Style + a research domain for source-focused academic analysis.

Testing Your Setup

The test suite includes an interactive web inspector that lets you test and experiment with KOAssistant without launching KOReader:

What you can do:

  • Test API keys (Verify your credentials work before using on e-reader)
  • Experiment with settings (Try different behaviors, domains, temperature, reasoning)
  • Preview request structure (See exactly what's sent to each provider)
  • Actually call APIs (Send real requests and see responses in real-time)
  • Simulate all contexts (Highlight text, book metadata, library selections)
  • Try custom actions (Test your action prompts before using them on your device)
  • Load your actual domains (The inspector reads from your domains/ folder)
  • Send multi-turn conversations with a full chat interface and conversation history

Requirements:

  • Lua 5.3+ with LuaSocket, LuaSec, and dkjson
  • Clone from GitHub (Tests are excluded from release zips to keep downloads small)
  • See tests/README.md for full setup instructions

Quick Start:

cd /path/to/koassistant.koplugin
lua tests/inspect.lua --web
# Then open http://localhost:8080 in a browser

Tip: The web inspector reads from your actual KOAssistant settings (koassistant_settings.lua), so run KOReader on the same device/computer first to load your full configuration (languages, behavior, temperature, etc.).

Why use it:

  • Test actions and prompts comfortably on a computer before deploying to your e-reader
  • Have actual chats with your desired setup to see how it performs
  • Experiment with expensive reasoning models without UI overhead
  • Debug why a prompt isn't working as expected
  • Learn how different settings affect request structure
  • Validate custom providers and models
  • Compare model and provider performance

Privacy & Data

⚠️ Some features are opt-in. To protect your privacy, personal reading data (highlights, annotations, notebook) is NOT sent to AI providers by default. You must enable sharing in Settings → Privacy & Data if you want features like Analyze Notes or Connect with Notes to work fully. See Privacy Controls below.

KOAssistant sends data to AI providers to generate responses. This section explains what's shared and how to control it. This is not privacy theater: the "threat model" is simply users including sensitive data (annotations, notes, content) by accident. You are already being permissive by using online AIs at all, and this plugin encourages AI analysis of your reading material — and the available placeholders/template variables can carry a substantial amount of sensitive data. Advanced Stats (opt-in, off by default) accesses KOReader's Statistics plugin locally to derive reading engagement groups; see Design Choices for what this means and why it's opt-in. Best practice is to pick providers thoughtfully, and the very best practice is to use local or self-hosted solutions, e.g. Ollama.

What Gets Sent

Always sent (cannot be disabled):

  • Your question/prompt
  • Selected text (for highlight actions)

Sent by default: (for Actions using it)

  • Document metadata like title, author, identifiers (you can disable this in Action management by unchecking "Include book info")
  • Enabled system content, like user languages, domain, behavior, etc
  • Basic stats: reading progress (percentage), chapter title, chapters read count, time since last opened
  • The data used to calculate this (exact date you opened the document last, etc.) is local only

Opt-in (disabled by default):

  • Highlights: your highlighted text passages (separate from annotations)
  • Annotations: your highlighted text with personal notes attached, and the dates they were made
  • Notebook entries: your KOAssistant notebook for the book, with dates
  • Book text content: actual text from the document (for X-Ray, Recap, etc.)
  • Library catalog: book metadata from scanned folders: title, author, series, reading status, progress percentage, last read date. Only sent by library actions when library scanning is enabled with folders configured
  • Advanced stats: reading engagement data derived from KOReader's Statistics plugin: curated groups based on reading time and completion patterns (e.g. books read extensively, stalled reads, briefly started). Raw statistics (hours, session counts, pages per hour) are computed locally and never sent, only human-readable group labels reach the AI. Only used by library scan actions

Privacy Controls

Settings → Privacy & Data provides three quick presets:

Preset What it does
Default Basic stats (progress, chapter info) shared for context-aware features. Personal content (highlights, annotations, notebook) stays private. Advanced stats off.
Minimal Maximum privacy. Only your question and book metadata are sent. All stats (including basic stats), library scanning, and personal content disabled.
Full All data sharing enabled for full functionality, including advanced stats. Does not automatically enable text extraction (see below).

Individual toggles (under Data Sharing Controls):

  • Allow Annotation Notes: Your personal notes attached to highlights (default: OFF). Automatically enables Allow Highlights. Actions requesting annotations degrade gracefully: when this is off but Allow Highlights is on, they receive highlights-only data (labeled "My highlights so far:" instead of "My annotations:").
  • Allow Highlights: Your highlighted text passages (default: OFF). Used by X-Ray, Recap, and actions with {highlights} placeholders. Does not include personal notes. Grayed out when annotations is enabled (annotations implies highlights).
  • Allow Notebook: Notebook entries for the book (default: OFF)
  • Allow Basic Stats: Reading progress percentage, chapter title, chapters read count, time since last opened (default: ON). Used by X-Ray, Recap, and other context-aware features.
  • Allow Advanced Stats: Reading engagement data derived from KOReader's Statistics plugin (default: OFF). Shares curated groups based on reading time and completion patterns with library scan actions. Raw statistics never leave the device, only human-readable labels like "read extensively" or "started briefly" reach the AI. See Design Choices for details.

Library Settings (in Reading & Library):

  • Enable Library Scanning: Allow scanning configured folders for book metadata (default: OFF). Required for scan-based library actions (Next Read, Discover New, Analyze Library, Challenge My Taste) and the Suggest from Library book action
  • Permanent Scan Folders: Folders always scanned for library actions. You can also pick folders on the fly in the input dialog
  • The global toggle is an absolute gate: all library scanning (including on-the-fly folders picked in the input dialog) requires it to be enabled. Per-action use_library flag provides the second gate

Trusted Providers: Mark providers you fully trust (e.g., local Ollama) to bypass all data sharing controls AND text extraction AND the library scanning toggle. Trust is evaluated against the provider a request actually goes to — your active provider, or an action's own pinned provider if it has one — so pinning an action to a different provider never inherits trust it shouldn't. When that provider is trusted, all data types (highlights, annotations, notebook, reading progress, book text, and library catalog) are available without toggling individual settings. Trusted providers still require at least one folder (permanent or on-the-fly) for library scanning. Trust also satisfies the consent check that background features (such as Automatic X-Ray) run against — those can then extract text in the background without a per-request tap.

Graceful degradation: When you disable a data type, actions adapt automatically. Section placeholders like {highlights_section} simply disappear from prompts, so you don't need to modify your actions. For text extraction, most actions fall back to AI training knowledge; see Text Extraction and Double-gating for details.

Visibility tip: If your device supports emoji fonts, enable Emoji Data Access Indicators (Settings → Display Settings → Emoji) to see at a glance what data each action accesses: 📄 document text, 🔖 highlights, 📝 annotations, 📓 notebook, 📚 library, 📊 advanced stats, 🌐 web search, directly on action names throughout the UI.

Text Extraction and Double-gating

⚠️ Text extraction is OFF by default. To use features like X-Ray, Recap, and context-aware highlight actions with actual book content (rather than AI's training knowledge), you must enable it in Settings → Privacy & Data → Text Extraction → Allow Text Extraction.

Text extraction sends actual book/document content to the AI, enabling features like X-Ray, Recap, Document Summary/Analysis, and highlight actions like "Explain in Context" to analyze what you've read. Without it enabled, most actions gracefully fall back to the AI's training knowledge: the AI is explicitly told no document text was provided and asked to use what it knows about the work (or say so honestly if it doesn't recognize it). This works reasonably for well-known titles but will be inaccurate for obscure works, and basically unusable for research papers and articles the AI hasn't seen. Exception: X-Ray requires text extraction and blocks generation without it; use X-Ray (Simple) for a prose overview from AI knowledge.

Background features: this same consent covers background runs you opt into separately — Automatic X-Ray and X-Ray checkpoint builds extract text and spend tokens without a per-request confirmation. They re-check consent at fire time (revoking it stops them), their size is bounded by their own guards (the progress-gap window; incremental checkpoint steps), and the interactive truncation/size warnings don't apply: an oversized background extraction aborts the run instead of asking.

Tip: If you enable text extraction but don't want to send the whole document, you have finer-grained options: choose "Document summary" or a specific section in an action's source-selection popup, attach a text range with the Scope session chip on a freeform chat, or let AI Book Tools retrieve only the relevant passages (see AI Book Tools). Hidden Flows also exclude front matter, appendices, etc. from extraction.

Why it's off by default:

  1. Token costs and context window (primary reasons, and also why it is not automatically enabled by Privacy presets, even Full): Extracting book text uses significantly more context than you might expect. A full book can consume 60k+ tokens per request, which adds up quickly with paid APIs. Users should consciously opt into this cost. Large contexts also significantly degrade response quality, especially for follow up questions. That's why actions with source selection let you choose "Document summary" as an alternative: run your queries on a previously generated summary (~2-8K tokens) rather than the full document text.

  2. Content awareness (See double-gating below): For most users reading mainstream books, the text itself isn't privacy-sensitive. However, if you're reading something non-standard, subversive, controversial, or otherwise sensitive, you should be aware that the actual content is being sent to cloud AI providers. This is a secondary consideration for most users but important for some.

How to enable:

  1. Go to Settings → Privacy & Data → Text Extraction
  2. Enable "Allow Text Extraction" (the master toggle)
  3. Built-in actions (X-Ray, Recap, Explain in Context, Analyze in Context) already have the per-action flag enabled

Double-gating for custom actions: When you create a custom action from scratch, sensitive data requires both a global privacy setting AND a per-action permission flag. This prevents accidental data leakage if you use sensitive placeholders/template variables: enabling a global setting doesn't automatically expose that data in all your custom actions.

For built-in actions: You only need to enable the global setting. Built-in actions already have the appropriate per-action flags set. When you copy a built-in action, it inherits those flags.

The table below documents which flags are required for each data type (relevant when creating custom actions from scratch):

Data Type Global Setting Per-Action Flag
Book text Allow Text Extraction "Allow text extraction" checked
X-Ray analysis cache Allow Text Extraction if cache was built with text (+ Allow Highlights if cache was built with highlights) "Allow text extraction" (if cache used text) and "Allow highlight use" (if cache used highlights) checked
Analyze/Summary caches Allow Text Extraction if cache was built with text "Allow text extraction" (if cache used text) checked
Highlights Allow Highlights (or Allow Annotation Notes) "Allow highlight use" checked
Annotations Allow Annotation Notes (degrades to highlights when off but Allow Highlights is on) "Allow annotation use (notes)" checked
Notebook Allow Notebook "Allow notebook use" checked
Library catalog Enable Library Scanning + folders configured "Allow library use" checked
Advanced stats Allow Advanced Stats "Allow advanced stats" checked
Surrounding context* None (hard-capped 2000 chars) Field use_surrounding_context (no in-app checkbox): nil/omitted = follow the global Surrounding Context setting (the default for custom actions), true = always on (also auto-set when your prompt contains {surrounding_context}), false = never
Page text* None (single current page, exempt) Auto-inferred from a {page_text} placeholder

* Surrounding context is the text around a highlight (more than you actually selected). It has no global privacy gate because it is hard-capped at 2000 characters, but it is off by default: it only rides along when the global Surrounding Context mode (Settings → Highlight Settings → Surrounding Context, or per-book in Book Settings, or the Scope session chip) is set to Sentence / Paragraph(s) / Characters rather than "None". Per-action this is a tri-state value in the action's Lua definition (not an editor checkbox): leave use_surrounding_context unset to follow that setting, or set it to true/false in a custom action to pin it always-on or never. Page text is the single currently visible page and is likewise exempt from the global gate; it is included only when an action's prompt uses the {page_text} placeholder.

Tip: Enable Emoji Data Access Indicators to see which flags each action has directly on its name, no need to inspect action settings manually.

Privacy compromise for X-Ray: X-Ray, X-Ray (Simple), and Recap use highlights (not annotations). If you want them to see your highlighted passages but not personal notes, enable Allow Highlights only (leave Allow Annotation Notes off). If you prefer no personal data at all, leave both off: X-Ray and Recap analyze the book text alone, and X-Ray (Simple) uses AI knowledge alone.

Cache permission inheritance: When caches are built, they record what data was used. Actions that later reference cache placeholders inherit requirements based on what the cache actually contains:

  • Cache built without text extraction → No "Allow Text Extraction" needed (AI used training knowledge only)
  • Cache built with text extraction → "Allow Text Extraction" needed
  • X-Ray/Recap cache built without highlights → No "Allow Highlights" needed
  • X-Ray/Recap cache built with highlights → "Allow Highlights" (or "Allow Annotation Notes") also required

The artifact viewer shows "Based on AI training data knowledge" or "Based on extracted document text" so you always know what a cache contains. If you change privacy settings after building a cache (e.g., disable text extraction), actions may render the cache placeholder empty. To fix: either re-enable the required permissions, or regenerate the cache with your current settings.

Two text extraction types (determined by placeholder in your action prompt):

  • {book_text_section}: Extracts from start to your current reading position (used by X-Ray, Recap)
  • {full_document_section}: Extracts the entire document regardless of position (used by most text extraction actions including Explain in Context, Analyze in Context, Summarize, Document Analysis, and more)

See Troubleshooting → Text Extraction Not Working if you're having issues.

Local Processing

For maximum privacy, Ollama can run AI models entirely on your device(s):

  • Data never leaves your hardware
  • Works offline after model download
  • See Ollama's official docs for installation and FAQ for network setup (hosting on another machine)
  • Quick start: Install Ollama → ollama pull qwen2.5:0.5b → Select "Ollama" as provider in KOAssistant settings
  • For network hosting, change the endpoint in Settings → Provider → Base URL (e.g., http://192.168.1.100:11434/api/chat)

Other local options: LM Studio, llama.cpp, Jan, vLLM, KoboldCpp, and LocalAI all have one-tap presets: go to Settings → Provider → Quick setup: Local provider, pick your engine, and the name and URL are pre-filled. Just change localhost to your server's IP if it's on another machine. See Adding Custom Providers for details.

Anyone using local LLMs is encouraged to open Issues/Feature Requests/Discussions to help enhance support for local, privacy-focused usage.

Provider Policies

Cloud providers have their own data handling practices. Check their policies on data retention and model training. Remember that API policies are often different from web interface ones.

Design Choices

Library scanning is opt-in. When enabled (Settings → Reading & Library), KOAssistant scans configured folders for book metadata (title, author, series, reading status, progress, last read date) to power library-aware features like "What to read next?" and reading pattern analysis. Only catalog metadata is sent, not book content, highlights, or annotations. Library scanning is triple-gated: (1) global enable_library_scanning toggle, (2) at least one folder configured, and (3) per-action use_library flag. Trusted providers bypass the global toggle but still require configured folders.

Reading engagement data (Advanced Stats): KOReader's Statistics plugin collects extensive local data (reading time, pages per session, reading speed, session history, daily patterns). With Allow Advanced Stats enabled (Settings → Privacy & Data, default: OFF), KOAssistant queries this database locally to compute engagement groups: curated categories like "books read extensively" (complete + significant reading time), "stalled reads" (started but inactive for weeks), "briefly started" (opened but barely read), and "recently finished". These groups are exposed as template variables ({deep_reads_section}, {stalled_section}, etc.) for library scan actions to compose.

What reaches the AI: Only human-readable book lists, e.g., "The Brothers Karamazov" by Fyodor Dostoevsky (47 hours). Raw statistics (exact timestamps, pages per session, reading speed, session logs) are used for local computation only and never leave the device. The AI sees categorized book lists, not behavioral data.

Why opt-in: Reading patterns over time create a surprisingly detailed personal profile. Even the curated groups reveal information about reading habits: which books were abandoned, which consumed obsessively, which ignored for months. This warrants conscious opt-in rather than a default-on toggle.

How to Use KOAssistant

KOAssistant works in 4 contexts, each with its own set of built-in actions (12 library actions shown as 4 scan-based + 7 selection-based + 1 book-context action that uses library data):

Context Built-in Actions
Highlight Explain, ELI5, Summarize, Elaborate, Connect, Connect (With Notes), Explain in Context, Analyze in Context, Thematic Connection, Fact Check*, Counterpoint, Current Context*, Translate, AI Wiki, Grammar, Dictionary, Quick Define, Deep Analysis, Look up in X-Ray††
Book About, Find Similar, Suggest from Library†, About Author, Historical Context, Related Thinkers, Reviews*, X-Ray, X-Ray (Simple), Recap, Analyze Notes, Key Arguments, Counterarguments, Discussion Questions, Quiz, Reading Guide, Document Analysis, Document Summary, Extract Key Insights
Library Next Read‡, Discover New‡, Analyze Library‡, Challenge My Taste‡, Compare§, Find Common Themes§, Analyze Collection§, Quick Summaries§, Reading Order§, Recommend§, Analyze Notes§ⁿ
General News Update*

*Requires web search (Anthropic, Gemini, OpenAI, xAI, Perplexity, OpenRouter). News Update is available in gesture menu by default but not in the general input dialog. See Web Search and General Chat for details.

†Book-context action that also appears in end-of-book suggestion popup. Requires library scanning.

‡Scan-based library action, requires library scanning enabled with folders configured. Available immediately in the library dialog without selecting books.

§Selection-based library action, requires 2+ books selected via presets or history browser.

ⁿRequires Allow Highlights or Allow Annotation Notes. Reads per-book sidecar data (highlights, annotations, notes) across selected books.

††Local action, searches cached X-Ray data instantly, no AI call or network required. Only appears when the book has an X-Ray cache.

Note: A separate Generate Image button also appears in KOReader's highlight popup (see below). It is a standalone highlight-menu button rather than a KOAssistant action, so it is not listed in the table above.

You can customize these, create your own, or disable ones you don't use. See Actions for details.

Highlight Mode

Highlight menu with KOAssistant actions

Access: Highlight text in a document → tap "KOAssistant"

Quick Actions: You can add frequently-used actions directly to KOReader's highlight popup menu for faster access. Instead of going through the KOAssistant dialog, actions like "KOA: Explain" or "KOA: Translate" appear as separate buttons. See Highlight Menu Actions below.

Bypass Mode: Skip the highlight menu entirely and trigger your chosen action immediately when selecting text. See Highlight Bypass below.

Built-in Actions:

Action Description
Explain Detailed explanation of the passage
ELI5 Explain Like I'm 5 - simplified explanation
Summarize Concise summary of the text
Elaborate Expand on concepts, provide additional context and details
Connect Draw connections to other works, thinkers, and broader context
Connect (With Notes) Connect passage to your personal reading journey ⚠️ Requires: Allow Annotation Notes, Allow Notebook
Explain in Context Comprehension-focused: what the passage means, what leads up to it, and what it builds on. Source selection: full text, summary, AI knowledge, or Smart retrieval (AI searches the book)
Analyze in Context Reader-focused: connects the passage to your highlights, annotations, and the threads you've been tracking. Source selection: full text, summary, AI knowledge, or Smart retrieval (AI searches the book) ⚠️ Requires: Allow Annotation Notes, Allow Notebook
Thematic Connection Craft-focused: examines the author's technique (language, structure, imagery) and how the passage fits into the work's thematic architecture. Source selection: full text, summary, or AI knowledge
Fact Check Verify claims using web search ⚠️ Requires: Web Search
Counterpoint Argues against the selected passage in good faith and at full strength: the strongest objections to its claim, reasoning, and framing, and who would disagree. (Fact Check verifies accuracy; Counterpoint challenges the argument.)
Current Context Get latest information about a topic using web search ⚠️ Requires: Web Search
Translate Translate to your configured language
AI Wiki Wikipedia-style encyclopedia entry about the selected text, using AI knowledge. Cached as an artifact (same as X-Ray browser wiki entries). Uses web search if enabled globally. Available in dictionary popup by default
Dictionary Full dictionary entry: definition, etymology, synonyms, usage (also accessible via dictionary popup)
Quick Define Minimal lookup: brief definition only, no etymology or synonyms
Grammar Sentence-level grammatical breakdown: constituency parse plus word-by-word analysis with part of speech, morphological features, and structural role. Language-aware — e.g., Arabic responses use traditional grammatical terminology alongside modern linguistic labels.
Deep Analysis Linguistic deep-dive: morphology, word family, cognates, etymology path
Look up in X-Ray [Local] Instant search of cached X-Ray data for selected text, no AI call, works offline. Searches by name and alias across all X-Rays (main + sections). Single match shows full detail; multiple matches across X-Rays show a grouped results view. Available in highlight menu and dictionary popup. Only appears when the book has an X-Ray cache.

Generate Image: A separate Generate Image (KOA) button in the highlight popup turns the selected text into an image via an image-generation provider (OpenAI, xAI, or Gemini). It uses its own provider/model and settings (independent of your chat provider) and appears only when image generation is enabled and the effective provider supports it. Generated images are kept on device in data_dir/koassistant_images and collected in a Generated Images gallery (tap to view, hold to delete, or delete all), with a per-book association so each book's images also appear on its "View Artifacts" list and in the cross-book artifact browser. You can hide the button via Settings → Menus & Buttons ("Show Generate Image button"). See Image Generation for details.

Source selection:

Several actions let you choose which document source the AI uses when you trigger them. A unified popup combines scope (what part of the book) and source (what data to send) in a single dialog:

Scope (rows shown depend on the action, whether the book has a table of contents, and your reading position):

  • Full document: Use the entire document. For "up to current position" actions (like Recap), whose extraction already stops at your reading position, this row is labeled Up to current position (NN%) instead.
  • Up to current position (NN%): For whole-document actions, limits scope to what you've read so far (spoiler-safe).
  • Pick section…: Focus on a specific chapter or part via a hierarchical TOC picker. The selected section name appears below the scope buttons. Section results are stored as independent artifacts (e.g., "Section Key Arguments: Chapter 5")
  • From section… (to current position): From a chosen section up to your current reading position.
  • Pick section range…: A start section and an end section.
  • Current chapter / Current chapter so far: Quiz only.

Source:

  • Extract text: Sends the actual document text to the AI. Most accurate, but uses more tokens. Requires text extraction to be enabled. When scoped to a section, only that section's text is extracted.
  • Use summary: Uses a pre-generated summary (~2-8K tokens) instead of raw text. Much cheaper for repeated use or follow-up conversations. Requires generating the summary first via the Document Summary action. When scoped to a section, uses the section summary if available (or offers to generate one). If no summary exists, this option shows a "(generate first / enable text extraction first)" hint.
  • Smart retrieval (AI searches the book): Offered on Explain in Context and Analyze in Context in tools-capable sessions. Instead of extracting a fixed span, the AI uses the local book tools to gather the passages it decides are relevant, and those replace full-text extraction. Requires full scope and text-extraction consent (or a trusted provider); shown disabled with the reason otherwise. See AI Book Tools.
  • AI knowledge only: No document data sent. The AI uses its training knowledge of the work. Free and fast, but less accurate for obscure works.

Actions with source selection: Explain in Context, Analyze in Context, Thematic Connection, Key Arguments, Counterarguments, Discussion Questions, Quiz, Reading Guide, Extract Key Insights, Document Summary, Document Analysis, Recap. For highlight-context actions (Explain in Context, Analyze in Context, Thematic Connection), the scope controls the text extraction range around the highlighted passage. Document Summary and Document Analysis require text extraction (other sources are grayed out). Recap doesn't support section scoping (scope row is grayed with an explanation).

When to use each source:

  • Full text: Short to medium documents, one-off queries, when you need the AI to work from the actual text
  • Summary: Longer documents, repeated queries, extended conversations, when token cost matters
  • Smart retrieval: Long documents where you want targeted passages instead of one big extraction, and the AI to decide what's relevant to your question
  • AI knowledge: Well-known works where the AI has good training data, quick queries, where nuance and bias may not matter as much

How sources affect AI behavior:

These aren't just quality tiers; they change how the AI thinks. When you provide actual text, the AI shifts from recall mode to analytical mode. Instead of (only) reconstructing a work from memory (filtered through whatever patterns, emphasis, and blind spots its training absorbed), it's doing direct analysis on the material in front of it, parsing structure, tracing arguments, finding patterns in what's actually written. Training-era biases and editorial slant matter less (but still matter) when the AI is working from your text rather than its pre-trained impressions of it.

With AI knowledge only, the AI is essentially giving you its "remembered take" on a work, shaped by which reviews, summaries, and discussions dominated its training data. For canonical works, this is often good enough. But for anything where framing matters (political texts, contested histories, philosophical arguments, novel research), the difference between "analyze this passage" and "tell me about this work" can be substantial.

In short: Text extraction gives the AI a job to do on specific material. AI knowledge asks it what it thinks it knows.

Accessing summaries:

  • Quick Actions → Document Summary (shows View/Redo popup if summary exists, generates if not)
  • File browser → Long-press a book → "View Artifacts (KOA)" → pick any cached artifact. X-Ray opens in a browsable category menu; all others open in the text viewer.
  • Gesture → Add artifact actions to gesture menu via Action Manager (hold action → "Add to Gesture Menu")
  • Coverage: The viewer title shows coverage percentage if document was truncated (e.g., "Summary (78%)")

Tip: For documents you'll query multiple times, generate the summary proactively via the Document Summary action. All artifact actions produce viewable reference guides that are also browsable via "View Artifacts". See Document Artifacts.

What the AI sees: Your highlighted text, plus document metadata (title, author). Actions like "Explain in Context" and "Analyze in Context" also use extracted document text to understand the surrounding content. When surrounding-context is enabled (Settings → highlight context mode, a per-book override, or the session Scope chip), highlight requests can also include a bounded window of text around your selection. Custom actions can access reading progress, chapter info, your highlights/annotations, notebook, and extracted book text, depending on action settings and privacy preferences. See Template Variables for details.

Save to Note: After getting an AI response, tap the Save to Note button to save it directly as a KOReader highlight note attached to your selected text. See Save to Note for details.

Tip: Add frequently-used actions to the highlight menu (Action Manager → hold action → "Add to Highlight Menu") for quick access. Other enabled highlight actions remain available from the main "KOAssistant" entry in the highlight popup. From that input window, you can also add extra instructions to any action (e.g., "esp. the economic implications" or "in simple terms").

Book/Document Mode

About chat response

Access: Long-press a book in File Browser → "Chat/Action (KOA)" or while reading, use gesture or menu

Some actions work from the file browser (using only document metadata like title/author), while others require reading mode (using document state like progress, highlights, or extracted text). Reading-only actions are automatically hidden in file browser. You can pin frequently-used file browser actions directly to the long-press menu via Action Manager → hold action → "Add to File Browser", so they appear as one-tap buttons without opening the action selector. All file browser buttons (utilities + pinned actions + Chat/Action) are distributed across rows of up to 4 buttons each. Long-press any pinned action button to see its description.

Built-in Actions:

Action Description
About Overview, significance, and why to read it
Find Similar Recommendations for similar works. When library scanning is enabled, notes which you already own
About Author Author biography and writing style
Historical Context When written and historical significance. Adapts to work type (novel, manifesto, religious text, research paper)
Related Thinkers Intellectual landscape: influences, contemporaries, and connected thinkers
Reviews Find critical and reader reviews, awards, and reception ⚠️ Requires: Web Search
X-Ray Browsable reference guide: characters (with aliases and connections), locations, themes, lexicon, timeline. Opens in a structured menu with search (including cross-section search across all X-Rays), chapter/book mention tracking, per-item chapter distribution, AI Wiki per-item encyclopedia, Section X-Rays for focused chapter/part analysis, linkable cross-references, local lookup, and highlight integration. Supports Automatic X-Ray (background upkeep), checkpoints, and version history. ⚠️ Requires: Allow Text Extraction
X-Ray (Simple) Prose companion guide from AI knowledge: characters, themes, settings, key terms. No text extraction needed. Uses reading progress to avoid spoilers.
Recap "Previously on..." style summary to help you resume reading. Source selection: extracted text (with incremental updates) or AI knowledge. Use Hidden Flows to limit scope ⚠️ Best with: Allow Text Extraction
Analyze Notes Discover patterns and connections in your notes and highlights ⚠️ Requires: Allow Annotation Notes
Key Arguments Thesis, evidence, assumptions, and counterarguments. Source selection: full text, summary, or AI knowledge. Supports section scope
Counterarguments Prosecutes the case against the work: steelmanned opposing positions, the argument's weakest links, what would falsify it, and who disagrees and why. (Key Arguments maps the argument; this one argues back.) Source selection: full text, summary, or AI knowledge. Supports section scope. Saved as an artifact
Discussion Questions Comprehension, analytical, and interpretive prompts. Source selection: full text, summary, or AI knowledge. Supports section scope
Quiz Interactive comprehension quiz, one question at a time with answer selection, scoring, and review. Multiple choice (auto-graded), short answer and discussion (self-graded). Triggered automatically at chapter ends (configurable) or manually from Quick Actions with scope picker. Question types, count, and difficulty configurable in Settings. Result saved as artifact. Source selection: full text, summary, or AI knowledge. Supports section scope
Reading Guide Spoiler-free guide to what's ahead: threads in motion, patterns to notice, helpful background, how to approach the rest. Uses reading position to stay safe. Source selection: full text, summary, or AI knowledge. Supports section scope
Document Analysis Deep analysis: thesis, structure, key insights, audience. Saved as an Analysis artifact. Supports section scope. ⚠️ Requires: Allow Text Extraction
Document Summary Comprehensive summary. Saved as a Summary artifact, which other actions can use as their document source. Supports section scope. ⚠️ Requires: Allow Text Extraction
Extract Key Insights Distills the most important takeaways: ideas worth remembering, novel perspectives, actionable conclusions. Source selection: full text, summary, or AI knowledge. Supports section scope
Suggest from Library Suggests what to read next from your own library, based on the current book and your reading patterns. Also triggers in the end-of-book popup. ⚠️ Requires: Library scanning enabled

What the AI sees: Document metadata (title, author, DOI when detected). For Analyze Notes: your annotations. For full document actions: entire document text. For Suggest from Library: your library catalog (title, author, series, status, progress, last read date). For library scan actions with Advanced Stats enabled: curated engagement groups (book lists categorized by reading patterns, see Privacy & Data).

Research Mode

Research Mode adapts KOAssistant's prompts, X-Ray schema, and web search behavior for academic and research texts. It can activate automatically via DOI detection or be turned on manually for any book.

Triggering Research Mode:

Trigger How it works
DOI auto-detection When KOAssistant detects a DOI (Digital Object Identifier) in your document, Research Mode activates automatically
Per-book toggle Set manually via the Domain & Research picker, persists in the book's sidecar
Global setting Enable in Domain & Research picker (global target) or Settings, applies to all books without a per-book override
Per-action override Actions can force Research Mode on or off regardless of other settings

Resolution order: Action override > per-book setting > DOI auto-detection > global setting. Per-book "Off" explicitly suppresses Research Mode even if a DOI is detected.

What changes with Research Mode:

Enhancement What it does
Academic X-Ray Replaces fiction/non-fiction categories with 7 research-appropriate categories: Key Concepts, Foundations (intellectual lineage, paradigms), Methodology, Findings, Referenced Works (with aliases and connections), Technical Terms, Figures & Data
Academic Prompt Tracks About, Find Similar, and X-Ray (Simple) switch to research-oriented prompts (research context, methodology, cited works instead of characters/themes). Recap, Key Arguments, Discussion Questions, Quiz, Reading Guide, and Analyze Notes include expanded academic adaptation (methodology, evidence evaluation, field positioning)
Research Nudge System prompt addition guiding the AI to ground analysis in the provided text, verify claims via web search, and contextualize within the paper's field
Web Search Override Actions that normally have web search disabled (X-Ray, Summarize, etc.) follow your global web search setting instead: if web search is on globally, research texts get web-enriched analysis
DOI in Prompts When a DOI is detected, every book-context prompt includes it, helping the AI identify the exact paper and its citation context

How to enable Research Mode:

The toggle is inside the Domain & Research picker (the Domain button in the chat input dialog, or the Domain item in Quick Settings). Below the domain list, a "Research Mode" section appears:

  • Book target: Use global / On / Off, saved per-book
  • Global target: Off / On, applies to all books without a per-book override

This shares the same book/global target toggle as domain selection. Research Mode for the current book can also be set from Book Settings.

How DOI detection works:

  1. Cached result, instant (checked first)
  2. Document metadata, EPUB identifiers, PDF description/keywords
  3. First-page text scan, extracts page 1 text, finds DOI pattern, discards text (most reliable for PDFs)

DOI detection runs independently of the Research Mode toggle: the DOI is always available for {doi_clause} in prompts. The toggle only controls whether Research Mode behavior (nudge, prompt swaps, web override) activates.

The DOI is a public identifier (like a URL). Only the DOI string enters metadata: no document content leaves the device beyond what you've already opted into via privacy settings.

Academic X-Ray categories are discipline-agnostic: the prompt tells the AI to adapt categorization to the field (a physics paper has different natural categories than a sociology study or a philosophy paper). The browsable X-Ray browser works identically: category navigation, search, chapter appearances, AI Wiki, linkable cross-references, and all other features carry over. Academic X-Rays use the same two-track design (incremental vs complete) and support Section X-Rays.

Cache track consistency: When updating an existing artifact (e.g., "Update X-Ray to 50%"), the update respects the track the cache was originally built with: a non-fiction X-Ray stays non-fiction even if Research Mode is now on, and vice versa. "Redo" regenerates from scratch using the current Research Mode setting.

Tip: Good metadata matters. DOI detection works best when your documents have clean metadata. Use Calibre or your reference manager (Zotero, Mendeley) to ensure the DOI is in the document's identifier or description fields. For PDFs without metadata DOI, the first-page text scan catches most academic papers since publishers print the DOI on page 1. After the first action run, the detected DOI is cached: subsequent actions (including from the file browser) use the cached result instantly.

Tip: Research Mode without DOI. For academic books, textbooks, or research-adjacent texts that don't have a DOI, enable Research Mode manually via the Domain & Research picker. This gives you the academic X-Ray schema, research nudge, and web search override: everything except the DOI-specific prompt enrichment.

Reading Analysis Actions

These actions analyze your actual reading content. They require specific privacy settings to be enabled:

Action What it analyzes Privacy setting required
X-Ray Book text + highlights up to current position Allow Text Extraction (required), Allow Highlights (optional)
X-Ray (Simple) AI training knowledge + reading progress + highlights Allow Highlights (optional)
Recap Book text or AI knowledge (user choice) + highlights up to current position Allow Text Extraction (for extracted text), Allow Highlights
Analyze Notes Your highlights and annotations Allow Annotation Notes
Key Arguments Full text, summary, or AI knowledge (user choice) Allow Text Extraction (for full text/summary)
Discussion Questions Full text, summary, or AI knowledge (user choice) Allow Text Extraction (for full text/summary)
Quiz Full text, summary, or AI knowledge (user choice) Allow Text Extraction (for full text/summary)
Document Analysis Entire document or section (user choice) Allow Text Extraction
Document Summary Entire document or section (user choice) Allow Text Extraction
Extract Key Insights Full text, summary, or AI knowledge (user choice) Allow Text Extraction (for full text/summary)
Reading Guide Full text, summary, or AI knowledge (user choice) + reading progress Allow Text Extraction (for full text/summary)
About AI training knowledge (+ optional web search) None (web search optional)
Suggest from Library Library catalog + current book + reading progress Enable Library Scanning + folders configured
Next Read Library catalog + engagement groups (recently finished, stalled, briefly started) Enable Library Scanning + folders configured; Allow Advanced Stats (optional, enhances with engagement data)
Discover New Library catalog + engagement groups (deep reads, recently finished) Enable Library Scanning + folders configured; Allow Advanced Stats (optional)
Analyze Library Library catalog + all engagement groups Enable Library Scanning + folders configured; Allow Advanced Stats (optional)
Challenge My Taste Library catalog + all engagement groups Enable Library Scanning + folders configured; Allow Advanced Stats (optional)

⚠️ Privacy settings required: These actions won't have access to your reading data unless you enable the corresponding setting in Settings → Privacy & Data. Without text extraction enabled, actions with source selection show "AI knowledge only" as the available option. For other actions, the AI gracefully falls back to its training knowledge, with a "Response generated without: ..." notice in the chat. Exception: X-Ray requires text extraction and blocks generation without it: use X-Ray (Simple) for a prose overview from AI knowledge.

Tip: Highlight actions can also use text extraction. "Explain in Context" and "Analyze in Context" send the full document text ({full_document_section}) to understand your highlighted passage within the complete work. See Highlight Mode for details.

X-Ray, Document Summary, and Document Analysis require text extraction enabled (Settings → Privacy & Data → Text Extraction). Without it, generation is blocked with a message directing you to enable text extraction (or use X-Ray (Simple) as an alternative for X-Ray). If you've already generated a cached result and later disable text extraction, you can still view it but cannot regenerate or redo it.

X-Ray categories X-Ray item detail Chapter appearances X-Ray apps

The X-Ray action produces a structured JSON analysis that opens in a browsable category menu rather than a plain text document. The initial browsable menu concept was inspired by X-Ray Plugin for KOReader by 0zd3m1r. Chapter distribution, linkable connections, and local lookup features were informed by Dynamic X-Ray by smartscripts-nl, a comprehensive manual X-Ray system with curated character databases, live page markers, and a custom histogram widget. Our approach differs: KOAssistant uses AI generation instead of manual curation, and menu-based navigation instead of custom widgets, but DX demonstrated the value of per-item chapter tracking and cross-reference linking. The browser provides:

  • Category navigation: Cast, World, Ideas, Lexicon, Story Arc, Reader Engagement, Current State/Conclusion (fiction) or Key Figures, Core Concepts, Arguments, Terminology, Argument Development, Reader Engagement, Current Position/Conclusion (non-fiction) or Key Concepts, Foundations, Methodology, Findings, Referenced Works, Technical Terms, Figures & Data, Reader Engagement, Current Position/Conclusion (academic, see Research Mode), with item counts. Reader Engagement appears only when highlights were provided during generation. Current State/Current Position appears for incremental (spoiler-free) X-Rays; Conclusion appears for complete (entire document) X-Rays, see two-track design below.
  • Item detail: descriptions, AI-provided aliases (e.g., "Lizzy", "Miss Bennet", shown for all categories), connections/relationships, your highlights mentioning each item, custom search term editing, and AI Wiki generation
  • Linkable references: character connections and cross-category references (locations → characters, themes → characters, etc.) are tappable buttons that navigate directly to the referenced item's detail view. References are resolved across all categories using name, alias, and substring matching.
  • Mentions: unified chapter-navigable text matching. Opens to your current chapter by default, showing which X-Ray items (characters, locations, themes, lexicon, etc.) appear there with mention counts and category tags. A chapter picker at the top opens a KOReader-style hierarchical TOC with expand/collapse for nested chapters, auto-expands to the current chapter and bolds it; subsequent opens remember your last selection. Tap any entry at any depth (Part, Chapter, Section) to analyze that scope. Includes an "All Chapters (to X%)" aggregate option that scans from page 1 to the coverage boundary, plus an "All Chapters" option that reveals the entire book (bypassing per-chapter spoiler confirmations). Chapters beyond the greater of X-Ray coverage and reading position are dimmed with tap-to-reveal spoiler protection. For complete X-Rays, all chapters are available with no spoiler gating. Books without a TOC fall back to page-range chunks. Excludes event-based categories (timeline, argument development) whose descriptive names produce misleading matches. Uses word-boundary matching against names and aliases.
  • Chapter Appearances: from any item's detail view, see where it appears across all chapters with inline bar visualization (████░░░░) and mention counts. Counts use union semantics: all match spans from the item's name and aliases are collected, overlapping spans merged, and unique matches counted, matching KOReader's text search behavior. Current chapter marked with ▶. Chapters beyond the greater of your X-Ray coverage and reading position are dimmed with tap-to-reveal spoiler protection (individual or "Scan all"). For complete X-Rays, all chapters are visible with no spoiler gating. Tap a chapter with mentions to navigate there and launch a text search for the item's name and aliases (uses regex OR for multi-term matching, e.g., Constantine|Mithrandir). A floating "← X-Ray" button appears during the search: tap it to return directly to the distribution view; hold to dismiss. Auto-dismisses when the search dialog is closed. Uses TOC-aware chapter boundaries with configurable depth and page-range fallback for books without TOC. Per-session caching avoids re-scanning.
  • Edit Search Terms: from any item's detail view, add custom search terms (alternate spellings, transliterations, nicknames) or ignore AI-generated aliases that produce false matches. Custom terms are stored per-book in a sidecar file that survives X-Ray regeneration. Added terms contribute to Chapter Appearances counts and KOReader text search patterns. Ignored terms are hidden from the item's alias list and excluded from counting. All operations (add, remove, ignore, restore) are accessible from a single "Edit Search Terms" button.
  • Search X-Ray: find any entry across all categories by name, alias, or description. When multiple X-Rays exist (main + sections), a "Search other X-Rays" button at the bottom lets you extend the search to all other X-Rays with grouped results by section
  • Local X-Ray Lookup: select text while reading → instantly look it up in cached X-Ray data. No AI call, no network, instant results. Searches by name and alias (not descriptions, to avoid false matches like "Swift" hitting unrelated entries). When multiple X-Rays exist, searches all of them: single match goes directly to detail, multiple matches in one X-Ray show results with a bold header identifying which X-Ray, matches across multiple X-Rays show a grouped cross-section results view. Smart fallback for single X-Ray: prefers section covering current page, falls back to main, uses sole section out of range, or shows picker. Available in highlight menu and dictionary popup when any X-Ray cache exists (main or section). See "Look up in X-Ray" in Highlight Mode.
  • Full View: rendered markdown view in the chat viewer (with export)
  • Chat about this: from any detail view, launch a chat with the entry as context to ask follow-up questions. Opens with a curated set of actions (Explain, Elaborate, ELI5, Fact Check, Connect by default) since the context is AI-generated analysis. Actions requiring document text (Explain in Context, Thematic Connection) are excluded when no book is open. The entry text is prefixed with a note clarifying it's from an analysis, not the work itself. Customize which actions appear via the gear icon → "Choose and Sort Actions"
  • AI Wiki: from any item's detail view (same categories as Chapter Appearances), generate a Wikipedia-style encyclopedia entry about the item using AI knowledge. The button passes only the item's name to the AI, with the X-Ray description provided as disambiguation context, so "Jim" is understood as "Jim Hawkins from Treasure Island" without biasing the output. Entries are cached per-item and per-category in the existing cache file. Button shows "AI Wiki" when no entry exists, "View AI Wiki" when cached. The viewer provides Delete and Regenerate options. Cached wiki entries are automatically cleared when the X-Ray cache is deleted.
  • Text selection: hold to select text in detail views: 1-3 words opens dictionary, 4+ copies to clipboard
  • Options menu (☰): info (model, progress, date, fiction/non-fiction/academic type, checkpoint provenance when checkpoints exist), All versions (N)… (main X-Ray only, when archived versions exist, see X-Ray version history below), delete, close

Model selection for X-Ray: X-Ray generates detailed structured JSON (for the X-Ray browser to work) that can be large (10K-30K+ tokens of output), and it is a complex task for the AI. The action requests up to 64K output tokens to avoid truncation. Weaker models can struggle to follow these instructions, and even if they manage it, will produce low quality content for the actual analysis, and models with low output caps (e.g., some Groq models at 8K) will produce shorter, potentially truncated results, so use larger models with higher output limits for best results. If you find a model that produces great X-Rays, you can lock it in for this action while keeping your global model for everything else, see the tip below.

Tip: Per-action model overrides. You don't have to use the same model for every action. If you discover that a particular model excels at X-Ray (or any other action), you can assign it permanently to just that action:

  1. Go to Settings → Actions → Manage Actions
  2. Long-press the action (e.g., X-Ray) → "Edit Settings"
  3. Scroll to Advanced → set Provider and Model

Your global model continues to be used for all other actions. This is useful for mixing cost and quality: for example, use a fast model (Gemini 3.5 Flash, Haiku, small Mistral models, etc.) as your global default for quick lookups and chat, while assigning a more capable model (Gemini 3.1 Pro, Sonnet, large Mistral models, etc.) specifically to X-Ray or Deep Analysis where quality matters most. See Tuning Built-in Actions for more examples. You can of course also momentarily change you global model to run an action and then change back if you don't want to tie an action to a model.

Tip: If your device supports emoji fonts, enable Emoji Menu Icons in Settings → Display Settings → Emoji for visual category icons in the X-Ray browser (e.g., characters, locations, themes). See Emoji Menu Icons.

Custom TOC support: Chapter-based features (Mentions, Chapter Appearances) automatically use KOReader's active TOC, including custom/handmade TOCs. If your book has no chapters or a single chapter, the fallback is page-range chunks (~20 pages each). For better results, create a custom TOC in KOReader (long-press the TOC icon → "Set custom TOC from pages") and the X-Ray browser will use it.

Hidden flows support: When KOReader's hidden flows feature is active (hiding endnotes, translator introductions, or separate books in collected works), KOAssistant automatically adapts:

  • Text extraction skips hidden content: only visible pages are sent to the AI
  • Reading progress reports your position within visible content only (e.g., page 42 of 70 visible pages = 60%, not 42%)
  • TOC-based features (Mentions, Chapter Appearances) filter out chapters from hidden flows
  • Cache staleness detects when your hidden flow configuration changes and notifies you

This works for both EPUB and PDF. Useful for collected works where you want to analyze just one book, or for editions with long endnotes/apparatus you want excluded from AI analysis. The hidden content is simply invisible to KOAssistant: extraction, progress tracking, and chapter features all operate on visible pages only.

Tip: Hidden Flows is one of the best ways to save tokens and improve AI results. By hiding front matter, introductions, appendices, bibliography, indices, references, and other non-narrative content, you send only the parts that matter: what remains becomes the "whole book" from KOAssistant's perspective. All actions (X-Ray, Summary, Analysis, etc.) operate on this trimmed scope. For collected works or anthologies, use Hidden Flows to isolate individual volumes: a "Complete X-Ray" treats the visible content as the entire document. Hidden Flows and Section X-Rays are complementary: use Hidden Flows to permanently trim away content you never want analyzed, then use Section X-Rays for focused analysis of specific chapters within the trimmed document. See KOReader's documentation for how to set up Hidden Flows.

Highlights in X-Ray: When Allow Highlights is enabled, X-Ray incorporates your highlighted passages into its analysis, adding a Reader Engagement category that tracks which themes and ideas you've engaged with, and weaving your highlights into character and location entries. This gives the X-Ray a personal dimension tied to your reading. To control this:

  • Disable for all actions: Turn off "Allow Highlights" in Settings → Privacy & Data. No action will see your highlights.
  • Disable for X-Ray only: Go to Settings → Actions → Manage Actions, long-press the X-Ray action → "Edit Settings", and untick "Allow highlight use". Other actions keep highlight access.

Without highlights, X-Ray still works fully: you just won't see the Reader Engagement category or highlight mentions in entries.

Tip: Reasoning for complex tasks. For short, dense works (research papers, academic chapters, technical documents under ~100 pages), more reasoning can significantly improve X-Ray quality and depth. The additional processing time is worthwhile when the text is concentrated: the AI produces more thorough entries and fewer omissions. Set the global reasoning stance to Maximum, or override your current model's reasoning to a high level (Settings → Advanced → Reasoning, or the Quick Settings Reasoning chip, or the input dialog's Quick (⚡) chip for a one-shot per-chat override). This also applies to Document Analysis and other complex one-off tasks. See Reasoning/Thinking.

X-Ray requires text extraction to generate: it blocks with a message directing you to enable text extraction or use X-Ray (Simple) instead. If you've already cached an X-Ray and later disable text extraction, you can still view the cached result but cannot update or redo it.

X-Ray (Simple) is a separate action that produces a prose overview (Characters, Themes, Setting, Key Terms, Where Things Stand) from the AI's training knowledge, no text extraction needed. Uses your reading progress for spoiler gating and optionally includes your highlights. Available in the Quick Actions panel and as a separate artifact. Every generation is fresh (no incremental updates). Best for well-known books when you don't want to enable text extraction. For obscure works or research papers, results will be limited since the AI may not recognize the title.

Recap works with source selection: choose between extracted text (recommended, with incremental updates as you read) or AI knowledge only. Use KOReader's Hidden Flows to limit scope to specific chapters or parts of the book.

  • With text extraction (recommended): AI analyzes actual book content. Produces accurate, book-specific results. Results are cached and labeled "Based on extracted document text."
  • Without text extraction (default): AI uses only the title/author and its training knowledge. Works reasonably for well-known titles but produces generic results. Results are labeled "Based on AI training data knowledge."

Tip: Enable Recap Reminder in Settings → Reading & Library to get a prompt to run Recap when you open a book you haven't read in a while (off by default).

Two-track X-Ray: When generating a new X-Ray, you choose between two tracks:

  • Incremental (default): Spoiler-free: extracts text only up to your current reading position. Produces a Current State (fiction) or Current Position (non-fiction) section capturing active conflicts, open questions, and narrative momentum. Supports incremental updates as you read further: only new content is sent, and the AI's additions are diff-merged into the existing analysis. Updates are fast and cheap (~200-500 output tokens vs 2000-4000 for full regeneration). You can also Update to 100% to extend the incremental X-Ray to the end of the book using the same spoiler-free prompt. For a new X-Ray, "Create X-Ray…" asks how far it should cover (up to your position / the whole book / to the end of a section) and how to build it (one request now / in checkpoints / automatically as you read); for an existing one the popup offers "Update X-Ray (to 100%)". The incremental track is also the only one that supports Automatic X-Ray and checkpoints.
  • Complete (entire document): Holistic: extracts and analyzes the entire document in one pass. Produces a Conclusion section with resolutions, themes resolved (fiction) or key findings, implications (non-fiction). Always generates fresh: no incremental updates, no diff-merging. Best for articles, research papers, short works, or finished books where spoiler-free scoping isn't needed. Reached via "Create X-Ray…" → "The whole book" → "In one request now (analyzed as a whole)".

The track is chosen at initial generation and cannot be converted. To switch tracks, delete the cache and regenerate. Both tracks use the same browsable category menu, the same JSON structure for all shared categories (characters, locations, themes, etc.), and the same privacy gates. The only structural difference is the final status section (Current State/Current Position vs Conclusion).

When an X-Ray cache covers 100% (whether from a complete generation, an incremental "Update to 100%", or simply reading to the end and updating), tapping X-Ray goes directly to the browser viewer with no popup (Redo is available in the browser's options menu).

Spoiler safety: By default, X-Ray and Recap use the incremental track, which limits extraction to your current reading position ({book_text_section}). Choosing the whole-book one-request build uses the complete track, which sends the full document ({full_document_section}). All other text extraction actions, including "Explain in Context" and "Analyze in Context", always send the full document. If you need a spoiler-free variant of any action, create a custom action using {book_text_section} instead of {full_document_section}.

Note: Marking a book as "finished" in KOReader does not affect text extraction. Incremental X-Ray and Recap still extract up to your actual page position, not 100%. This means you can navigate to a specific point in a finished book and get a spoiler-free analysis up to that point. For a full analysis of a finished book, use "Create X-Ray…" → "The whole book" → "In one request now" to get the complete track with Conclusion.

⚠️ To enable text extraction: Go to Settings → Privacy & Data → Text Extraction → Allow Text Extraction. This is OFF by default to avoid unexpected token costs.

X-Ray version history: Every time an X-Ray is updated or redone, the version it replaces is archived automatically, so an update or a full regeneration never silently destroys your previous analysis. To browse the archive:

  • From the X-Ray popup (open book or file browser) or the X-Ray browser's ☰ menu, tap "All versions (N)…" (main X-Ray only, sections have no history). The list holds both archived previous versions and any checkpoint versions — which can sit ahead of your reading position, hence "All".
  • Versions are listed newest first, labeled by coverage and age (e.g., "43% · 3 days ago").
  • For each archived version: View it (opens read-only in the full X-Ray browser, titled "X-Ray Version"), Restore it (swaps it back in as the live X-Ray; the version it replaces takes the freed archive slot, so a restore never grows the archive), or Delete it.
  • Archived versions also appear as a "Previous X-Ray Versions (N)" group on every View Artifacts surface (Quick Actions, file browser long-press, the input dialog's Artifacts button, the cross-book Artifact Browser, and chat/artifact viewers), inserted right under the main X-Ray row.

How many versions are kept per book is set by Settings → Reading & Library → X-Ray Versions to Keep (default 5, range 0-20; oldest dropped first). Setting it to 0 stops archiving new versions; already-archived ones stay until you delete them or delete the X-Ray itself (deleting the X-Ray clears its version history and AI Wiki entries too).

Re-reader shortcut: If you jump back in a book so your live X-Ray covers more than you've re-read, the X-Ray popup offers a "View earlier version (NN% · …)" row that opens the nearest archived version at or below your current position, and the version list marks that entry "(latest before your position)". This handles the one case where a live, ahead-of-you X-Ray could otherwise spoil a re-read.

Automatic X-Ray (opt-in): KOAssistant can quietly keep a book's X-Ray up to your reading position in the background as you read, so you never face one giant catch-up extraction on a long book. Everything is off by default, and there are two ways to opt in:

  • Per book: set Automatic X-Ray: On for the book — from its X-Ray popup or Book Settings. A per-book On is self-contained: it auto-creates the first X-Ray if the book has none (while you're still early in the book), then keeps it updated as you read — no global setting needed. A per-book Off always wins.
  • Globally: enable Settings → Reading & Library → X-Ray → Automatic X-Ray (all books) to make every book behave that way by default (books with no X-Ray additionally need the Auto-create X-Ray sub-toggle to get their first one automatically). Individual books can still override either way.

There is also an optional once-per-book offer: with Offer Automatic X-Ray for New Books enabled, opening a book that has no X-Ray asks — early in the book, and only when it could act right away — whether to turn Automatic X-Ray on for it. Declining sets the book's switch to Off, so it never asks again.

Spend guards keep it conservative and predictable:

  • It only updates an existing incremental X-Ray or creates a first one early in a book (where allowed, per above), and never touches complete, AI-knowledge, legacy, or section X-Rays. It never builds checkpoints — that is always an explicit, cost-confirmed action.
  • It fires at most once per cooldown (default 15 minutes) and only when the progress gap since the last update falls inside a configurable window (default 5%-25%). Gaps bigger than the maximum stay manual, so a big jump always goes through the popup that shows you the extraction size first.
  • It runs only when WiFi is already on, it never toggles the radio, and it never prompts.
  • It sends exactly what a manual "Update to X%" sends (the cached result + entity index + only the newly-read text) to your configured provider, and it re-checks text-extraction consent (or a trusted provider) at fire time, just like a manual update. Revoking consent silently stops it.

Failures are silent (surfaced only in the X-Ray popup's coverage line and the debug console); enable Notify on Background Activity for a brief notification when background work starts and completes. Tunable dials (minimum/maximum progress gap, cooldown) live under the master toggle. This is currently EPUB-only (flowing formats; page-based PDFs don't show the rows). Automatic X-Ray extracts book text and spends API tokens without a per-request tap — the interactive truncation/size warnings don't apply to background runs (an oversized background extraction aborts instead of asking) — so leave it off if you want every request to be deliberate.

X-Ray checkpoints (manual, runs in the background): from the X-Ray popup's Versions group, "Build checkpoints…" generates a full set of prefix versions of the book's X-Ray (continuing from your existing X-Ray's coverage when one exists, or from the beginning of the book when none does — the confirmation dialog states which) — roughly one every 10% of a normal-length book (spacing adapts to book length: wider on short books so a novella isn't sliced into tiny calls, narrower on very long books so a single version never covers an oversized slice; versions snap to chapter ends when the book has a usable table of contents, so they read as "up to the end of a chapter"). The confirmation dialog shows the planned checkpoint count and spacing, and "Adjust spacing for this run…" lets you override it for that one run — e.g. denser versions for dense material. After that one dialog, the checkpoints are built in the background one incremental step at a time — the book is read once in total, plus a fixed per-checkpoint overhead, so somewhat more than one full X-Ray run — while you keep reading (the book must stay open; you can cancel anytime and resume later from where it stopped). As you read past a version's position, it is silently swapped in as your live X-Ray, so the X-Ray follows your reading position with zero waiting; all versions stay browsable under "All versions".

Checkpoints serve two purposes, and both are first-class: spoiler-safe reading (every position gets an X-Ray that never runs ahead of you), and a checkpointed full build — completing a big book's X-Ray in bounded increments instead of one oversized request (a failure keeps the finished versions; resume continues from the highest). If you built them for the second reason and don't want spoiler gating, tap "Switch to complete version (100%) — instant" in the popup's Versions group: it installs the finished 100% version as your live X-Ray for free (no merging is ever needed — each checkpoint already contains everything below it), with a notice that the other checkpoints can be safely deleted (keeping them is fine too; they stay browsable). The switch is not a one-way door: while the checkpoints are kept, "Switch back to your position (NN%) — instant" re-installs the version at or below where you're reading, and position-tracking (promotion as you read) resumes — both switches are free and reversible. Useful before a re-read, for book clubs, or to give a book spoiler-safe X-Rays for its whole length up front.

Section X-Rays: focused X-Rays for individual chapters, parts, or sections of a book. Unlike the main X-Ray (which covers the whole document), Section X-Rays analyze only a specific page range chosen from the book's table of contents. You can have multiple Section X-Rays per book alongside the main X-Ray, each is independent and stored separately.

How to create a Section X-Ray:

  1. From the X-Ray scope popup, tap "Generate Section X-Ray…"
  2. A hierarchical TOC picker shows all chapters/parts, tap the section you want
  3. Optionally rename it (defaults to the TOC entry title, 80-character limit)
  4. The AI analyzes only the text within that page range and produces a complete X-Ray

Section ranges: "Generate for a section range…" (same popup group) asks for two TOC picks — the first and last section — and produces ONE Section X-Ray spanning everything between them (e.g. chapters 3–7 as a single artifact). Picks work in either order; the name defaults to "First – Last". One request instead of building each chapter separately and merging.

How to browse Section X-Rays:

  • From the X-Ray scope popup → "View Section X-Rays (N)", lists all sections with page ranges and timestamps
  • If you're currently reading within a section's page range, a "View 'Section Name' (pp X–Y, Nd ago)" button appears directly in the popup for quick access
  • From View Artifacts (Quick Actions, file browser, artifact browser) → "View Section X-Rays (N)" group
  • Tap any entry to open it in the X-Ray browser; hold for rename/delete options

Section X-Ray browsing differences:

  • Title shows "X-Ray § [Section Name]" instead of "X-Ray"
  • Scope gating replaces spoiler gating: chapters outside the section's page range are dimmed (not unread-based). Tap to reveal with a scope warning
  • Complete-only: no incremental updates and no version history, section scope is fully analyzed in one pass
  • Reading position marker only shown when your current page falls within the section's scope
  • Options menu shows "Regenerate" (no Update variants) and section-specific info (scope, page range, model)

Font-size independence: Section X-Rays store XPointers (stable document positions) alongside page numbers. When you change font size and reopen the book, page ranges in the section list and browser automatically update to reflect the new layout.

Tip: Section X-Rays are ideal when the full document is too large for a single detailed analysis, or when chapters cover disparate topics (as in many textbooks, academic works, or the Quran surah-by-surah). Rather than trimming the document globally with Hidden Flows, sections let you run deep analyses on specific parts while keeping the full document intact for other actions. Also useful for pivotal scenes in novels, individual essays in collections, or introductory sections you want to reference independently. For trimming away content you never want analyzed (bibliography, indices, notes, apparatus), use Hidden Flows instead: the two approaches are complementary. Section scoping is also available for other text-extraction actions, see Section support below.

Full Document Actions (Document Analysis, Document Summary, Extract Insights, Key Arguments, Discussion Questions, Quiz, Explain in Context, Analyze in Context, Thematic Connection): These actions use the entire document context. Document Analysis and Document Summary require text extraction: they block generation when it's disabled, like X-Ray. Actions with source selection (Key Arguments, Discussion Questions, Quiz, Extract Insights, Explain in Context, Analyze in Context, Thematic Connection) let you choose between full text, a cached summary, or AI knowledge only, see Source selection. They adapt to your content type and work especially well with Domains. For example, with a "Linguistics" domain active, analyzing a linguistics paper will naturally focus on relevant aspects.

Section support: Most text-extraction book actions can be focused on a specific chapter or part instead of the full document. Scope and source are combined in a single unified popup: tap "Pick section…" to choose via a hierarchical TOC picker, or "Pick section range…" / "From section… (to current position)" for multi-section spans. For X-Ray, the action's own popup offers section options (see Section X-Rays). Section artifacts are stored independently (e.g., "Section Summary: Chapter 5") and appear as groups in the Artifact Browser. When you're reading within a section's page range, a quick-access "View" button for that section appears directly in the action popup. Naming a section with the same page range as an existing one replaces the old entry. Supported actions: Document Summary, Document Analysis, Key Arguments, Discussion Questions, Quiz, Extract Key Insights (plus X-Ray via Section X-Rays above). Section scoping respects KOReader's custom/handmade TOC: create custom chapter boundaries to define your own scopes.

Tip: Create specialized versions for your workflow. Copy a built-in action, customize the prompt for your field (e.g., "Focus on methodology and statistical claims" for scientific papers), and pair it with a matching domain. Disable built-ins you don't use via Action Manager (tap to toggle). See Custom Actions for details.

Artifact Caching: All artifact actions cache results per book. For incremental X-Rays with a partial cache, a popup lets you View the cached result (with coverage and age), Update it to your current position, or Update to 100%. Complete X-Rays and incremental caches at 100% go directly to the browser viewer, Redo is available in the options menu. Updating or redoing an X-Ray archives the version it replaces (see X-Ray version history). See Document Artifacts for details.

Reading Mode vs File Browser:

Book actions work in two contexts: reading mode (book is open) and file browser (long-press a book in your library).

  • File browser has access to book metadata (title, author, identifiers) plus sidecar data (highlights, annotations, notebook, reading progress) read from the book's metadata on disk
  • Reading mode additionally has access to live document state: extracted text, page text, chapter/TOC information, reading statistics

Reading-only actions (hidden in file browser): X-Ray, Recap, Document Analysis, Document Summary, these require live document text extraction or source selection that isn't available until you open the book.

Sidecar-eligible actions (available in file browser): X-Ray (Simple), Analyze Notes, Suggest from Library, and other actions that only need highlights, annotations, notebook, or reading progress. These read data from the book's sidecar files on disk without requiring an open document.

Custom actions using placeholders like {book_text}, {full_document}, or {page_text} require reading mode. Placeholders like {reading_progress}, {highlights}, {annotations}, and {notebook} work in both contexts via sidecar fallback. The Action Manager shows a [reading] indicator for reading-only actions.

Library Mode

Access: Quick Settings → Library Chat/Action, or Settings menu → Library Chat/Action, or via gesture. Opens directly to an input dialog with all library actions available. File browser multi-select also works: select multiple documents → tap any → "Compare with KOAssistant".

The library dialog splits actions into two zones with their own management buttons:

Library Scan zone: scan-based actions with a Library Scan ▾ button for folder management (enable/disable permanent folders, add on-the-fly folders for this session). Always visible by default so users can discover scan actions, but actions are grayed out until library scanning is enabled with folders configured. Tapping the Library Scan ▾ button when scanning is not enabled shows a setup prompt. To hide this zone entirely, use the gear menu → Hide Library Scan Actions:

Action Description
Next Read What to read next from your library, including books worth revisiting or picking back up. Based on reading patterns, what you've finished, and what's been sitting unread. With Advanced Stats enabled, includes engagement context (stalled reads, briefly started books)
Discover New Suggests new books based on your library, identifies your taste and recommends works you don't have, including a few picks outside your comfort zone ("Expand your horizons"). With Advanced Stats enabled, includes deep reads and recently finished books for better taste inference
Analyze Library Analyzes your library to identify genres and authors you gravitate toward, completion patterns, and gaps in your collection. With Advanced Stats enabled, includes full engagement data for richer pattern analysis
Challenge My Taste Critiques your reading pattern rather than celebrating it: where your library is one-sided, which voices are missing, and what a sharp critic of your shelf would say — ending with a few books that would argue with it. With Advanced Stats enabled, includes engagement patterns

Items zone: selection-based actions with an Items ▾ button for book management (presets, browse history, add folder, clear). Require 2+ books selected:

Action Description
Compare What makes each work distinct: contrasts, not just similarities
Find Common Themes Shared DNA: recurring themes, influences, connections
Analyze Collection What this selection reveals about the reader's interests
Quick Summaries Brief summary of each work
Reading Order Suggest optimal order based on dependencies, difficulty, themes
Recommend Suggests 5-8 new works based on patterns across your selected works. When library scanning is enabled, notes which recommendations you already own and prioritizes unread books
Analyze Notes Analyzes highlights, annotations, and notes across selected books: patterns in what you mark, what you write, and how your thinking connects across works ⚠️ Requires: Allow Highlights or Allow Annotation Notes

Selection-based action buttons are grayed out (disabled) until 2+ books are added. Long-press any grayed-out button to see what it does. Tap Items ▾ to select books via presets (Currently Reading, Recently Finished, On Hold, Last 5 from History), Browse History, or Browse Folder. The book picker supports source switching: once inside, use the hamburger menu to switch between history and folder sources without closing. Selections persist across source switches. The title bar shows the count of selected items.

Freeform chat also works: type a question and tap Send. When library scanning is enabled with folders configured, the library catalog is included as context. When items are selected, those are included too. The input hint rotates context-sensitive suggestions (e.g., "What should I read next?", "How do these books connect?", "A book I've been neglecting").

What the AI sees: For scan-based actions: library catalog metadata (title, author, series, status, progress, last read date). For selection-based actions: list of selected titles, authors, and identifiers. Actions with sidecar flags (e.g., Analyze Notes) also read per-book highlights, annotations, and notebook entries from sidecar files, with the same privacy double-gating as single-book actions, with annotation degradation. A warning appears when total sidecar data is large. See Privacy & Data for details on library scanning.

General Chat

Access: Tools → KOAssistant → General Chat/Action, or via gesture (easier)

A free-form conversation without specific document context. If started while a book is open, that "launch context" is saved with the chat (so you know where you launched it from) but doesn't affect the conversation, i.e. the AI doesn't see that you launched it from a specific document, and the chat is saved in General chats

Built-in Actions:

Action Description
News Update Get today's top news stories from Al Jazeera with links ⚠️ Requires: Web Search

Tip: General-context actions can now see their own recent saved results via the {previous_results_section} placeholder. This lets you build "repeating" actions that continue from where they left off (e.g., a running journal or a rolling news digest). It reads the assistant turns of your most recent saved general chats for that same action — so you need to have saved chats for it. See Utility Placeholders.

Managing the Input Dialog

All input dialogs (highlight, book, library, general) show a configurable set of actions that you can customize per context, plus a session chips row above the input field for controlling this chat only. The title bar has a close X on the right and a gear icon on the left. Below the chips come the action buttons in rows of 2, then Send. Long-press any action button to see its description.

Session Controls (Chips)

The old fixed top row ([Web ON/OFF] [Domain] [Send]) and the pile of checkboxes have been replaced by a single row of tappable chips, followed by Send. Each chip controls one aspect of the request. The canonical order is fixed — Domain · Web · Tools · Quick · Scope · Attach · Spoiler — but you choose which chips are shown. Most chips follow the same pattern: tap toggles/changes the value for this chat, and long-press opens the persistent (per-book / global) defaults picker behind it.

Chip Tap Long-press
Domain 🏛️ Opens the domain picker (subject expertise) for this chat (same picker; choose "For this book" / "Global")
Web 🌐 Toggles web search for this chat (session-only — it no longer changes your saved global setting). If your provider can't search, tapping explains instead of toggling Opens the For-this-book / Global web-search picker
Tools 🔍 Toggles AI Book Tools for this chat Opens the tools posture picker (Off / Manual / Auto, For-this-book or Global)
Quick ⚡ Toggles the one-shot Quick Answer posture for this chat Opens the Quick controls menu (one-shot reasoning / model override, "Quick answer default…" for the per-book/global starting state, plus "Preset settings…")
Scope 🎯 Book chats: pick a text range to attach; highlight chats: set the surrounding-context mode for this chat Book chats: same picker; highlight chats: opens the persistent per-book/global surrounding-context default picker (different from the tap menu)
Attach 📎 Stage extra material (notebook / artifact / chat / file / note) for this chat Manage the staged attachments
Spoiler Toggles spoiler-free mode for this chat Opens the For-this-book / Global spoiler-free picker

Details on each:

  • Domain chip — shows the active domain name (or "Domain"); opens the domain picker with a For-this-book / Global target toggle.
  • Web chip — the label reflects the current on/off state. This is now a session toggle: it applies to freeform Send and to actions launched from this dialog, but does not persist as your global web-search default. Long-press opens the per-book / global picker. Unsupported providers get an explanation on tap rather than a silent toggle.
  • Tools chip — only shown in book/highlight contexts with a book open. Reads "ON/OFF" when tools are usable; shows N/A when the session can't run tools (tap explains why — e.g. text-extraction consent needed, unsupported provider, or an X-Ray chat where tools are excluded by design), and a locked OFF when the tools posture is off (long-press to turn on). It also reads N/A when a Scope pick is active, because an attached scope already supplies book text (the chip wins over tools for that send).
  • Quick chip — tap applies a one-shot Quick Answer posture for the chat (see below); the label shows ON, SET (a one-shot reasoning/model override is active), or OFF. Long-press opens the Quick controls menu. A separate "Quick answer default…" entry in that menu (and the per-book Book Settings screen) sets whether the ⚡ chip starts ON for this book (or globally) on a fresh dialog open — like the Web/Tools/Spoiler chips' persistent pickers, this doesn't change the current chat's session state.
  • Scope chip (book contexts) — attaches a slice of the book's text to your freeform message: Current page (works without text-extraction consent), Up to current position (NN%), From section… (to current position), Pick section range…, or Choose section…. Everything except "Current page" needs "Allow Text Extraction" (or a trusted provider). Picks that reach beyond your current position are rejected/clamped when spoiler-free is on. The pick is resolved into text at Send (a Cancel on the large-extraction warning keeps your typed input intact), and it is session-only — a fresh dialog open clears it.
  • Scope chip (highlight contexts) — instead of a book range, it sets the surrounding-context mode for this chat (Off / Sentence / Paragraph / Characters), overriding the ambient highlight-context default. Long-press opens the persistent per-book / global picker.
  • Attach chip — stages extra context that rides alongside your messages (as its own context message, not as your question). Types: Notebook (this book) (needs Notebook sharing consent), Artifact… (any saved/pinned artifact — the current book's first, with an "All books…" option), Chat… (a saved chat), Text file… (a .txt/.md file), and Note… (a free-text note, e.g. "this is the 2nd edition" or "I'm reading this for a course"). The label shows the count. Long-press manages/removes staged items. Works in every input context, including X-Ray chat.
  • Spoiler chip — only shown in book/highlight contexts; toggles spoiler-free mode for the session. Long-press opens the per-book / global picker. This chip replaces the old "Show Spoiler-free Chat Checkbox" setting (that setting was migrated into chip membership).

Tip: Quick Answer & its preset. Tapping the ⚡ Quick chip applies a configurable bundle for that chat: a concise-answer nudge, reasoning off, web search off, and book tools off (each part can be turned off in the preset). You can also switch models just for Quick Answer chats. Long-press the chip for one-shot Reasoning (Follow / Off / On) and Model (provider → model, filtered to providers you have keys for) overrides, for "Quick answer default…" (the per-book/global setting for whether the chip starts ON), and for Preset settings…. Configure the preset in Settings → Chat & Export Settings → Quick Answer Preset (Quick Answer On by Default, Concise Answer Nudge, Turn Reasoning Off, Turn Web Search Off, Turn Book Tools Off, and the model mode: Keep current / Fastest for provider / a tier / a pinned model). A one-shot pick from the chip's menu always overrides the preset for that chat.

Tip: Choosing which chips appear. Tap the gear icon → Toolbar Buttons… to toggle which chips are shown. Only membership is configurable — the order is fixed. Your choice persists in features.session_chips. Chips that don't apply to the current context are hidden automatically (e.g. Tools/Scope/Spoiler need a book open).

Actions in the Input Dialog

Default actions per context:

Context Default Actions
Highlight Translate, Explain, ELI5, Elaborate, Summarize, Connect, Fact Check, Counterpoint, Explain in Context
Book About, X-Ray (Simple), Find Similar, Key Arguments, Counterarguments, Extract Key Insights, Discussion Questions, About Author, Reviews
Book (file browser) About, X-Ray (Simple), Find Similar, Analyze Notes, Related Thinkers, About Author, Historical Context, Reviews, Suggest from Library
X-Ray Chat Explain, Elaborate, ELI5, Fact Check, Connect
General (none, use Send button for freeform chat)

All defaults are customizable: add, remove, or reorder actions for each context independently. Remaining enabled actions are always accessible via "Show More Actions" in the grid or the gear icon → "More Actions".

Customizing which actions appear:

  • From the input dialog: Tap the gear icon → "Choose and Sort Actions" to reorder, show, or hide actions for the current context
  • From the input dialog: Tap the gear icon → "More Actions" to run any enabled action not currently shown in the grid
  • From Action Manager: Long-press any action → "+ Input Dialog" to add it to the relevant input context

The general input dialog shows only actions you've explicitly added. By default, it starts empty (use the Send button for freeform chat). To add actions:

  1. Go to Settings → Actions → Action Manager
  2. Switch to General context (at the top)
  3. Long-press any action
  4. Tap "Add to General Input"

Actions like News Update that require web search are available in the gesture menu by default but not in the input dialog. This avoids showing web-dependent actions to users who haven't configured a web-search-capable provider. Add them to the input dialog (Manage Actions -> long press a general context action -> Add to General Input) if you use Anthropic, Gemini, OpenAI, xAI, Perplexity, or OpenRouter.

Tip: News Update demonstrates per-action web search override (enable_web_search = true). Even if web search is globally disabled, this action will use it. See Web Search for more on per-action overrides.

Quick UI Features

  • Action Descriptions: Long-press any action button to see what it does. Works everywhere: input dialog, Quick Actions panel, highlight menu, and file browser buttons. Also works on grayed-out buttons (e.g., library selection actions before adding books).
  • Settings Icon (Input): Tap the gear icon in the input dialog title bar for a menu with Quick Settings (streamlined settings panel), Choose and Sort Actions (reorder, show/hide actions for this context), More Actions (access enabled actions not shown in the grid), Toolbar Buttons… (choose which session chips appear above the input field), and — in book/highlight chats — Book Settings (per-book overrides for the book you're chatting about). See Recommended Setup for details on the Quick Settings panel.
  • Session Chips (Input): The row of chips above the input field controls this chat only — Domain, Web search, Book Tools, Quick Answer, Scope, Attach, and Spoiler. Tap to change the value for this chat; long-press to open the persistent (per-book / global) picker behind it. See Managing the Input Dialog for details on each chip. (These replaced the old fixed Web/Domain top row and the checkbox pile.)
  • Settings Icon (Viewer): Tap the gear icon in the chat viewer title bar for a menu with Font Size, Alignment (left / justify / right), Reset to Defaults, Show Reasoning (when the response has reasoning content), Show Sources (when the response used web search or book tools — see below), and Show/Hide Debug. Font size and alignment now persist across opens (including on artifact and X-Ray viewers).
  • Show Sources: When a response used web search or AI Book Tools, a Show Sources viewer lists the web URLs and queries and/or the book lookups the AI performed. Per-message indicators also appear inline ("Searched the web", "Searched the book — N lookups"). Pre-search prose is preserved behind an inline *[Searched the web]* marker rather than being discarded. The Sources and Reasoning viewers support text selection, Copy, and Export like the main chat.
  • Settings Icon (Panels): Both the Quick Settings and Quick Actions panels have a gear icon in the title bar for managing panel layout: reorder, show/hide buttons without leaving the panel
  • Show/Hide Quote: In the chat viewer, toggle button to show or hide the highlighted text quote (useful for long selections)
  • Save to Note: For highlight context chats, tap the Save to Note button to save the AI response directly as a note attached to your highlighted text (see Save to Note below)
  • Add to reply: In the chat viewer's text-selection popup, when a reply is open you can send the selected text into the reply as a quote — useful for asking a follow-up about a specific sentence in the answer.
  • Link Handling: Tapping a link in the chat viewer opens KOReader's external link dialog: Copy, Show QR code, Open in browser, and any registered plugin actions (e.g., Add to Wallabag). When no book is open, a basic version of the dialog is shown.
  • Text Selection: Selecting 1 word in any viewer triggers a dictionary lookup. Long-pressing 1 word or selecting 2+ words opens a popup with Copy, Dictionary, Translate, and Add to Notebook options (plus Add to reply when a reply is open). Consistent across all viewer types (chat, X-Ray browser, compact, dictionary, translate views). Can also be extended to KOReader's own viewers (dictionary, Wikipedia, bookmarks, etc.) via Settings → Menus & Buttons → Text selection in viewers → Enhance text selection (requires restart). See Text Selection in Chat Viewer.
  • Other: Turn on off Text/Markdown view, Debug view mode, add Tags, Change Domain, etc

Spoiler-Free Mode

Prevents the AI from revealing events beyond your current reading position when chatting about books.

How it works: When enabled, a spoiler prevention instruction is injected into the system prompt for freeform chat (the Send button) in book and highlight contexts. The instruction tells the AI your exact reading progress (e.g., "The reader is currently at 42% of this book") and forbids discussing anything beyond that point. When reading progress is unavailable, a generic variant is used ("The reader has not finished this book").

With AI Book Tools enabled, this setting also controls the tools' reading scope structurally: spoiler-free on → the tools can only read up to your current page (the AI physically cannot read ahead); off → they can read the whole document. That's a stronger guarantee than the prompt instruction alone.

How to turn it on:

  • Global toggle — Settings → Chat & Export Settings → Spoiler-free Chat: when on, all book/highlight freeform chats get spoiler awareness by default. Off by default.
  • Per-chat (Spoiler chip) — enable the Spoiler chip via the input dialog's gear menu → Toolbar Buttons…, then tap it to flip spoiler-free for the current chat without changing your global setting. (This chip replaces the old "Show Spoiler-free Chat Checkbox" setting, which was migrated into chip membership.) The chip starts in whatever state your per-book / global default resolves to, and can be flipped per chat.
  • Per-book override — in Book Settings you can set spoiler-free per book (Follow global / On / Off); the per-book value seeds the chip when you open the book. Long-press the Spoiler chip to reach the per-book / global picker directly.

Reading progress source:

  • Open book: Live progress from the reader
  • File browser: Saved progress from book settings
  • No progress available (0% or unknown): Falls back to generic "has not finished" variant

What's covered:

  • Freeform chat (Send button) in book and highlight contexts
  • Replies in the same chat session inherit the spoiler setting

What's intentionally excluded:

  • Predefined actions (have their own spoiler handling where relevant, e.g., X-Ray, Recap)
  • Artifact chat (discussing already-generated content)
  • Chat history resume (previous messages already generated)
  • X-Ray "Chat about this" (section coverage % may conflict with book reading %)
  • Library and general contexts (no specific book to spoil)

For custom actions: Use the {spoiler_free_nudge} placeholder in your action prompts to add spoiler awareness. The placeholder resolves to the spoiler instruction when active, or to nothing when inactive. See Utility Placeholders.

Save to Note

Save AI responses directly to your KOReader highlights.

When working with highlighted text, the Save to Note button lets you save the AI response as a native KOReader note attached to that highlight. This integrates AI explanations, translations, and analysis directly into your reading annotations.

How it works:

  1. Highlight text and use any KOAssistant action (Explain, Translate, etc.)
  2. Review the AI response in the chat viewer
  3. Tap the Save to Note button (appears between Copy and Notebook)
  4. KOReader's Edit Note dialog opens with the response pre-filled
  5. Edit if desired, then save, and the highlight is created with your note attached

Key features:

  • Native integration: Uses KOReader's standard highlight/note system
  • Configurable content: Choose what to save: response only (default), question + response, or full chat with metadata. Configure in Settings → Chat & Export Settings → Content Format → Note Content
  • Editable before saving: Review and modify the AI response before committing
  • Creates permanent highlight: The selected text becomes a saved highlight with the note attached
  • Works with translations: Great for saving translations alongside the original text
  • Available in all views: Appears in both full chat view and Translate View

Use cases:

  • Save explanations of difficult passages for later reference
  • Keep translations alongside original foreign text
  • Build a glossary of term definitions within your book
  • Annotate with AI-generated insights that become part of your reading notes

Note: The Save to Note button only appears for highlight context chats (where you've selected text). It's not available for book, library, or general chat contexts.

Image Generation

KOAssistant can turn a passage you highlight into an AI-generated image — visualize a character, a described setting, a diagram, or a scene straight from the text you are reading.

Tip: Image generation is a paid feature that uses your own provider API key, just like chat. Each image costs whatever the provider charges per image (this is separate from, and usually more expensive than, text generation), so use it deliberately.

How to Generate an Image

  1. Highlight a passage in your book (any length — the selected text becomes the image description/prompt).
  2. In the highlight menu, tap Generate Image (KOA).
  3. A progress window appears ("Generating image with … / …", with an elapsed-seconds counter). Tap Stop to cancel a request in flight.
  4. When it finishes, the image opens full-screen in KOReader's built-in image viewer. It is also saved automatically (see Where Images Are Stored).

The Generate Image button only appears when the resolved image provider is one that supports image generation and you have an API key configured for it. If no supported provider is available, the button is hidden.

Supported Providers and Models

more like this

dsclaude

Claude Code & Desktop launchers for 11+ third-party LLM backends (DeepSeek, Qwen, Kimi, GLM, MiniMax, Doubao, LongCat,…

PowerShell★ 56
@Agents365-ai

search

search projects, people, and tags