KOAssistant

Powerful, customizable AI assistant for KOReader.

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

• Highlight text → translate, explain, define words, analyze passages, connect ideas, save content directly to KOReader's highlight notes/annotations
• 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
• 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, 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, OpenRouter, Perplexity)
• Multilingual → Use any language the AI understands, and use the KOAssistant UI in 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. 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.

Note: This README is intentionally detailed to help users discover all features. Use the table of contents or search (Ctrl+F) to navigate.

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 → KOReader Integration. 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.

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 Fonts 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: 8 actions included by default (Translate, Look up in X-Ray, ELI5, Explain, Elaborate, Summarize, Connect, Fact Check); add more via Manage Actions → hold action → "Add to Highlight Menu"
• 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 → "Add to Gesture Menu", requires restart)
• Pin actions to file browser: Add frequently-used book actions directly to the long-press menu (Manage Actions → hold → "Add to File Browser")

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)

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
• Web Search & Language: Enable AI web search and set 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
• Manage Actions: Edit and configure your actions

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

• New Book Chat/Action: Start a chat about the current book or access book actions
• Quick Actions...: Access the Quick Actions panel for reading features
• More Settings...: Open the full settings menu

The panel has a gear icon (top-left) that opens the QS Panel Utilities manager for reordering and toggling buttons. Also accessible via Settings → Quick Settings Settings → QS Panel Utilities.

2. Quick Actions (reader mode only)

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
• Artifact button: "View Artifacts" appears when any artifacts exist (X-Ray, X-Ray (Simple), Summary, Analysis, Recap, About, Analyze Notes), opening a picker showing each artifact with progress % and age (e.g., "X-Ray (100%, 3d ago)")
• Utilities: Translate Page, New Book Chat/Action, Continue Last Chat, General Chat/Action, Chat History, Notebook, View Artifacts, Quick Settings

You can add any book action to Quick Actions via Action Manager → hold action → "Add to 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). Also accessible via the hamburger menu in Manage Actions. 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:

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) for quick queries; powerful models (like Sonnet, Opus) 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 meant as security or privacy theater or false reassurances of privacy, as the "threat model" here is simply users including sensitive data (Annotations, notes, content, etc.) by accident; you are already being permissive about privacy by using online AIs (especially for personal interest areas) in the first place, and this plugin by its nature does encourage the use of AI to analyze your reading material. The available placeholders/template variables are substantial in this regard (amount and sensitivity of 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:

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 Chat & Export Settings → 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) 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. When the active 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.

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, 🌐 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.

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):

* Surrounding context is a text selection type for highlight context (same as highlighting text), included here for clarity because it extracts more than you highlighted.

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 → Chat & Export 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 (11 library actions shown as 3 scan-based + 7 selection-based + 1 book-context action that uses library data):

*Requires web search (Anthropic, Gemini, 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.

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

Highlight Mode

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:

Source selection:

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

Scope (shown when the book has a table of contents):

• Full document: Use the entire document
• 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")

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. If no summary exists, this option shows "(generate first)".
• 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, Discussion Questions, Quiz, 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
• 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. 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

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:

…view the full README on GitHub.