A KOReader plugin that puts an AI assistant inside your book. Highlight a passage and ask what it means, ask about the page you're looking at (including diagrams and tables), or just open a general chat. Answers render as formatted text and can be exported as readable articles.
Powered by OpenRouter, so you can point it at almost any model — Claude, GPT, Gemini, Llama — by editing one setting.
Asking about a circuit diagram — something you can't highlight.
Recorded on a real Kindle. The AI asks a clarifying question first, offered as
tappable buttons. Token count and cost are shown under each reply.
Wait for the reply shortened; keyboard entry cut.
Prerequisites: a jailbroken Kindle with KOReader and KUAL already installed, and an OpenRouter account.
Developed and tested on a Kindle 11th-gen, firmware 5.17.1.0.3 (Winterbreak). Other jailbroken Kindles running KOReader should work, but haven't been tested.
This is the walkthrough I followed on my own device: It's Time to Jailbreak Your Kindle. by Dammit Jeff — it covers the jailbreak plus installing KUAL and KOReader, which is everything this plugin needs.
For the authoritative and continuously updated instructions, use the MobileRead Kindle forums and the Winterbreak page.
Check your firmware version first (Settings → Device Options → Device Info). Kindle jailbreaks are firmware-specific: a method that works on one version can fail — or require a downgrade — on another, and Amazon patches them in updates. Any video is a snapshot of whatever was current when it was recorded, so confirm against the sources above before starting. Turn off auto-updates once you're jailbroken, or an OTA update will undo it.
- Ask about a highlight — select text, then Explain / Summarize / Translate / ELI5 / Define in context, or type your own question. The book title, author, chapter and reading position go along as context.
- Ask about the current page — sends a screenshot, so you can ask about figures, tables, equations or scripts that text selection can't capture.
- General chat — from the KOReader menu or straight from KUAL.
- Spoiler protection — optionally tells the model not to reveal anything past your current position.
- Clarifying questions — when your request is ambiguous the AI can offer tappable options instead of making you type.
- History — every chat is saved, searchable, renameable, and survives reboots.
- Export — turn any reply or whole chat into an HTML article you can read in KOReader like any other book.
- Optional web search — let the model look things up for a reply, toggled per message.
Designed for e-ink throughout: one screen refresh per action, no streaming, no animation, buttons instead of typing wherever possible.
Text selection can only reach text. A diagram, a table, an equation, a footnote in a script your Kindle can't select, a scanned or image-only PDF page — all of it is invisible to a plugin that works from highlights.
Ask about the current page captures what's actually on screen and sends it to a vision model, so you can ask "what's this chart showing?" or "walk me through this equation" about anything you can see. You can combine it with a highlight, too — send the passage and the page it sits on.
It's handled carefully:
- You confirm before anything is uploaded. A screenshot can contain copyrighted or private material, so the plugin says so and asks first.
- Your model doesn't have to support images. If it doesn't, you're told and offered a picker filtered to vision-capable models — pick one and the page you were asking about goes through, no restart, no lost context.
- Your history stays plain text. Saved chats keep the text plus a local path to the image; the multimodal request is assembled at send time and the stored chat is never rewritten.
- Screenshots are cleaned up. They live per-chat and are deleted when that chat is, or when you cancel the capture.
Kindle Wi-Fi drops constantly, and a dropped connection often means the server already generated — and billed — the reply. So failures are only ever retried automatically when they provably cannot have produced a billed completion: HTTP 5xx, and TLS handshakes that never reached the server. Timeouts and resets are never auto-retried; you get a Retry button and decide.
Every reply shows its own token count and cost plus a running session total, and Test API key validates your key and shows your remaining credit — for free — before you spend anything.
The Wi-Fi radio dozes during the long wait for a non-streaming reply and kills the socket, so power-save is disabled before every request. Requests run in a cancellable subprocess, so a slow model never freezes the reader and you can always back out. Chat writes are atomic (write-then-rename), so a crash or a dead battery mid-save can't corrupt your history. If a request fails, your unsent message stays in the transcript ready to retry — nothing is lost.
The picker loads OpenRouter's live catalog, is searchable, shows each model's price per million tokens, and sorts by popularity, throughput or latency. Hold any row to favourite it. Set a fallback model and it takes over automatically when your primary errors. Models that can't do text chat are filtered out entirely.
Highlight context includes the title, author, chapter and your reading position — and with spoiler protection on, that position is sent to the model with an instruction not to reveal anything past it. Useful when you want a character explained without learning what happens to them in three chapters.
Every network call, file write and JSON parse is wrapped defensively — a malformed config or a failed save degrades to a clear message instead of taking KOReader down with it. Replies render as real formatted text (headings, lists, code blocks, tables) rather than a wall of markdown syntax.
Three pieces get copied over USB. Connect the Kindle and mount it as a drive —
its root (where documents/ lives) is /mnt/us/ on the device.
⬇ Download the latest release and unzip it — that's the easiest way to get the files below. (Cloning the repo works too.)
Copy the askai.koplugin/ folder to:
<Kindle>/koreader/plugins/askai.koplugin/
There is no on-device key entry — you paste the key into a file over USB, once.
a. Get a key. Sign in at
openrouter.ai/keys → Create key. Add credit
under Credits (a few dollars goes a long way),
and set a spend limit on the key while you're there. It looks like
sk-or-v1-….
b. Make the folder. On the mounted Kindle, create this folder if it isn't already there — on a fresh install it won't be, because KOReader only creates it the first time the plugin runs:
<Kindle>/koreader/settings/askai/
c. Create config.json inside it, containing just your key:
{
"openrouter_api_key": "sk-or-v1-YOUR-KEY-HERE"
}That's the whole minimum. The final path must be exactly:
<Kindle>/koreader/settings/askai/config.json
Windows hides file extensions by default, which is the single most common way this goes wrong: you make
config.jsonin Notepad and actually getconfig.json.txt, which the plugin can't see. Turn on View → File name extensions in Explorer and check. Use a plain-text editor — Notepad, TextEdit in plain text mode, VS Code — never Word or Pages, which substitute curly quotes and break the JSON.
Optional extra settings for config.json
{
"openrouter_api_key": "sk-or-v1-YOUR-KEY-HERE",
"default_model": "anthropic/claude-sonnet-4.5",
"app_referer": "https://github.com/your/repo",
"app_title": "Kindle AskAI"
}default_model sets the starting model (changeable later in Settings, which is
easier — it has a searchable picker). app_referer and app_title are just
how your usage is labelled in OpenRouter's dashboard.
Read this before pasting a key. The key is stored in plain text on the Kindle, and anyone with physical or SSH access to the device can read it. That's an accepted tradeoff for this design (there's no on-device keyboard entry, by choice), but it means you should:
- Use a dedicated key for the Kindle, not one you use elsewhere.
- Set a spend limit on it in the OpenRouter dashboard.
- Revoke it immediately if you lose the device or sell it.
Copy extensions/askai/ to:
<Kindle>/extensions/askai/
This adds an "Ask AI (KOReader)" entry to KUAL that boots KOReader straight into a new chat. Skip it if you'd rather always go through KOReader's menu.
If KUAL doesn't list it, make sure bin/launch.sh kept its executable bit
(copying over some filesystems strips it). Over SSH:
chmod +x /mnt/us/extensions/askai/bin/launch.shEject the Kindle and restart KOReader (KOReader menu → Exit, then relaunch). Plugins are only loaded at startup.
You should now see Ask AI in KOReader's Tools menu.
- Open Tools → Ask AI → Settings → Test API key. This costs nothing and tells you immediately whether the key works — do this before anything else.
- Open a book, highlight a sentence, tap Ask AI, and pick Explain.
If the key test passes and a highlight query returns text, you're done.
Under Tools → Ask AI → Settings:
| Setting | Default | Notes |
|---|---|---|
| Model | anthropic/claude-sonnet-4.5 |
Searchable live list from OpenRouter; hold an entry to favourite it |
| Fallback model | none | Tried automatically if the primary errors |
| Max response tokens | 1024 | Higher = longer answers, more cost |
| Temperature | 0.7 | Lower = more focused |
| HTTP timeout | 90s | Raise it on a slow connection |
| Clarifying questions | on | AI may ask before guessing |
| Include book context | on | Sends title/author/chapter/position with highlights |
| Spoiler protection | off | Turn on to avoid plot reveals past your position |
| Show token usage / cost | on | Per-reply and running total |
| Auto-title chats with AI | on | One cheap call names each chat |
Vision (asking about a page) needs a model that accepts images. If your current model doesn't, the plugin says so and offers to switch — the picker filters to vision-capable models automatically.
"Ask AI" isn't in the Tools menu at all.
Almost always a load error. Check the log — over SSH, or by reading the file
directly off the mounted drive at koreader/crash.log:
tail -n 120 /mnt/us/koreader/crash.logA traceback mentioning askai names the culprit. Also confirm the folder is
plugins/askai.koplugin/ (that exact name, .koplugin suffix included) and
that you restarted KOReader.
"No API key found."
The plugin can't find or can't parse config.json. In rough order of
likelihood:
- It's really
config.json.txt. Windows hides known extensions — enable View → File name extensions and look again. This is the most common cause by a wide margin. - Wrong folder. It must be
koreader/settings/askai/config.json— insidesettings/askai/, notsettings/, and not next to the plugin inplugins/askai.koplugin/. - Invalid JSON. Paste it into any JSON validator. A trailing comma, or curly “smart quotes” from Word/Pages, will break it — retype the quotes in a plain-text editor.
- KOReader wasn't restarted after you added the file.
"Invalid API key" from the key test. Usually a copy-paste artifact: a trailing space, a line break in the middle of the key, or a partial copy. Re-copy the whole key from OpenRouter.
"Out of credits." The key is valid but the account has no funds. Top up, or switch to a free model in Settings → Model.
Replies fail partway through, or "connection reset". Kindle Wi-Fi power-save dozes the radio during the long wait for a non-streaming reply. The plugin disables power-save around each request, but if it persists, disable it manually over SSH:
iw dev wlan0 set power_save offNote this resets on sleep/reconnect/reboot.
Don't blindly retry a reset. The server may have already generated and billed the reply. The plugin only auto-retries the cases that are safe (5xx, TLS handshake) and deliberately does not auto-retry timeouts.
A response is cut off mid-sentence. It hit the token ceiling. Raise Max response tokens, or tap Continue.
Bad model id (400).
Model ids must be the exact API id (anthropic/claude-sonnet-4.5), not the
label from the website. In particular the site's …-latest aliases are not
valid API ids. Use the built-in picker and this can't happen.
KUAL entry does nothing.
Check launch.sh is executable (see install step 3). It also only opens a chat
on a cold start — if KOReader is already running, the launcher won't re-open
it, and the request is discarded after a few minutes rather than surprising you
with a chat later.
/mnt/us/koreader/plugins/askai.koplugin/ the plugin
/mnt/us/koreader/settings/askai/
├── config.json your API key (plain text)
├── settings.lua on-device settings
├── models.json cached model list (1-day TTL)
└── chats/
├── index.json chat list
├── <id>.json one file per chat
└── assets/<id>/ page screenshots sent to the AI
/mnt/us/extensions/askai/ KUAL launcher
<KOReader home>/AskAI/ exported HTML articles
Uninstalling: delete those paths. Deleting a chat also deletes its screenshots.
Everything is sent to OpenRouter, which routes it to whichever model provider you selected. That includes your questions, the passages you highlight, book metadata, and — when you use the page feature — screenshots of what you're reading.
The plugin asks for explicit confirmation before the first screenshot upload. Nothing is sent anywhere until you take an action that asks for a reply. OpenRouter's data policy governs what happens next; some providers train on inputs and some don't, and that's configurable per-account in OpenRouter's settings.
The plugin is plain Lua against KOReader's own widget toolkit — no build step.
Edit a module, copy it to plugins/askai.koplugin/ on the device, and restart
KOReader (Lua is not hot-reloaded, so changes do nothing until a restart).
Parse-check anything you push using the device's own interpreter before restarting — a syntax error in any one module silently drops the whole plugin from the menu:
/mnt/us/koreader/luajit -e 'assert(loadfile("main.lua"))'Then read /mnt/us/koreader/crash.log to confirm a clean load.
Design notes and the device deploy loop live in
docs/, which is untracked (local to the working copy) — so a fresh clone won't have it.