Deckle, a morning newspaper for your Kindle, built on your own machine

Deckle turns EPUBs you own into Kindle books that behave like store books, and puts them on your Kindle over USB: Enhanced Typesetting, a cover that shows, real page numbers, X-Ray and Word Wise.

Desktop app for macOS and Windows, plus a CLI. Written in Rust (Tauri for the UI). GPL-3.0. No account, no subscription, no telemetry.

It also prints you a morning paper. The Deckle Daily (preview) builds an edition on your machine from your town's weather and news, your RSS feeds and the articles you saved, with a generated front page as its cover, and delivers it when the Kindle connects. Details in docs/daily.md.

A sideloaded EPUB is a second-class book on a Kindle. Amazon's own conversion through Send to Kindle drops Enhanced Typesetting, X-Ray and Word Wise. calibre plugins and forum recipes fix each of these one at a time, and they conflict: the trick that turns on X-Ray gives you a grey cover on a 2024 Scribe. Deckle does all of it in one pipeline and picks the right tradeoff for the Kindle that's plugged in.

Install Kindle Previewer 4 (free, from Amazon). It's the only thing that produces Enhanced Typesetting. Deckle drives it and doesn't bundle it.

Download Deckle from Releases:

macOS 14+, Apple Silicon or Intel: .dmg, signed and notarized.

Windows 11: -setup.exe (per-user, no admin) or .msi, code-signed. A new certificate can still trigger SmartScreen: More info → Run anyway.

Linux .deb / .AppImage: everything works except conversion, because Kindle Previewer doesn't run on Linux.

Plug in the Kindle, drop EPUBs on the window, press Send to Kindle.

Quit calibre, Android File Transfer and Amazon's Send to Kindle first. Only one program at a time can talk to an MTP Kindle (Scribe, Colorsoft, Paperwhite 2024).

Early. The whole pipeline works from the app and the CLI and is tested against fixtures and a simulated mass-storage Kindle. On real hardware it's been verified on a Kindle Scribe (2024); other models are pending. Results per device are in docs/devices.md. Bug reports with your model and firmware are very welcome.

Enhanced Typesetting (KFX). Previewer makes a KPF; Deckle packs it into the monolithic KFX a Kindle reads, with approximate page numbers.

Covers that stick. On Kindles where it can, Deckle writes its own cover thumbnail and puts it back on every send.

X-Ray. Finds the people and terms in the book. Optionally an LLM (Anthropic, or any OpenAI-compatible endpoint including local Ollama) writes spoiler-free descriptions, and Wikipedia adds summaries.

Word Wise. Hints from a Wiktionary-derived English lexicon, pointed at the Kindle's own dictionary when it has one.

Other inputs. .docx, .txt, web articles (a URL, .webloc/.url, or a saved .html) go through the same pipeline. A finished .kfx is sent as is.

Optional cleanups. Fill missing metadata from Open Library, fix typography, turn footnotes into pop-up notes.

Library. A plain folder (Author/Title/ plus a deckle.json), no database. Deckle can tell you which books on the Kindle it could now build better and re-send them.

The Deckle Daily (preview). A morning newspaper built locally from weather, local news and your RSS feeds, with full article text, delivered when the Kindle connects. Details in docs/daily.md.

Network

Converting and sending a book is offline. Deckle goes online only for:

A book sent with features carries an ASIN, so the Kindle itself may ask Amazon about it. That's the Kindle, not Deckle. Settings → Default mode → Cover first avoids it.

The interesting parts, with format notes in docs/formats/.

KPF → KFX. Kindle Previewer's CLI outputs a KPF: a zip around a SQLite database of Ion fragments, with 1 KiB fingerprint records injected every MiB. A Kindle wants a monolithic KFX. jhowell's kfxlib (GPL-3, part of the KFX Input calibre plugin) has the complete conversion. Deckle's KFX writer is a Rust port of it, tested byte for byte against kfxlib's output, so no Python is involved. Page numbers come from the same port (1,850 positions per page).

