https://github.com/zeeyado/koassistant.koplugin
A powerful AI assistant integrated into KOReader.
https://github.com/zeeyado/koassistant.koplugin
chatgpt-api claude-ai deepseek e-ink e-reader ereader gemini-api koplugin koreader koreader-plugin ollama-api
Last synced: 4 months ago
JSON representation
A powerful AI assistant integrated into KOReader.
- Host: GitHub
- URL: https://github.com/zeeyado/koassistant.koplugin
- Owner: zeeyado
- License: gpl-3.0
- Created: 2025-07-10T18:04:19.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-02-05T21:36:43.000Z (4 months ago)
- Last Synced: 2026-02-06T00:47:27.154Z (4 months ago)
- Topics: chatgpt-api, claude-ai, deepseek, e-ink, e-reader, ereader, gemini-api, koplugin, koreader, koreader-plugin, ollama-api
- Language: Lua
- Homepage: https://github.com/zeeyado/koassistant.koplugin
- Size: 5.38 MB
- Stars: 39
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# KOAssistant
[](https://github.com/zeeyado/koassistant.koplugin/releases/latest)
[](LICENSE)
[](https://hosted.weblate.org/engage/koassistant/)
**Powerful, customizable AI assistant for KOReader.**
- **Highlight text** → translate, explain, define words, analyze passages, connect ideas, save content directly to KOReader's highlight notes/annotations
- **While reading** → reference guides (Summaries, X-Ray, Recap), analyze your highlights/annotations, explore the book (author, context, arguments, similar works), generate discussion questions
- **Research & analysis** → deep analysis of papers/articles, explore arguments, find connections across works
- **Multi-document** → compare texts, find common themes, analyze your collection
- **General chat** → AI without book context
- **Web search** → AI can search the web for current information (Anthropic, Gemini, OpenRouter)
16 built-in providers (Anthropic, OpenAI, Gemini, Ollama, and more) plus custom OpenAI-compatible providers. Fully configurable: custom actions, behaviors, domains, per-action model overrides. Personal reading data (highlights, annotations, notebooks) is opt-in — not sent to the AI unless you enable it.
**Status:** Active development — [issues](https://github.com/zeeyado/koassistant.koplugin/issues), [discussions](https://github.com/zeeyado/koassistant.koplugin/discussions), and [translations](https://hosted.weblate.org/engage/koassistant/) 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](https://github.com/omer-faruq/assistant.koplugin); both can run side by side.
> **Note:** This README is intentionally detailed to help users discover all features. Use the table of contents to navigate.
---
## Table of Contents
- [User Essentials](#user-essentials)
- [Quick Setup](#quick-setup)
- [Recommended Setup](#recommended-setup)
- [Configure Quick Access Gestures](#configure-quick-access-gestures)
- [Testing Your Setup](#testing-your-setup)
- [Privacy & Data](#privacy--data) — ⚠️ (Read this) Some features require opt-in
- [Privacy Controls](#privacy-controls)
- [Text Extraction and Double-gating](#text-extraction-and-double-gating) — Enable book content analysis (off by default)
- [How to Use KOAssistant](#how-to-use-koassistant) — Contexts & Built-in Actions
- [Highlight Mode](#highlight-mode)
- [Book/Document Mode](#bookdocument-mode)
- [Reading Analysis Actions](#reading-analysis-actions) — X-Ray, Recap, Full Document Analysis
- [Multi-Document Mode](#multi-document-mode)
- [General Chat](#general-chat)
- [Save to Note](#save-to-note)
- [How the AI Prompt Works](#how-the-ai-prompt-works) — Behavior + Domain + Language system
- [Actions](#actions)
- [Managing Actions](#managing-actions)
- [Tuning Built-in Actions](#tuning-built-in-actions)
- [Creating Actions](#creating-actions) — Wizard + template variables
- [Template Variables](#template-variables) — 30+ placeholders for dynamic content
- [Utility Placeholders](#utility-placeholders) — Reusable prompt fragments (conciseness, hallucination nudges)
- [Highlight Menu Actions](#highlight-menu-actions)
- [Dictionary Integration](#dictionary-integration) — Compact view, on demand context mode
- [Bypass Modes](#bypass-modes) — Skip menus, direct AI actions
- [Dictionary Bypass](#dictionary-bypass)
- [Highlight Bypass](#highlight-bypass)
- [Translate View](#translate-view)
- [Custom Action Gestures](#custom-action-gestures)
- [Available Gesture Actions](#available-gesture-actions)
- [Translate Current Page](#translate-current-page)
- [Behaviors](#behaviors) — Customize AI personality
- [Built-in Behaviors](#built-in-behaviors)
- [Sample Behaviors](#sample-behaviors)
- [Custom Behaviors](#custom-behaviors)
- [Domains](#domains) — Add subject expertise to prompts
- [Creating Domains](#creating-domains)
- [Managing Conversations](#managing-conversations) — History, export, notebooks
- [Auto-Save](#auto-save)
- [Chat History](#chat-history)
- [Export & Save to File](#export--save-to-file) — Clipboard, file, multiple formats
- [Notebooks (Per-Book Notes)](#notebooks-per-book-notes)
- [Chat Storage & File Moves](#chat-storage--file-moves)
- [Tags](#tags)
- [Settings Reference](#settings-reference) ↓ includes [KOReader Integration](#koreader-integration)
- [Update Checking](#update-checking)
- [Advanced Configuration](#advanced-configuration)
- [Backup & Restore](#backup--restore)
- [Technical Features](#technical-features)
- [Streaming Responses](#streaming-responses)
- [Prompt Caching](#prompt-caching)
- [Response Caching (X-Ray/Recap)](#response-caching-x-rayrecap) — Incremental updates + Summary Cache for Smart actions
- [Reasoning/Thinking](#reasoningthinking)
- [Web Search](#web-search) — AI searches the web for current information (Anthropic, Gemini, OpenRouter)
- [Supported Providers + Settings](#supported-providers--settings) - Choose your model, etc
- [Free Tier Providers](#free-tier-providers)
- [Adding Custom Providers](#adding-custom-providers)
- [Adding Custom Models](#adding-custom-models)
- [Setting Default Models](#setting-default-models)
- [Tips & Advanced Usage](#tips--advanced-usage)
- [View Modes: Markdown vs Plain Text](#view-modes-markdown-vs-plain-text)
- [Reply Draft Saving](#reply-draft-saving)
- [Adding Extra Instructions to Actions](#adding-extra-instructions-to-actions)
- [KOReader Tips](#koreader-tips)
- [Troubleshooting](#troubleshooting)
- [Features Not Working / Empty Data](#features-not-working--empty-data) — Privacy settings for opt-in features
- [Text Extraction Not Working](#text-extraction-not-working)
- [Font Issues (Arabic/RTL Languages)](#font-issues-arabicrtl-languages)
- [Settings Reset](#settings-reset)
- [Debug Mode](#debug-mode)
- [Requirements](#requirements)
- [Contributing](#contributing)
- [Community & Feedback](#community--feedback)
- [Credits](#credits)
- [AI Assistance](#ai-assistance)
---
## User Essentials
**New to KOAssistant?** Start here for the fastest path to productivity:
1. ✅ **[Quick Setup](#quick-setup)** — Install, add API key, restart (5 minutes)
2. 🔒 **[Privacy Settings](#privacy--data)** — Some features require opt-in; configure what data you share
3. 🎯 **[Recommended Setup](#recommended-setup)** — Configure gestures and explore key features (10 minutes)
4. 🧪 **[Testing Your Setup](#testing-your-setup)** — Web inspector for experimenting (optional but highly recommended)
5. 💰 **[Free Tiers](#free-tier-providers)** — Don't want to pay? See free provider options
**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) can be disabled via **[Settings → KOReader Integration](#koreader-integration)**. Use only what you need.
---
## Quick Setup
**Get started in 3 steps:**
### 1. Install the Plugin
If you are updating, follow the same steps, and just choose merge folder and replace/overwrite any matching files. An automatic updater is plannes.
Download koassistant.koplugin.zip from latest [Release](https://github.com/zeeyado/koassistant.koplugin/releases) -> Assets or clone:
```bash
git clone https://github.com/zeeyado/koassistant.koplugin
```
Copy 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/
```
### 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
```bash
cp apikeys.lua.sample apikeys.lua
```
Edit `apikeys.lua` and add your API key(s):
```lua
return {
anthropic = "your-key-here", -- console.anthropic.com
openai = "", -- platform.openai.com
-- See apikeys.lua.sample for all 16 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](#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](#free-tier-providers).
### 3. Restart KOReader
Find KOAssistant Settings in: **Tools → Page 2 → KOAssistant**
### 4. Configure Privacy Settings (Optional)
Some features require opt-in to work:
- **Analyze Highlights, Connect with Notes** → Enable "Allow Highlights & Annotations"
- **X-Ray, Recap with actual book content** → Enable "Allow Text Extraction"
Go to **Settings → Privacy & Data** to configure. See [Privacy & Data](#privacy--data) for details.
> **Quick option:** Use **Preset: Full** to enable all data sharing at once. Or leave defaults (personal content private, basic context shared).
---
## Recommended Setup
### Getting Started Checklist
After setting up your API key, complete these steps for the best experience:
- [ ] **Configure privacy settings** — Enable data sharing for features you want (Settings → Privacy & Data). See [Privacy & Data](#privacy--data)
- [ ] **Set up gesture access** — See [Configure Quick Access Gestures](#configure-quick-access-gestures) for the recommended two-step setup (Quick Settings in file browser + Quick Actions in reader, same gesture)
- [ ] **Explore the highlight menu** — Translate and Explain are included by default; 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** — Configure response languages with native script pickers (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)
> **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
**Recommended quick 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): 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 and knowledge context
- **Temperature & Reasoning** — Adjust creativity level and toggle Anthropic/Gemini reasoning (has no effect on other providers)
- **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
- **Chat History & Browse Notebooks** — Quick access to saved chats and notebooks
- **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
To show/hide buttons in the Quick Settings panel, use **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, Book Info
- **Summary management** — "View Summary" (if summary exists) or "Generate Summary" (if not) for cached document summaries
- **Utilities** — Translate Page, View/Edit Notebook, Chat History, Continue Last Chat, New Book Chat/Action, General Chat/Action, Quick Settings, View Caches
You can add any book action to Quick Actions via **Action Manager → hold action → "Add to Quick Actions"**. To reorder or remove actions, use **Settings → Quick Actions Settings → Panel Actions**. To show/hide utility buttons (Translate Page, Chat History, etc.), use **Settings → Quick Actions Settings → QA Panel Utilities**. Defaults can also be removed.
> **Tip**: For quick access, assign Quick Settings and Quick Actions to their own gestures (e.g., two-finger tap, 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, New Book Chat/Action
- Toggle Dictionary Bypass, Toggle Highlight Bypass
- Translate Current 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 Current 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](#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 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, X-Ray, Translate Page) 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](#behaviors)** | Control response style (concise, detailed, custom) | Settings → Actions & Prompts → Manage Behaviors |
| **[Domains](#domains)** | Add project-like context to conversations | Settings → Actions & Prompts → Manage Domains |
| **[Actions](#actions)** | Create your own prompts and workflows | Settings → Actions & Prompts → Manage Actions |
| **Quick Actions** | Fast access to reading actions while in a book | Gesture → "KOAssistant: Quick Actions" |
| **[Highlight Menu](#highlight-menu-actions)** | Actions in highlight popup (2 defaults: Translate, Explain) | Manage Actions → Add to Highlight Menu |
| **[Dictionary Integration](#dictionary-integration)** | AI-powered word lookups when selecting single words | Settings → Dictionary Settings |
| **[Bypass Modes](#bypass-modes)** | Instant AI actions without menus | Settings → Dictionary/Highlight Settings |
| **Reasoning/Thinking** | Enable deep analysis for complex questions | Settings → Advanced → Reasoning |
| **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, Zotero, or similar tools to ensure titles, authors, and identifiers are correct.
- **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.
- **Try different behavior styles**: 22 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, multi-book 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** — **Full chat interface** with 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](tests/README.md) for full setup instructions
**Quick Start:**
```bash
cd /path/to/koassistant.koplugin
lua tests/inspect.lua --web
# Then open http://localhost:8080 in a browser
```
**Pro 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 Highlights or Connect with Notes to work fully. See [Privacy Controls](#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), but none currently access KOReader's built in advanced local statistics. 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
- Reading progress (percentage)
- Chapter info (current 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 and annotations — your saved highlights and personal notes, 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.)
### Privacy Controls
**Settings → Privacy & Data** provides three quick presets:
| Preset | What it does |
|--------|--------------|
| **Default** | Progress and chapter info shared for context-aware features. Personal content (highlights, annotations, notebook) stays private. |
| **Minimal** | Maximum privacy. Only your question and book metadata are sent. Even progress and chapter info are disabled. |
| **Full** | All data sharing enabled for full functionality. Does not automatically enable text extraction (see below). |
**Individual toggles** (under Data Sharing Controls):
- **Allow Highlights & Annotations** — Your saved highlights and personal notes (default: OFF)
- **Allow Notebook** — Notebook entries for the book (default: OFF)
- **Allow Reading Progress** — Current reading position percentage (default: ON)
- **Allow Chapter Info** — Chapter title, chapters read, time since last opened (default: ON)
**Trusted Providers:** Mark providers you fully trust (e.g., local Ollama) to bypass all data sharing controls.
**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.
### 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, Summarize/Analyze Document, and highlight actions like "Explain in Context" to analyze what you've read. Without it enabled, these features rely solely on the AI's training knowledge of the book (which works for well-known titles but may be inaccurate for obscure works, and definitely sub-par (basically unusable) for research papers and articles).
**Why it's off by default:**
1. **Token costs** (primary reason, 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.
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 (+ Allow Highlights & Annotations if cache was built with annotations) | "Allow text extraction" and "Allow annotation use" (if cache was built with annotations) checked |
| Analyze/Summary caches | Allow Text Extraction | "Allow text extraction" checked |
| Highlights | Allow Highlights & Annotations | "Allow annotation use" checked |
| Annotations | Allow Highlights & Annotations | "Allow annotation use" checked |
| Notebook | Allow Notebook | "Allow notebook use" checked |
| Surrounding context* | None (hard-capped 2000 chars) | Auto-inferred from placeholder |
\* 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.
**Privacy compromise for X-Ray:** If you want X-Ray to analyze actual book content but prefer not to share your personal annotations, enable **only** "Allow Text Extraction" (leave "Allow Highlights & Annotations" off). X-Ray will analyze the book text without including your highlights or notes.
**Cache permission inheritance:** When the X-Ray cache is built, it records whether annotations were included. Actions that later reference `{xray_cache_section}` inherit these requirements:
- Cache built **without** annotations → Only "Allow Text Extraction" needed to use it
- Cache built **with** annotations → Both "Allow Text Extraction" AND "Allow Highlights & Annotations" required
If you change privacy settings after building a cache (e.g., disable annotations), actions may render the cache placeholder empty. To fix: either re-enable the required permissions, or regenerate the cache with your current settings using the "↻ Fresh" button.
**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 (for short papers, articles)
See [Troubleshooting → Text Extraction Not Working](#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](https://github.com/ollama/ollama) for installation and [FAQ](https://github.com/ollama/ollama/blob/main/docs/faq.md) 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, vLLM, llama.cpp server, and Text Generation WebUI all work via [Adding Custom Providers](#adding-custom-providers) since they support OpenAI-compatible APIs. Just input the Provider name and Model name and you are set -- they will be saved for future use.
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
KOAssistant does not include library-wide scanning or reading habit profiling.
**KOReader's deeper statistics:** KOReader's Statistics plugin collects extensive local data (reading time, pages per session, reading speed, session history, daily patterns). KOAssistant does **not** access any of this. If KOAssistant ever adds features that expose this behavioral data, they will require explicit opt-in with clear warnings about how revealing such information can be. Reading patterns over time create a surprisingly detailed personal profile.
---
## How to Use KOAssistant
KOAssistant works in **4 contexts**, each with its own set of built-in actions:
| Context | Built-in Actions |
|---------|------------------|
| **Highlight** | Explain, ELI5, Summarize, Elaborate, Connect, Connect (With Notes), Explain in Context, Analyze in Context, Thematic Connection (Smart), Translate, Dictionary, Quick Define, Deep Analysis |
| **Book** | Book Info, Similar Books, About Author, Historical Context, Related Thinkers, Key Arguments, Discussion Questions, Generate Quiz (Smart), Discussion Questions (Smart), X-Ray, Recap, Analyze Highlights, Analyze Document, Summarize Document, Extract Key Insights |
| **Multi-book** | Compare Books, Common Themes, Analyze Collection, Quick Summaries, Reading Order |
| **General** | Ask, News Update* |
*News Update requires web search — available in gesture menu by default but not in the general input dialog. See [General Chat](#general-chat) for details.
You can customize these, create your own, or disable ones you don't use. See [Actions](#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](#highlight-menu-actions) below.
**Bypass Mode**: Skip the highlight menu entirely and trigger your chosen action immediately when selecting text. See [Highlight Bypass](#highlight-bypass) below.
**Built-in Actions**:
| Action | Description |
|--------|-------------|
| **Ask** | Free-form question about the text |
| **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 Highlights & Annotations, Allow Notebook* |
| **Explain in Context** | Explain passage using surrounding book content ⚠️ *Requires: Allow Text Extraction* |
| **Explain in Context (Smart)** | Like above, but uses cached document summary for efficiency ⚠️ *Requires: Allow Text Extraction* |
| **Analyze in Context** | Deep analysis with book context and your annotations ⚠️ *Requires: Allow Text Extraction, Allow Highlights & Annotations* |
| **Analyze in Context (Smart)** | Like above, but uses cached document summary ⚠️ *Requires: Allow Text Extraction, Allow Highlights & Annotations* |
| **Thematic Connection (Smart)** | Analyze how a passage connects to the book's larger themes ⚠️ *Requires: Allow Text Extraction* |
| **Translate** | Translate to your configured language |
| **Dictionary** | Full dictionary entry: definition, etymology, synonyms, usage (also accessible via dictionary popup) |
| **Quick Define** | Minimal lookup: brief definition only, no etymology or synonyms |
| **Deep Analysis** | Linguistic deep-dive: morphology, word family, cognates, etymology path |
**Smart variants** (use cached summary):
Several actions have Smart variants that use cached document summaries instead of raw book text. This is faster, cheaper, and works especially well for repeated queries.
| Action | Context | What it does |
|--------|---------|--------------|
| **Explain in Context (Smart)** | Highlight | Explain passage using cached summary |
| **Analyze in Context (Smart)** | Highlight | Deep analysis using cached summary + annotations |
| **Thematic Connection (Smart)** | Highlight | Analyze how passage connects to larger themes |
| **Discussion Questions (Smart)** | Book | Generate discussion prompts grounded in summary |
| **Generate Quiz (Smart)** | Book | Comprehension quiz with answers using summary |
**When to use Smart variants:**
- Longer documents (research papers, textbooks, novels)
- Repeated queries on the same book
- Books the AI isn't trained on (need context for every query)
**How it works:**
- First use: Prompts to generate a reusable summary (generates via `summarize_full_document`)
- Subsequent uses: Uses cached summary (much faster and cheaper)
- Token savings: ~100K raw text → ~2-8K cached summary per query
**Managing summaries:**
- **Generate**: Quick Actions → "Generate Summary" (when no summary exists)
- **View**: Quick Actions → "View Summary" (when summary exists), or use the "View Summary" gesture
- **File browser**: "View Summary (KOA)" button appears when a book has a cached summary
- **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 Quick Actions to save tokens on future queries.
See [Response Caching → "Generate Once, Use Many Times"](#response-caching-x-rayrecap) for full details on the summary cache system.
**What the AI sees**: Your highlighted text, plus document metadata (title, author). Actions like "Explain in Context" and "Analyze in Context" also use extracted book 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](#privacy--data). See [Template Variables](#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](#save-to-note) for details.
> **Tip**: Add frequently-used actions to the highlight menu (Settings → Menu Customization → 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 → "KOAssistant" or while reading, use gesture or menu
Some actions work from the file browser (using only 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.
**Built-in Actions**:
| Action | Description |
|--------|-------------|
| **Ask** | Free-form question about the book |
| **Book Info** | Overview, significance, and why to read it |
| **Find Similar** | Recommendations for similar books |
| **About Author** | Author biography and writing style |
| **Historical Context** | When written and historical significance |
| **Related Thinkers** | Intellectual landscape: influences, contemporaries, and connected thinkers |
| **Key Arguments** | Thesis, evidence, assumptions, and counterarguments (non-fiction) |
| **Discussion Questions** | Comprehension, analytical, and interpretive prompts for book clubs or study |
| **Discussion Questions (Smart)** | Like above, but uses cached summary for grounded questions ⚠️ *Requires: Allow Text Extraction* |
| **Generate Quiz (Smart)** | Comprehension quiz with answers (multiple choice, short answer, essay) ⚠️ *Requires: Allow Text Extraction* |
| **X-Ray** | Structured reference guide: characters, locations, themes, timeline ⚠️ *Best with: Allow Text Extraction* |
| **Recap** | "Previously on..." style summary to help you resume reading ⚠️ *Best with: Allow Text Extraction* |
| **Analyze Highlights** | Discover patterns and connections in your highlights ⚠️ *Requires: Allow Highlights & Annotations* |
| **Analyze Document** | Deep analysis of complete short documents (papers, articles, notes) |
| **Summarize Document** | Comprehensive summary of entire document |
| **Extract Key Insights** | Actionable takeaways and ideas worth remembering |
**What the AI sees**: Document metadata (title, author). For Analyze Highlights: your annotations. For full document actions: entire document text.
#### 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 up to current position | Allow Text Extraction |
| **Recap** | Book text up to current position | Allow Text Extraction |
| **Analyze Highlights** | Your highlights and annotations | Allow Highlights & Annotations |
| **Analyze Document** | Entire document | Allow Text Extraction |
| **Summarize Document** | Entire document | Allow Text Extraction |
| **Extract Key Insights** | Entire document | Allow Text Extraction |
| **Discussion Questions (Smart)** | Cached summary | Allow Text Extraction |
| **Generate Quiz (Smart)** | Cached summary | Allow Text Extraction |
> ⚠️ **Privacy settings required:** These actions won't have access to your reading data unless you enable the corresponding setting in **Settings → Privacy & Data**. Without the setting enabled, the AI will attempt to use only its training knowledge (works for famous books, less accurate for obscure works). A "*Response generated without: ...*" notice will appear in the chat to indicate what data was requested but not provided.
> **Tip:** Highlight actions can also use text extraction. "Explain in Context" and "Analyze in Context" use `{book_text_section}` to understand your highlighted passage within the broader book context. See [Highlight Mode](#highlight-mode) for details.
**X-Ray/Recap**: These actions work in two modes:
- **Without text extraction** (default): AI uses only the title/author and relies on its training knowledge of the book. Works for well-known titles; may be inaccurate for obscure works.
- **With text extraction**: AI analyzes actual book content up to your reading position. More accurate but costs more tokens. Enables response caching for incremental updates.
> ⚠️ **To enable text extraction:** Go to Settings → Privacy & Data → Text Extraction → Allow Text Extraction. This is OFF by default to avoid unexpected token costs.
**Full Document Actions** (Analyze, Summarize, Extract Insights): Designed for short content—research papers, articles, notes—where you want AI to see everything regardless of reading position. These general-purpose actions adapt to your content type and work especially well with [Domains](#domains). For example, with a "Linguistics" domain active, analyzing a linguistics paper will naturally focus on relevant aspects.
> **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](#custom-actions) for details.
> **📦 Response Caching (Experimental)**: When text extraction is enabled (Settings → Privacy & Data → Text Extraction), X-Ray and Recap responses are automatically cached per book. Running them again after reading further sends only the *new* content to update the previous analysis—faster and cheaper. This feature is experimental and feedback is welcome. See [Response Caching](#response-caching-x-rayrecap) 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** only: title, author, identifiers
- **Reading mode** additionally has access to **document state**: reading progress, highlights, annotations, notebook, extracted text
**Reading-only actions** (hidden in file browser): X-Ray, Recap, Analyze Highlights, Analyze Document, Summarize Document, Extract Key Insights, Discussion Questions (Smart), Generate Quiz (Smart). These require document state that isn't available until you open the book.
Custom actions using placeholders like `{reading_progress}`, `{book_text}`, `{full_document}`, `{highlights}`, `{annotations}`, or `{notebook}` are filtered the same way. The Action Manager shows a `[reading]` indicator for such actions.
### Multi-Document Mode
**Access**: Select multiple documents in File Browser → tap any → "Compare with KOAssistant"
**Built-in Actions**:
| Action | Description |
|--------|-------------|
| **Ask** | Free-form question about the selected books |
| **Compare** | What makes each book 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 book |
| **Reading Order** | Suggest optimal order based on dependencies, difficulty, themes |
**What the AI sees**: List of titles, authors, and identifiers
### 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 |
|--------|-------------|
| **Ask** | Free-form question (default) |
| **News Update** | Get today's top news stories from Al Jazeera with links ⚠️ *Requires: Web Search* |
**Managing the Input Dialog:**
The general input dialog shows only actions you've explicitly added. By default, it shows just "Ask". To add more 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](#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, or OpenRouter, the latter of which support web search for models from other providers that KOAssistant currently doesn't have dedicated web support for, e.g. OpenAI, XAI, Perplexity models.
> **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](#web-search) for more on per-action overrides.
### Quick UI Features
- **Settings Icon (Input)**: Tap the gear icon in the input dialog title bar to open **Quick Settings**—a streamlined two-column panel providing quick access to frequently-changed settings without navigating through the full settings menu. See [Recommended Setup](#recommended-setup) for details on what's available in this panel.
- **Settings Icon (Viewer)**: Tap the gear icon in the chat viewer title bar to adjust font size and text alignment (cycles left/justified/right on each click)
- **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](#save-to-note) below)
- **Other**: Turn on off Text/Markdown view, Debug view mode, add Tags, Change Domain, etc
### 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 Add to Notebook)
4. KOReader's Edit Note dialog opens with the response pre-filled
5. Edit if desired, then save — 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 Settings → 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, multi-book, or general chat contexts.
---
## How the AI Prompt Works
When you trigger an action, KOAssistant builds a complete request from several components:
**System message** (sets AI context):
1. **Behavior** — Communication style: tone, formatting, verbosity (see [Behaviors](#behaviors))
2. **Domain** — Knowledge context: subject expertise, terminology (see [Domains](#domains))
3. **Language instruction** — Which language to respond in (see [AI Language Settings](#ai-language-settings))
**User message** (your specific request):
1. **Context data** — Highlighted text, book metadata, surrounding sentences (automatic)
2. **Action prompt** — The instruction template with placeholders filled in
3. **User input** — Your optional free-form addition (the text you type)
### Context Data vs Placeholders
There are two ways book metadata (title, author) can be included in a request:
1. **`[Context]` section** — Automatically added as a labeled section at the start of the user message. Controlled by `include_book_context` flag on actions.
2. **Direct placeholders** — `{title}`, `{author}`, `{author_clause}` substituted directly into the prompt template.
**For highlight actions:** Use `include_book_context = true` to add a `[Context]` section. The highlighted text is the main subject, so book info is supplementary context.
**For book actions:** Use `{title}` and `{author_clause}` directly in the prompt (e.g., "Tell me about {title}"). The book IS the subject, so it belongs in the prompt itself.
### Skipping System Components
Some actions skip parts of the system message because they'd interfere:
- **Translate** and **Dictionary** actions skip both **Domain** and **Language instruction** by default. Domain context can significantly alter translation/definition results since the AI follows domain instructions. The target language is already specified directly in the prompt template.
- Custom actions can toggle these via the **"Skip domain"** and **"Skip language instruction"** checkboxes in the action wizard.
> **Tip:** When creating custom actions, experiment with domain on and off to see what produces better results for your use case. For precise linguistic tasks (translation, grammar checking), skipping domain usually helps. For analytical tasks (explaining concepts in a field), domain context improves results.
### Behavior vs Domain vs Action Prompt
All three can contain instructions to the AI, and deciding what to put where can be confusing:
| Component | Scope | Best for |
|-----------|-------|----------|
| **Behavior** | Global (one selection for all chats) | Communication style, formatting rules, verbosity level |
| **Domain** | Sticky (persists until you change it) | Subject expertise, terminology, analytical frameworks |
| **Action prompt** | Per-action (specific task) | Task-specific instructions, output format, what to analyze |
> **Tip:** For most custom actions, using a standard behavior (like "Standard" or "Full") and putting detailed instructions in the action prompt works best. Reserve custom behaviors for broad style preferences you want across all interactions. Reserve domains for deep subject expertise you want across multiple actions.
> **Tip:** There is natural overlap between behavior and domain — both are sent in the system message and both can influence the AI's approach. The key difference: behavior controls *manner* (how it speaks), domain controls *substance* (what it knows). A "scholarly" behavior makes the AI formal and rigorous; a "philosophy" domain makes it reference philosophers and logical frameworks.
---
## Actions
Actions define what you're asking the AI to do. Each action has a prompt template, and can optionally override behavior, domain, language, temperature, reasoning, and provider/model settings. See [How the AI Prompt Works](#how-the-ai-prompt-works) for how actions fit into the full request.
When you select an action and start a chat, you can optionally add your own input (a question, additional context, or specific request) which gets combined with the action's prompt template.
### Managing Actions
**Settings → Actions & Prompts → Manage Actions**
- Toggle built-in and custom actions on/off
- Create new actions with the wizard
- Edit or delete your custom actions (marked with ★)
- Edit settings for built-in actions (temperature, thinking, provider/model, AI behavior)
- Duplicate/Copy existing Actions to use them as template (e.g. to make a slightly different variant)
**Action indicators:**
- **★** = Custom action (editable)
- **⚙** = Built-in action with modified settings
**Editing built-in actions:** Long-press any built-in action → "Edit Settings" to customize its advanced settings without creating a new action. Use "Reset to Default" to restore original settings.
### Tuning Built-in Actions
Don't like how a built-in action behaves? Clone and customize it:
**Common tweaks:**
1. **Action too verbose?**
- **Example:** Elaborate gives you walls of text
- **Fix:** Duplicate the action, edit the prompt to add "Keep response under 150 words"
- **Why clone?** Preserves the original if you want to compare
2. **Want different model for specific action?**
- **Example:** Quick Define lookups are slow with your main model
- **Fix:** Edit the Quick Define action → Advanced → Set provider to "anthropic" and model to "claude-haiku-4-5"
- **Why:** Different actions benefit from different models:
- **Fast/cheap models** for Dictionary, Quick Define, Translate (speed matters, task is simple)
- **Standard models** for Explain, Summarize, ELI5 (balanced quality and cost)
- **Reasoning models** for Deep Analysis, Key Arguments, academic tasks (complex thinking)
- **Examples:** Haiku/GPT-4.1-nano/qwen2.5:0.5b for lookups; Sonnet/GPT-5/llama3.3 for general use; Opus/o3/deepseek-r1 for analysis
3. **Want action without domain/language?**
- **Example:** Translate action giving unexpected results due to your domain
- **Fix:** Edit action → Name & Context → Check "Skip domain"
- **Why:** Domain context can alter translation style/register
4. **Compare different approaches?**
- Duplicate an action multiple times with different prompts
- Name them "Explain (brief)", "Explain (detailed)", "Explain (ELI5)"
- Test which works best for your reading style
**Quick workflow:**
1. Long-press any action in Manage Actions
2. Select "Duplicate" or "Edit Settings"
3. Modify prompt/settings/model
4. Test in [web inspector](#testing-your-setup)
5. Use on e-reader when satisfied
**Tip:** Disable built-in actions you don't use (tap to toggle) — cleaner action menus.
### Creating Actions
The action wizard walks through 4 steps:
1. **Name & Context**: Set button text and where it appears (highlight, book, multi-book, general, or both). Options:
- *View Mode* — Choose how results display: Standard (full chat), Dictionary Compact (minimal popup), or Translate (translation-focused UI)
- *Include book info* — Send title/author with highlight actions
- *Skip language instruction* — Don't send your language preferences (useful when prompt already specifies target language)
- *Skip domain* — Don't include domain context (useful for linguistic tasks like translation)
- *Add to Highlight Menu* / *Add to Dictionary Popup* — Quick-access placement
2. **AI Behavior**: Optional behavior override (use global, select a built-in, none, or write custom text)
3. **Action Prompt**: The instruction template with placeholder insertion (see [Template Variables](#template-variables))
4. **Advanced**: Provider, Model, Temperature, and Reasoning/Thinking overrides
### Template Variables
Insert these in your action prompt to reference dynamic values:
| Variable | Context | Description | Privacy Setting |
|----------|---------|-------------|-----------------|
| `{highlighted_text}` | Highlight | The selected text | — |
| `{title}` | Book, Highlight | Book title | — |
| `{author}` | Book, Highlight | Book author | — |
| `{author_clause}` | Book, Highlight | " by Author" or empty | — |
| `{count}` | Multi-book | Number of books | — |
| `{books_list}` | Multi-book | Formatted list of books | — |
| `{translation_language}` | Any | Target language from settings | — |
| `{dictionary_language}` | Any | Dictionary response language from settings | — |
| `{context}` | Highlight | Surrounding text context (sentence/paragraph/characters) | — |
| `{context_section}` | Highlight | Context with "Word appears in this context:" label | — |
| `{reading_progress}` | Book (reading) | Current reading position (e.g., "42%") | Allow Reading Progress |
| `{progress_decimal}` | Book (reading) | Reading position as decimal (e.g., "0.42") | Allow Reading Progress |
| `{chapter_title}` | Book (reading) | Current chapter name | Allow Chapter Info |
| `{chapters_read}` | Book (reading) | Number of chapters read (e.g., "5 of 12") | Allow Chapter Info |
| `{time_since_last_read}` | Book (reading) | Time since last reading session (e.g., "3 days ago") | Allow Chapter Info |
| `{highlights}` | Book, Highlight (reading) | All highlights from the document | Allow Highlights & Annotations |
| `{annotations}` | Book, Highlight (reading) | All highlights with user notes | Allow Highlights & Annotations |
| `{highlights_section}` | Book, Highlight (reading) | Highlights with "My highlights so far:" label | Allow Highlights & Annotations |
| `{annotations_section}` | Book, Highlight (reading) | Annotations with "My annotations:" label | Allow Highlights & Annotations |
| `{notebook}` | Book, Highlight (reading) | Content from the book's KOAssistant notebook | Allow Notebook |
| `{notebook_section}` | Book, Highlight (reading) | Notebook with "My notebook entries:" label | Allow Notebook |
| `{book_text}` | Book, Highlight (reading) | Extracted book text from start to current position | Allow Text Extraction |
| `{book_text_section}` | Book, Highlight (reading) | Same as above with "Book content so far:" label | Allow Text Extraction |
| `{full_document}` | Book, Highlight (reading) | Entire document text (start to end, regardless of position) | Allow Text Extraction |
| `{full_document_section}` | Book, Highlight (reading) | Same as above with "Full document:" label | Allow Text Extraction |
| `{surrounding_context}` | Highlight (reading) | Text surrounding the highlighted passage | — |
| `{surrounding_context_section}` | Highlight (reading) | Same as above with "Surrounding text:" label | — |
| `{xray_cache}` | Book (reading) | Cached X-Ray (if available) | Allow Text Extraction (+ Annotations if cache used them) |
| `{xray_cache_section}` | Book (reading) | Same as above with progress label | Allow Text Extraction (+ Annotations if cache used them) |
| `{analyze_cache}` | Book (reading) | Cached document analysis (if available) | Allow Text Extraction |
| `{analyze_cache_section}` | Book (reading) | Same as above with label | Allow Text Extraction |
| `{summary_cache}` | Book (reading) | Cached document summary (if available) | Allow Text Extraction |
| `{summary_cache_section}` | Book (reading) | Same as above with label | Allow Text Extraction |
**Context notes:**
- **Book** = Available in both reading mode and file browser
- **Highlight** = Always reading mode (you can't highlight without an open book)
- **(reading)** = Reading mode only — requires an open book. Book actions using these placeholders are automatically hidden in file browser
- **Privacy Setting** = The setting that must be enabled in Settings → Privacy & Data for this variable to have content. If disabled, the variable returns empty (section placeholders disappear gracefully)
#### Section vs Raw Placeholders
"Section" placeholders automatically include a label and gracefully disappear when empty:
- `{book_text_section}` → "Book content so far:\n[content]" or "" if empty
- `{full_document_section}` → "Full document:\n[content]" or "" if empty
- `{context_section}` → "Word appears in this context: [text]" or "" if empty
- `{highlights_section}` → "My highlights so far:\n[content]" or "" if empty
- `{annotations_section}` → "My annotations:\n[content]" or "" if empty
- `{notebook_section}` → "My notebook entries:\n[content]" or "" if empty
- `{surrounding_context_section}` → "Surrounding text:\n[content]" or "" if empty
- `{xray_cache_section}` → "Previous X-Ray (as of X%):\n[content]" or "" if empty
- `{analyze_cache_section}` → "Document analysis:\n[content]" or "" if empty
- `{summary_cache_section}` → "Document summary:\n[content]" or "" if empty
"Raw" placeholders (`{book_text}`, `{full_document}`, `{highlights}`, `{annotations}`, `{notebook}`, `{surrounding_context}`, `{xray_cache}`, `{analyze_cache}`, `{summary_cache}`) give you just the content with no label, useful when you want custom labeling in your prompt.
**Tip:** Use section placeholders in most cases. They prevent dangling references—if you write "Look at my highlights: {highlights}" in your prompt but highlights is empty, the AI sees confusing instructions about nonexistent content. Section placeholders include the label only when content exists.
> **Privacy note:** Section placeholders adapt to [privacy settings](#privacy--data). If a data type is disabled (or not yet enabled), the corresponding placeholder returns empty and section variants disappear gracefully. For example, `{highlights_section}` is empty unless you enable **Allow Highlights & Annotations**. You don't need to modify actions to match your privacy preferences—they adapt automatically.
> **Double-gating (for custom actions):** When creating custom actions from scratch, sensitive data requires BOTH a global privacy setting AND a per-action permission flag. This prevents accidental data leakage—if you enable "Allow Text Extraction" globally, your new custom actions still need "Allow text extraction" checked to actually use it. Built-in actions already have appropriate flags set, and copied actions inherit them. Document cache placeholders require the same permissions as their source: `{xray_cache}` needs both text extraction AND annotations, while `{analyze_cache}` and `{summary_cache}` only need text extraction. See [Text Extraction and Double-gating](#text-extraction-and-double-gating) for the full reference table.
#### Utility Placeholders
Utility placeholders provide reusable prompt fragments that can be inserted into any action. Currently available:
| Placeholder | Expands To |
|-------------|------------|
| `{conciseness_nudge}` | "Be direct and concise. Don't restate or over-elaborate." |
| `{hallucination_nudge}` | "If you don't recognize this or the content seems unclear, say so rather than guessing." |
**Why use these?**
- **`{conciseness_nudge}`**: Some AI models (notably Claude Sonnet 4.5) tend to produce verbose responses. This provides a standard instruction to reduce verbosity without sacrificing quality. Used in 14 built-in actions including Explain, Summarize, ELI5, and the context-aware analysis actions.
- **`{hallucination_nudge}`**: Prevents AI from fabricating information when it doesn't recognize a book or author. Used in 12 built-in templates including Book Info, Find Similar, Historical Context, and all multi-book actions.
**For custom actions:** Add these placeholders at the end of your prompts where appropriate. The placeholders are replaced with the actual text at runtime, so you can also use the raw text directly if you prefer.
### Tips for Custom Actions
- **Skip domain** for linguistic tasks: Translation, grammar checking, dictionary lookups work better without domain context influencing the output. Enable "Skip domain" in the action wizard for these.
- **Skip language instruction** when the prompt already specifies a target language (using `{translation_language}` or `{dictionary_language}` placeholders), to avoid conflicting instructions.
- **Put task-specific instructions in the action prompt**, not in behavior. Behavior applies globally; action prompts are specific. Use a standard behavior and detailed action prompts for most custom actions.
- **Temperature matters**: Lower (0.3-0.5) for deterministic tasks (translation, definitions). Higher (0.7-0.9) for creative tasks (elaboration, recommendations).
- **Experiment with domains**: Try running the same action with and without a domain to see what works for your use case. Some actions benefit from domain context (analysis, explanation), others don't (translation, grammar).
- **Test before deploying**: Use the [web inspector](#testing-your-setup) to test your custom actions before using them on your e-reader. You can try different settings combinations and see exactly what's sent to the AI.
- **Reading-mode placeholders**: Book actions using `{reading_progress}`, `{book_text}`, `{full_document}`, `{highlights}`, `{annotations}`, `{notebook}`, or `{chapter_title}` are **automatically hidden** in File Browser mode because these require an open book. This filtering is automatic—if your custom book action uses these placeholders, it will only appear when reading. Highlight actions are always reading-mode (you can't highlight without an open book). The action wizard shows a `[reading]` indicator for such actions.
- **Document caches**: Reference previous X-Ray, Analyze Document, or Summary results without re-running them using `{xray_cache_section}`, `{analyze_cache_section}`, or `{summary_cache_section}`. Useful for building on previous analysis. These require `use_book_text = true` since the cached content derives from book text (X-Ray cache additionally requires use of annotations, if the cache was built with annotations in the first place). Two usage patterns:
- **Supplement**: Add cache reference to actions that otherwise use only title/author (like Discussion Questions or Key Arguments). The section placeholder disappears if no cache exists, so there's no major change for users without caches—just bonus context when available.
- **Replace**: Use cached summary INSTEAD of raw book text for token savings on long books. Built-in **Smart actions** (Explain in Context Smart, Analyze in Context Smart) implement this pattern. Add `requires_summary_cache = true` to your custom actions to trigger automatic summary generation when needed. See [Response Caching](#response-caching-x-rayrecap) for details.
- **Surrounding context**: Use `{surrounding_context_section}` in highlight actions to include text around the highlighted passage. This is live extraction (not cached), hard-capped at 2000 characters. Particularly useful for **custom dictionary-like actions** that need sentence context for single-word lookups—look at the built-in `quick_define`, `dictionary`, and `deep` actions for inspiration. Uses your Dictionary Settings for context mode (sentence, paragraph, or character count).
### File-Based Actions
For more control, create `custom_actions.lua`:
```lua
return {
{
text = "Grammar Check",
context = "highlight",
behavior_override = "You are a grammar expert. Be precise and analytical.",
prompt = "Check grammar: {highlighted_text}"
},
{
text = "Discussion Questions",
context = "book",
prompt = "Generate 5 discussion questions for '{title}'{author_clause}."
},
{
text = "Series Order",
context = "multi_book",
prompt = "What's the reading order for these books?\n\n{books_list}"
},
}
```
**Optional fields**:
- `behavior_variant`: Use a preset behavior by ID (e.g., "standard", "mini", "full", "gpt_style_standard", "perplexity_style_full", "reader_assistant", "none")
- `behavior_override`: Custom behavior text (overrides variant)
- `provider`: Force specific provider ("anthropic", "openai", etc.)
- `model`: Force specific model for the provider
- `temperature`: Override global temperature (0.0-2.0)
- `reasoning_config`: Per-provider reasoning settings (see below)
- `extended_thinking`: Legacy: "off" to disable, "on" to enable (Anthropic only)
- `thinking_budget`: Legacy: Token budget when extended_thinking="on" (1024-32000)
- `enabled`: Set to `false` to hide
- `use_book_text`: Allow text extraction for this action (acts as permission gate; also requires global "Allow Text Extraction" setting enabled). The actual extraction is triggered by placeholders in the prompt: `{book_text_section}` extracts to current position, `{full_document_section}` extracts entire document. Also gates access to analysis cache placeholders.
- `use_annotations`: Include document highlights and annotations (`use_highlights` is deprecated, use this instead)
- `use_reading_progress`: Include reading position and chapter info
- `use_reading_stats`: Include time since last read and chapter count
- `use_notebook`: Include content from the book's KOAssistant notebook
- `use_surrounding_context`: Include surrounding text for highlight actions (auto-inferred from `{surrounding_context}` placeholder)
- `include_book_context`: Add book info to highlight actions
- `cache_as_xray`: Save this action's result to the X-Ray cache (for other actions to reference)
- `cache_as_analyze`: Save this action's result to the document analysis cache
- `cache_as_summary`: Save this action's result to the document summary cache
- `skip_language_instruction`: Don't include language instruction in system message (default: off; Translate/Dictionary use true since target language is in the prompt)
- `skip_domain`: Don't include domain context in system message (default: off; Translate/Dictionary use true)
- `domain`: Force a specific domain by ID (overrides the user's current domain selection; file-only, no UI for this yet)
- `enable_web_search`: Override global web search setting (true=force on, false=force off, nil=follow global)
**Per-provider reasoning config** (new in v0.6):
```lua
reasoning_config = {
anthropic = { budget = 4096 }, -- Extended thinking budget
openai = { effort = "medium" }, -- low/medium/high
gemini = { level = "high" }, -- low/medium/high
}
-- Or: reasoning_config = "off" to disable for all providers
```
See `custom_actions.lua.sample` for more examples.
### Highlight Menu Actions
Add frequently-used highlight actions directly to KOReader's highlight popup for faster access.
**Default actions** (included automatically):
1. **Translate** — Instant translation of selected text
2. **Explain** — Get an explanation of the passage
**Other built-in actions you can add**: ELI5, Summarize, Elaborate, Connect, Connect (With Notes), Explain in Context, Analyze in Context, Dictionary, Quick Define, Deep Analysis
**Adding more actions**:
1. Go to **Manage Actions**
2. Hold any highlight-context action
3. Tap **"Add to Highlight Menu"**
4. A notification reminds you to restart KOReader
Actions appear as "KOA: Explain", "KOA: Translate", etc. in the highlight popup.
**Managing actions**:
- Use **Settings → Highlight Settings → Highlight Menu Actions** to view all enabled actions
- Tap an action to move it up/down or remove it
- Default actions can be removed (they won't auto-reappear)
- Actions requiring user input (like "Ask") cannot be added
**Note**: Changes require an app restart since the highlight menu is built at startup.
> **Prefer a cleaner menu?** You can disable KOAssistant's highlight menu integration entirely via **Settings → KOReader Integration**. The main "KOAssistant" button and quick action shortcuts (Translate, Explain, etc.) have separate toggles.
---
## Dictionary Integration
With help from contributions to [assistant.koplugin](https://github.com/omer-faruq/assistant.koplugin) by [plateaukao](https://github.com/plateaukao) and others
KOAssistant integrates with KOReader's dictionary system, providing AI-powered word lookups when you select words in a document.
> **Tip:** For best results, duplicate a built-in dictionary action and customize it for your language pair. Set a light model (e.g. Haiku) for speed, and make it your bypass action for one-tap lookups.
> **Don't need dictionary integration?** Disable it entirely via **Settings → KOReader Integration → Show in Dictionary Popup**.
### How It Works
When you select a word in a document, KOReader normally shows its dictionary popup. With KOAssistant's dictionary integration, you can:
1. **Add AI actions to the dictionary popup** — Tap the "AI Dictionary" button to access a menu of AI-powered word analysis options
2. **Bypass the dictionary entirely** — Skip KOReader's dictionary and go directly to AI for word lookups
**Default dictionary popup actions** (3 included):
1. **Dictionary** — Full entry: definition, etymology, synonyms, usage
2. **Quick Define** — Minimal: brief definition only
3. **Deep Analysis** — Linguistic deep-dive: morphology, word family, cognates
You can add other highlight actions to this menu via **Manage Actions → hold action → "Add to Dictionary Popup"**.
### Dictionary Settings
**Settings → Dictionary Settings**
| Setting | Description | Default |
|---------|-------------|---------|
| **AI Buttons in Dictionary Popup** | Show "AI Dictionary" button in KOReader's dictionary popup | On |
| **Response Language** | Language for definitions. Can follow Translation Language (`↵T`) or be set independently | `↵T` |
| **Context Mode** | Surrounding text sent with lookup: None, Sentence, Paragraph, or Characters | None |
| **Context Characters** | Character count when using "Characters" mode | 100 |
| **Disable Auto-save** | Don't auto-save dictionary lookups to chat history | On |
| **Enable Streaming** | Stream responses in real-time (shows text as it generates) | Off |
| **Dictionary Popup Actions** | Configure which actions appear in the AI menu (reorder, add custom) | 3 built-in |
| **Bypass KOReader Dictionary** | Skip native dictionary, go directly to AI action | Off |
| **Bypass Action** | Which action triggers on bypass (try Quick Define for speed) | Dictionary |
| **Bypass: Follow Vocab Builder** | Respect KOReader's Vocabulary Builder auto-add setting during bypass | On |
> **Tip:** Test different dictionary actions and context modes in the [web inspector](#testing-your-setup) to find what works best for your reading. Consider creating custom dictionary actions for your specific language pair.
### Dictionary Popup Actions (3 included by default)
When "AI Button in Dictionary Popup" is enabled, tapping the AI button shows a menu of actions. Three built-in dictionary actions are included by default:
| Action | Purpose | Includes |
|--------|---------|----------|
| **Dictionary** | Standard dictionary entry | Definition, pronunciation, etymology, synonyms, usage examples |
| **Quick Define** | Fast, minimal lookup | Brief definition only—no etymology, no synonyms |
| **Deep Analysis** | Linguistic deep-dive | Morphology (roots, affixes), word family, etymology path, cognates |
The **first action** in your list is the default when tapping the AI button. You can also set any action as the **Bypass Action** for instant one-tap lookups.
**Configure this menu:**
1. **Settings → Dictionary Settings → Dictionary Popup Actions**
2. Enable/disable actions, reorder them, or add custom actions
3. Consider setting "Quick Define" as bypass action for faster responses
### Context Mode: When to Use It
Context mode sends surrounding text (sentence/paragraph/characters) with your lookup. The compact view has a **Ctx** button to toggle context on-demand.
**Context OFF (default)**
- ✅ Natural, complete dictionary response
- ✅ Multiple definitions and homographs included (e.g., "round" as noun, verb, adjective)
- ✅ Faster response (less text to process)
- ❌ Doesn't know which meaning is intended in your reading
**Context ON**
- ✅ Precise, disambiguated definition for THIS usage
- ✅ Explains word's role in THIS specific sentence
- ❌ May miss other meanings/senses of the word (context disambiguates, so homographs aren't shown)
- ❌ Slightly slower (more text to process)
**Best practice:** Use context OFF for general lookups; turn context ON (via Ctx button) when you need disambiguation.
### Dictionary Language Indicators
The dictionary language setting shows return symbols when following other settings:
- `↵` = Following Primary Language
- `↵T` = Following Translation Language
See [How Language Settings Work Together](#how-language-settings-work-together) for details.
### RTL Language Support
Dictionary, translate, general chat, and cache viewers have special handling for right-to-left (RTL) languages:
- **Automatic RTL mode**: When your dictionary or translation language is set to an RTL language, results automatically use Plain Text mode for proper font rendering. For general chat and cache viewers (X-Ray, Analyze, Summary), the content is checked—if RTL characters outnumber Latin, it switches to RTL mode (right-aligned text + Plain Text). This can be configured via **Settings → Display Settings → Text Mode for RTL Dictionary**, **Text Mode for RTL Translate**, and **Auto RTL mode for Chat**.
- **BiDi text alignment**: Entries with RTL content display with correct bidirectional text alignment. Mixed RTL/LTR content (e.g., Arabic headwords with English pronunciation guides) renders in the correct reading order.
- **IPA transcription handling**: Phonetic transcriptions are anchored to display correctly alongside RTL headwords.
> **Note:** For best RTL rendering, Plain Text mode is recommended. The automatic RTL settings handle this for dictionary, translate, general chat, and cache viewers, while preserving your global Markdown/Plain Text preference when content is not predominantly RTL.
### Custom Dictionary Actions
The built-in dictionary actions use unified prompts that work across many scenarios:
- **Monolingual lookups** (e.g., English word → English definitions)
- **Bilingual lookups** (e.g., French word → English definitions and translations)
- **Context-aware disambiguation** (toggle Ctx ON in compact view)
For the best results, **create custom dictionary actions tailored to your specific use case**:
1. **Settings → Actions & Prompts → Manage Actions**
2. Find "Dictionary" or "Quick Define" and tap to **duplicate**
3. Edit the duplicate with prompts specific to your language pair or learning style
4. **Settings → Dictionary Settings → Dictionary Popup Actions** — add your custom action
5. Set it as the **Bypass Action** for one-tap access
6. Consider changing the bypass action to "Quick Define" for faster responses, or to your custom action
**Examples:**
- **"EN→AR Dictionary"** — Explicit Arabic translation with English metalanguage
- **"Monolingual French"** — Definitions only in French, no translations
- **"Etymology Focus"** — Start from Deep Analysis, remove morphology sections
- **"Quick Vocab"** — Minimal definition + example sentence for flashcard creation
**Tips:**
- Use a **lighter model** (e.g., Haiku) for dictionary actions via per-action model override
- **Context OFF** (default) gives complete entries with all senses; **Context ON** disambiguates for the specific usage
- For RTL languages, the compact view automatically uses Plain Text mode
### Dictionary Bypass
When bypass is enabled, selecting a word skips KOReader's dictionary popup entirely and immediately triggers your chosen AI action.
**To enable:**
1. Settings → Dictionary Settings → Bypass KOReader Dictionary → ON
2. Settings → Dictionary Settings → Bypass Action → choose action (default: Dictionary)
**Recommended setup:** Set "Quick Define" or a custom lightweight action as your bypass action for faster responses. Use the full "Dictionary" action when you need etymology and synonyms.
**Toggle via gesture:** Assign "KOAssistant: Toggle Dictionary Bypass" to a gesture for quick on/off switching.
**Note:** Dictionary bypass (and the dictionary popup AI button) uses compact view by default for quick, focused responses.
### Compact View Features
The compact dictionary view provides two rows of buttons:
- **Row 1:** MD ON/TXT ON, Copy, +Note, Wiki, +Vocab
- **Row 2:** Expand, Lang, Ctx, [Action], Close
**MD ON / TXT ON** — Toggle between Markdown and Plain Text view modes. Shows "MD ON" when Markdown is active, "TXT ON" when Plain Text is active. For RTL languages, this may default to TXT ON automatically based on your settings.
**Copy** — Copies the AI response only (plain text). Unlike the full chat view, compact view always copies just the response without metadata or asking for format.
**+Note** — Save the AI response as a note attached to your highlighted word in KOReader's annotation system. The button is greyed out if word position data isn't available (e.g., when launched from certain contexts).
**Wiki** — Look up the word in Wikipedia using KOReader's built-in Wikipedia integration.
**+Vocab** — Add the looked-up word to KOReader's Vocabulary Builder. After adding, the button changes to "Added" (greyed out). See [Vocabulary Builder Integration](#vocabulary-builder-integration) below.
**Expand** — Open the response in the full-size chat viewer with all options (continue conversation, save, export, etc.).
**Lang** — Re-run the lookup in a different language (picks from your configured languages). Closes the current view and opens a new one with the updated result.
**Ctx: ON/OFF** — Toggle surrounding text context. If your lookup was done without context (mode set to "None"), you can turn it on to get a context-aware definition (Sentence by default). If context was included, you can turn it off for a plain definition. Re-runs the lookup with the toggled setting. This setting is not sticky, so context will revert to your main setting on closing the window.
**[Action]** — Shows the abbreviated name of the current dictionary action (e.g., "Dict", "Quick", "Deep"). Tap to switch to a different dictionary popup action. If only one other action is available, switches directly; otherwise shows a picker with all available dictionary actions.
**Close** — Close the compact view.
**RTL-aware rendering**: When viewing dictionary results for RTL languages, the compact view automatically uses Plain Text mode (if enabled in settings) and applies correct bidirectional text alignment for proper display of RTL content.
### Vocabulary Builder Integration
When using dictionary lookups in compact view, KOAssistant integrates with KOReader's Vocabulary Builder:
- **Auto-add enabled** (Vocabulary Builder ON in KOReader settings): Words are automatically added to vocab builder when looked up via dictionary bypass. A greyed "Added" button confirms the word was added.
- **Auto-add disabled** (Vocabulary Builder OFF): A "+Vocab" button appears to manually add the looked-up word to the vocabulary builder.
The vocab button appears in compact/minimal buttons view (dictionary bypass and popup actions).
**Bypass: Follow Vocab Builder Auto-add** (Settings → Dictionary Settings): Controls whether dictionary bypass respects KOReader's Vocabulary Builder auto-add setting. Disable this if you use bypass for analyzing words you already know and don't want them added to the vocabulary builder.
### Chat Saving
Dictionary lookups are **not auto-saved** by default (`Disable Auto-save` is on). This prevents cluttering your chat history with individual word lookups.
- **Auto-save disabled** (default): Lookups are not saved automatically. If you expand a compact view chat, the Save button becomes active so you can save manually to the current document.
- **Auto-save enabled** (toggle off): Dictionary chats follow your general chat saving settings (auto-save all or auto-save continued).
---
## Bypass Modes
Bypass modes let you skip menus and immediately trigger AI actions.
### Dictionary Bypass
Skip KOReader's dictionary popup when selecting words. Useful for language learners who want instant AI definitions.
**How it works:**
1. Select a word in the document
2. Instead of dictionary popup → AI action triggers immediately
3. Response appears in **compact view** (minimal UI optimized for quick lookups — see [Compact View Features](#compact-view-features))
**Configure:** Settings → Dictionary Settings → Bypass KOReader Dictionary
### Highlight Bypass
Skip the highlight menu when selecting text. Useful when you always want the same action (e.g., translate).
**How it works:**
1. Select text by long-pressing and dragging
2. Instead of highlight menu → AI action triggers immediately
3. Response appears in **full view** (standard chat viewer)
**Configure:** Settings → Highlight Settings → Enable Highlight Bypass
### Bypass Action Selection
Both bypass modes let you choose which action triggers:
| Bypass Mode | Default Action | Where to Configure |
|-------------|----------------|-------------------|
| Dictionary | Dictionary | Settings → Dictionary Settings → Bypass Action |
| Highlight | Translate | Settings → Highlight Settings → Bypass Action |
You can select any highlight-context action (built-in or custom) as your bypass action. **Recommended:** Set dictionary bypass to "Quick Define" or a custom lightweight action for faster responses.
### Gesture Toggles
Quick toggle bypass modes without entering settings:
- **KOAssistant: Toggle Dictionary Bypass** - Assign to gesture
- **KOAssistant: Toggle Highlight Bypass** - Assign to gesture
Toggling shows a brief notification confirming the new state.
### Custom Action Gestures
You can add any **book** or **general** action to KOReader's gesture menu:
1. Go to **Settings → Actions & Prompts → Manage Actions**
2. Hold any book or general action to see details
3. Tap **"Add to Gesture Menu"**
4. **Restart KOReader** for changes to take effect
5. Configure the gesture in **Settings → Gesture Manager**
Actions with gestures show a `[gesture]` indicator in the Action Manager list.
**Where gestures appear:**
- **Book actions** → Reader gestures only (requires open book; grayed out in File Browser)
- **General actions** → Available in both contexts (can add to Reader and/or File Browser gestures)
**Why only book and general?** Highlight actions require selected text, and multi-book actions require file browser multi-select — neither can be triggered via gestures.
**Note:** Changes require restart because KOReader's gesture system loads available actions at startup.
### Available Gesture Actions
**Reader Only** (require open book; grayed out in File Browser gesture settings):
- KOAssistant: Quick Actions — Reading actions panel
- KOAssistant: New Book Chat/Action — Start a chat about current book or access book actions
- KOAssistant: X-Ray — Generate book reference guide
- KOAssistant: Recap — Get a story summary
- KOAssistant: Analyze Highlights — Analyze your annotations
- KOAssistant: Translate Current Page — Translate visible page text
- KOAssistant: View Notebook — View current book's notebook
- KOAssistant: Edit Notebook — Edit current book's notebook
- KOAssistant: View Summary — View cached document summary
- KOAssistant: View Caches — View all document caches
**General** (available in both File Browser and Reader gesture settings):
- KOAssistant: Quick Settings — Two-column settings panel
- KOAssistant: Chat History — Browse all saved chats
- KOAssistant: Continue Last Saved Chat — Resume most recently saved chat
- KOAssistant: Continue Last Opened Chat — Resume most recently viewed chat
- KOAssistant: General Chat/Action — Start a new general conversation or run a general action
- KOAssistant: Settings — Open main settings menu
- KOAssistant: Action Manager — Manage all actions
- KOAssistant: Manage Behaviors — Select or create behaviors
- KOAssistant: Manage Domains — Manage knowledge domains
- KOAssistant: Dictionary Popup Manager — Configure dictionary popup actions
- KOAssistant: Change Primary Language — Quick language picker
- KOAssistant: Change Translation Language — Pick translation target
- KOAssistant: Change Dictionary Language — Pick dictionary language
- KOAssistant: Change Provider — Quick provider picker
- KOAssistant: Change Model — Quick model picker
- KOAssistant: Change Behavior — Quick behavior picker
- KOAssistant: Change Domain — Quick domain picker
- KOAssistant: Toggle Dictionary Bypass — Toggle dictionary bypass on/off
- KOAssistant: Toggle Highlight Bypass — Toggle highlight bypass on/off
- KOAssistant: Browse Notebooks — Open Notebook Manager
**Custom Actions:**
- Book actions you add via "Add to Gesture Menu" → Reader Only
- General actions you add via "Add to Gesture Menu" → Available in both contexts
### Translate Current Page
A special gesture action to translate all visible text on the current page:
**Gesture:** KOAssistant: Translate Current Page
This extracts all text from the visible page/screen and sends it to the Translate action. Uses Translate View (see below) for a focused translation experience.
**Works with:** PDF, EPUB, DjVu, and other supported document formats.
### Translate View
All translation actions (Highlight Bypass with Translate, Translate Current Page, highlight menu Translate) use a specialized **Translate View** — a minimal UI focused on translations.
**Button layout:**
- **Row 1:** MD ON/TXT ON (toggle markdown), Copy, Save to Note (when highlighting)
- **Row 2:** → Chat (expand to full chat), Show/Hide Original, Lang, Close
**Key features:**
- **Lang button** — re-run translation with a different target language (picks from your configured languages)
- **Save to Note button** — save translation directly to a highlight note (closes translate view after save)
- **Auto-save disabled** by default (translations are ephemeral like dictionary lookups)
- **Copy/Note Content** options — choose what to include: full, question + response, or translation only
- **Configurable original text visibility** — follow global setting, always hide, hide long text, or never hide
- **→ Chat button** — expands to full chat view with all options (continue conversation, save, etc.)
**Configure:** Settings → Translate Settings
> 📖 **Quick Reference: Bypass Mode Use Cases**
>
> - **Dictionary Bypass** → Language learners wanting instant definitions
> - **Highlight Bypass** → Quick translations or instant explanations
> - **Translate Current Page** → Academic reading, foreign language texts
>
> All bypass modes can be toggled via gestures for quick on/off switching.
---
## Behaviors
Behavior defines the AI's personality, communication style, and response guidelines. It is sent **first** in the system message, before domain context and language instruction. See [How the AI Prompt Works](#how-the-ai-prompt-works) for the full picture.
### What Behavior Controls
- Response tone (conversational, academic, concise)
- Formatting preferences (when to use lists, headers, etc.)
- Communication style (brief vs detailed explanations)
### Built-in Behaviors
23 built-in behaviors are available, organized by provider style. Each style comes in three sizes (Mini ~160-220 tokens, Standard ~400-500 tokens, Full ~1150-1325 tokens):
**Provider-inspired styles (all provider-agnostic — use any style with any provider):**
- **Claude Style** (Mini, Standard, Full) — Based on [Anthropic Claude guidelines](https://docs.anthropic.com/en/release-notes/system-prompts). **Claude Style (Standard) is the default.**
- **DeepSeek Style** (Mini, Standard, Full) — Analytical and methodical
- **Gemini Style** (Mini, Standard, Full) — Clear and adaptable
- **GPT Style** (Mini, Standard, Full) — Conversational and helpful
- **Grok Style** (Mini, Standard, Full) — Witty with dry humor
- **Perplexity Style** (Mini, Standard, Full) — Research-focused with source transparency
**Reading-focused:**
- **Reader Assistant** (~350 tokens) — Reading companion persona (used by Smart actions)
**General utility:**
- **Concise** (~55 tokens) — Brevity-focused, minimal guidance for direct responses
**Specialized (used by specific actions, hidden from quick pickers):**
- **Direct Dictionary** (~30 tokens) — Minimal guidance for dictionary lookups (used by Dictionary action)
- **Detailed Dictionary** (~30 tokens) — Guidance for detailed linguistic analysis (used by Deep Analysis action)
- **Direct Translator** (~80 tokens) — Direct translation without commentary (used by Translate action)
**Changing the default:** Settings → Actions & Prompts → Manage Behaviors, tap to select. Or use Quick Settings (gear icon or gesture) → Behavior.
### Sample Behaviors
The [behaviors.sample/](behaviors.sample/) folder contains additional behaviors beyond the built-ins:
- **Reading-specialized**: Scholarly, Religious/Classical, Creative writing
- **More provider styles**: Additional variations and experimental styles
To use: copy desired files from [behaviors.sample/](behaviors.sample/) to `behaviors/` folder. They'll appear in the behavior selector under "FROM BEHAVIORS/ FOLDER".
### Custom Behaviors
Create your own behaviors via:
1. **Files**: Add `.md` or `.txt` files to `behaviors/` folder
2. **UI**: Settings → Actions & Prompts → Manage Behaviors → Create New
**File format** (same as domains):
- Filename becomes the behavior ID: `concise.md` → ID `concise`
- First `# Heading` becomes the display name
- Rest of file is the behavior text sent to AI
See [behaviors.sample/README.md](behaviors.sample/README.md) for full documentation.
### Per-Action Overrides
Individual actions can override the global behavior:
- Use a different variant (minimal/full/none)
- Provide completely custom behavior text
- Example: The built-in Translate action uses a dedicated "translator_direct" behavior for direct translations
### Relationship to Other Components
- Behavior is the **first** component in the system message, followed by domain and language instruction
- Individual actions can override or disable behavior (see [Actions](#actions) → Creating Actions)
- Behavior controls *how* the AI communicates; for *what* context it applies, see [Domains](#domains)
- There is natural overlap: a "scholarly" behavior and a "critical reader" domain both influence analytical depth, but from different angles (style vs expertise)
> 🎭 **Remember:** Behavior = HOW the AI speaks | Domain = WHAT it knows
>
> Combine them strategically: Perplexity Style + research domain = source-focused academic analysis. Test combinations in the [web inspector](#testing-your-setup).
---
## Domains
Domains provide **project-like context** for AI conversations. When selected, the domain context is sent **after** behavior in the system message. See [How the AI Prompt Works](#how-the-ai-prompt-works) for the full picture.
### How It Works
The domain text is included in the system message after behavior and before language instruction. The AI uses it as background knowledge for the conversation. You can have very small, focused domains, or large, detailed, interdisciplinary ones. Both behavior and domain benefit from prompt caching (50-90% cost reduction on repeated queries, depending on provider).
### Built-in Domain
One domain is built-in: **Synthesis**
This serves as an example of what domains can do. For more options/inspiration, see [domains.sample/](domains.sample/) which includes specialized sample domains.
### Creating Domains
Create domains via:
1. **Files**: Add `.md` or `.txt` files to `domains/` folder
2. **UI**: Settings → Actions & Prompts → Manage Domains → Create New
**File format**:
**Example**: Truncated part of `domains/synthesis.md` (from [domains.sample/](domains.sample/))
```markdown
# Synthesis
This conversation engages ideas across traditions—mystical, philosophical,
psychological, scientific—seeking resonances without forcing false equivalences.
...
## Orientation
Approach texts and questions through multiple lenses simultaneously:
- Depth Psychology: Jungian concepts as maps of inner territory
- Contemplative Traditions: Sufism, Taoism, Buddhism, Christian mysticism
- Philosophy: Western and non-Western traditions
- Scientific Cosmology: Modern physics, complexity theory, emergence
...
```
- Filename becomes the domain ID: `my_domain.md` → ID `my_domain`
- First `# Heading` becomes the display name (or derived from filename)
- Metadata in `` comments is optional (for tracking token costs)
- Rest of file is the context sent to AI
- Supported: `.md` and `.txt` files
See [domains.sample/](domains.sample/) for examples including classical language support and interpretive frameworks.
### Selecting Domains
Select a domain via the **Domain** button in the chat input dialog, or through Quick Settings. Once selected, the domain **stays active** for all subsequent chats until you change it or select "None".
**Note**: Keep this sticky behavior in mind — if you set a domain for one task, it will apply to all following actions (including quick actions that don't open the input dialog, unless they have been set to Skip Domain) until you clear it. You can change the domain through the input dialog, Quick Settings, or gesture actions.
### Browsing by Domain
Chat History → hamburger menu → **View by Domain**
**Note**: Domains are for context, not storage. Chats still save to their book or "General AI Chats", but you can filter by domain in Chat History.
### Tips
- **Domain can be skipped per-action**: Actions like Translate and Dictionary skip domain by default because domain instructions alter their output. You can toggle "Skip domain" for any custom action in the action wizard (see [Actions](#actions)).
- **Domain vs Behavior overlap**: Both are sent in the system message. Behavior = communication style, Domain = knowledge context. Sometimes content could fit in either. Rule of thumb: if it's about *how to respond*, put it in behavior. If it's about *what to know*, put it in a domain.
- **Domains affect all actions in a chat**: Once selected, the domain applies to every message in that conversation. If an action doesn't benefit from domain context, use "Skip domain" in that action's settings.
- **Cost considerations**: Large domains increase token usage on every request. Keep domains focused. Most major providers (Anthropic, OpenAI, Gemini, DeepSeek) cache system prompts automatically (50-90% cost reduction on repeated domain context).
- **Preview domain effects**: Use the [web inspector](#testing-your-setup) to see how domains affect request structure and AI responses before using them on your e-reader.
---
## Managing Conversations
### Auto-Save
By default, all chats are automatically saved. You can disable this in Settings → Conversations.
- **Auto-save All Chats**: Save every new conversation
- **Auto-save Continued Chats**: Only save when continuing from history (i.e. from an already saved chat)
### Chat History
**Access**: Tools → KOAssistant → Chat History
Hamburger Menu:
Browse saved conversations organized by:
- **By Document**: Chats grouped by book (including "General AI Chats", "Multi-Book Chats", and individual books)
- **By Domain**: Filter by knowledge domain (hamburger menu → View by Domain)
- **By Tag**: Filter by tags you've added (hamburger menu → View by Tag)
Delete all chats
**Chat organization**: In the document view, chats are sorted as:
1. 💬 General AI Chats
2. �