Covers vs. features. X-Ray and Word Wise only load for books marked EBOK with an ASIN. An EBOK whose ASIN the store doesn't know shows a grey cover, and Amazon overwrites any cover thumbnail with a "no image" file once the Kindle goes online. PDOC books always show their embedded cover but get no X-Ray or Word Wise. So Deckle decides per Kindle:

Amazon reuses a print ISBN-10 as that edition's ASIN, so Open Library is enough to find a candidate without scraping Amazon. You can override the mode per book.

MTP on macOS. macOS has no MTP stack, so Deckle has a small PTP/MTP client over USB. Kindle specifics: always the 32-bit ObjectInfo layout (libmtp switches layouts on the Kindle's nameless root folders and every write then fails with 0xA806), zero-length packets after full-packet data phases, TransactionID 0 for OpenSession, and never create a documents folder.

X-Ray is a SQLite sidecar (<book>.sdr/XRAY.entities.<ASIN>.asc) in the schema WordDumb reverse-engineered, with occurrences at KFX positions. Entities come from a heuristic tuned on Pride and Prejudice: honorifics, speech verbs, stop lists, alias merging.

Word Wise is a sidecar that holds no text. LanguageLayer.en.<ASIN>.kll stores positions and sense ids into a dictionary already on the Kindle (system/kll/*.klld). Deckle matches the book against its own lexicon (174k senses, inflections mapped to lemmas, difficulty from wordfreq) and points the hints at the Kindle's English dictionary. If the Kindle doesn't have one, Deckle installs its own in the Chinese slot: set Word Wise → Language → 中文 on the Kindle; the hints are still English. Per-book proper-noun detection keeps "Darcy" from being glossed as a unit of permeability.

MTP Kindles hide system/, so Word Wise there needs the Kindle's kll.en.en.klld copied to documents/deckle/ once (a jailbroken Kindle with KOReader can do it). Without it, Word Wise is skipped and the book and X-Ray still ship.

cargo build --release -p deckle-cli # binary at target/release/deckle deckle devices # connected Kindles (mass storage and MTP) deckle run book.epub --to device # convert, enrich, send deckle run book.epub --to ./out --cde pdoc # export to a folder, cover-first deckle run book.epub --to device --cde ebok --asin B0XXXXXXXX # real ASIN: store cover on MTP Kindles deckle run book.epub --to device --cde ebok --llm anthropic # X-Ray descriptions (ANTHROPIC_API_KEY) deckle run book.epub --to device --cde ebok --llm openai
--llm-endpoint http://localhost:11434/v1 --llm-model llama3 # or a local model deckle run book.epub --to device --word-wise-level 3 # hints for rarer words only deckle run notes.docx --to device # also .txt, a URL, .webloc/.url/.html deckle inspect book.epub --json # metadata, spine, TOC, warnings deckle convert book.kpf -o book.kfx # repackage an existing Previewer KPF

deckle library init ~/Books/Deckle # keep a copy of everything you send deckle library list --series # grouped by series deckle library reprocess --dry-run # books Deckle could build better now deckle kindle books # what's on the Kindle, and free space

deckle --help and deckle <command> --help list everything else.

Rust (stable, 1.85+), Node 22, pnpm. Conversion needs macOS or Windows.

cargo test --workspace cd apps/desktop && pnpm install && pnpm tauri dev # app with hot reload pnpm tauri build # installers in target/release/bundle

Releases: docs/release.md. Word Wise database builder: data/wordwise/README.md. Design specs live in docs/superpowers/specs/.

Deckle builds on research and code from the MobileRead community: jhowell's KFX Input/Output and kfxlib, jloutsch's kfxgen, xxyzz's WordDumb and Proficiency, seapy's kindle-cli, and calibre's Kindle driver. Word Wise definitions come from Wiktionary via kaikki.org (CC BY-SA 4.0), word frequencies from wordfreq (CC BY-SA 4.0).

Kindle Previewer is Amazon's and is never bundled. Kindle is a trademark of Amazon.com, Inc. Deckle is not affiliated with Amazon.