# ZenOS: a redesigned interface layer for KOReader > ZenOS is a Lua plugin layer that rebuilds the KOReader interface with a personal Home page, a redesigned Library, a swipe-down Controls panel, a Launcher and a Zen page browser, while keeping KOReader itself underneath. It is GPL-3.0 licensed, released monthly, and it runs on the same devices KOReader already supports. **xZenLabs/zen-os** — A clean, minimal E-Reader experience - Repository: https://github.com/xZenLabs/zen-os - Website: https://zen-labs.org/zen-os - Stars: 846 · Forks: 50 - Language: Lua - License: GPL-3.0 - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/xzenlabs-zen-os ## What ZenOS actually is ZenOS describes itself as a customizable interface layer for KOReader. That phrasing is the whole design. It adds a personal Home page, a redesigned Library, a fast Controls panel, a Launcher, reader tools and unified settings, while keeping KOReader underneath. The distinction from a fork matters. KOReader is the reading engine, the document parser, the sync client and the plugin host. ZenOS is a layer that replaces the screens you interact with and leaves the machinery alone. A user who installs it still has KOReader, still has the KOReader plugin ecosystem, and still has the same reading engine, but a different set of menus and panels. The repository structure reflects that. The top level has main.lua, a _meta.lua, a common/ directory, modules/, config/, fonts/, icons/, locales/ and a spec/ directory for tests, with a .luacheckrc and a luacheck.sh for Lua linting, a build.sh, and a translation_utils.py for the translations. The primary language is Lua, and the topic tags name the devices it targets: Kindle, Kobo, PocketBook, Boox, eink devices, plus desktop and Android, and the plugin relationship to KOReader. The homepage is zen-labs.org/zen-os, and the README links the release page, an installation guide at docs/installation.md and a Discord community. ## The Home page and its widgets The Home page is the first thing ZenOS puts in front of you, and it is the part with the most design decisions in it. Widgets include date and time, a featured book, reading statistics, reading goals, a book strip and quotes. They are arranged within what the README calls the screen's space budget, which is a small screen constraint stated plainly: on a six inch e-ink panel there is not much room, and a widget that does not fit is a problem the layout has to solve rather than ignore. Widgets can be edited directly from Home, and presets can be applied and saved. The quotes widget is the one with an interesting data model. It can combine built-in quotes, annotations, and any selection of custom quote files stored in `koreader/settings/ZenOS/quotes/`, while the existing `koreader/settings/ZenOS/quotes.lua` file remains the primary custom file. So there is a legacy single file and a newer directory of files, and the widget draws from both. The book strip is the other substantial widget. It can switch between recent books, favourites, To Be Read, authors, series, languages, tags, collections, the Kindle Library when available, a folder, or a custom list. Optional strip controls can filter by book status, or launch actions, Controls, plugin menus and KOReader menus. Featured books support recent, To Be Read or a hand-picked title, with configurable metadata and progress labels. That is a lot of configuration surface for a home screen, and it is the clearest example of the philosophy stated in the README: less is more, with everything designed either to remove clutter or add clear value. ## The Controls panel and the swipe gesture The Controls panel is a swipe-down overlay, and it is the most immediately useful piece for anyone who spends time on a device with limited navigation options. Swipe down from anywhere and you get up to nine configurable controls plus brightness and warmth sliders. The buttons can toggle device features, run dispatcher actions, open plugins or KOReader menus, and expose installed integrations such as Bluetooth, Tailscale and ZenFM. The gesture handling has specifics that matter on an e-ink device where an accidental swipe is costly. Tapping Bluetooth toggles it, while holding it manages connections on Kindle, Kobo and PocketBook. Tailscale can toggle Wi-Fi by itself, which is the kind of detail that only appears when someone has actually used it on a device that has no other way to reach the network settings. Holding the minus button on a lighting slider jumps to zero, a shortcut for turning the front light off without touching the slider. Everything is configurable, and a control can point at a dispatcher action, a plugin or a KOReader menu rather than only toggling a hardware feature. That is what makes the panel a general purpose control surface rather than a settings sheet. The README is clear that the performance goal is battery efficiency, which on e-ink hardware is a real constraint rather than a slogan, since a backlight that stays on and a panel that refreshes often both cost charge. ## Library layouts, sorting and the metadata editor The Library is the second area ZenOS rebuilds, and here the focus is on density and on making the folder context carry weight. You can choose classic, mosaic or detailed list layouts from the current folder's context menu, then customise cover ratios, badges, progress indicators, rounded corners, folder covers and automatic series grouping. The path for these settings is Zen Settings > Library > Appearance > Layout, which controls mosaic grids with previews, list items per page, and the fields shown in detailed lists. Display mode, sorting and status filters can be saved per folder, which is the detail that makes the Library usable on a device with hundreds of folders. A global sort is fine until you have a comics folder, a reference folder and a fiction folder, and the one you want in each is different. The context menu is described as streamlined, handling read status, collections, file operations and full-screen book details. The native metadata editor changes book details, filenames and covers, or fills them from Hardcover, Google Books and Open Library. That last part is the interesting one: a metadata editor that can pull from three external catalogues means a library imported without good covers can be fixed in bulk rather than one book at a time. A separate guide covers the Library in more detail at docs/library.md, and the README shows screenshots of the cover view, the list view and the context menu. ## The Zen page browser and the reading modes Inside a book, ZenOS replaces KOReader's page browser with the Zen page browser, which puts page scrubbing, search, table of contents, bookmarks, font controls and book details into one view. It respects stable page labels and non-linear book content, which matters for the manga and comic files that the tags and the Manga navbar destination point at. Reader themes can switch with light and dark mode, and independent top and bottom status bars support presets, custom fonts and configurable content. Independent is the operative word, since a reader who wants the clock at the top and progress at the bottom should not have to choose. The dictionary and highlight menus are restyled, and they surface Wikipedia, X-Ray, KOAssistant and AI Assistant when those are installed. Since the last of those is optional, the menu has to degrade cleanly, and the wording that these appear when installed is the same care. Two smaller behaviours are worth noting. An opening banner replaces KOReader's blocking opening message, which on a slow e-ink refresh is a real annoyance. Margin guards reduce accidental selections while holding the screen edge, which is the e-ink equivalent of a palm rejection, since the display reports touches at the edge differently. The three focus modes sit on top of this. Zen Mode hides most of KOReader's default menu tabs and can be toggled without restarting. Lockdown Mode adds configurable restrictions for a controlled reading setup. Incognito Mode temporarily prevents reading history and statistics tracking and can turn itself off after a chosen timeout, which is the feature that makes the mode usable for a shared device rather than merely a gesture. ## Where ZenOS is the wrong choice The first limitation is that it is a layer, not a replacement. If the reason you dislike KOReader is its reading engine, its document handling or its plugin system, ZenOS does not address that. It addresses the interface, and a person who has already customised KOReader heavily may find the layer fights their existing setup rather than replacing it. The second is the device dependency. The tags name Kindle, Kobo, PocketBook, Boox and other e-ink devices, and some integrations are explicitly platform specific. Tapping Bluetooth toggles it and holding it manages connections on Kindle, Kobo and PocketBook, and installing ZenPM is described as limited to supported non-Android ARM devices. The lighting sliders and the device toggles assume a device with a front light, so a device without one has a partly inert Controls panel. The third is the scale of the configuration. The Home widgets, the Controls, the Library layouts, the Navbar tabs, the Launcher buttons and the reading modes are all configurable, and the number of decisions in front of a new user is large. Someone who wants KOReader to simply work, with fewer menus and no customisation, is a good fit for Zen Mode, which can be reached inside ZenOS but which is exactly the kind of thing people install a minimal layer to avoid. The fourth is the dependency on a moving upstream. ZenOS layers onto KOReader, and KOReader moves. A release of ZenOS that fits one KOReader version may not fit the next, and the README's own emphasis on performance and stability is a statement of intent rather than a guarantee about future KOReader releases. The fifth is that some features are integrations rather than features. The OPDS browser theming, the Rakuyomi and kindle.koplugin integrations, and the ZenFM content all depend on other software being present. ## ZenOS compared with KOReader's own front end and with stock Kindle firmware The fair comparison is with KOReader as it ships, and the difference in approach is that ZenOS takes KOReader's existing capabilities and reorganises them for one reading posture, while KOReader exposes everything at once. KOReader's own interface is powerful and dense. Its menus carry a great deal, and the configuration options are many. ZenOS's stated philosophy is the opposite: remove clutter, keep the interface fast, and treat performance, stability and ease of use as the three things that were non-negotiable during development. The Zen Mode, which hides most of the default menu tabs, is effectively the KOReader interface with the clutter removed, which tells you how the two relate. The second comparison is with the stock Kindle and Kobo interfaces. The stock firmware on a Kindle is fast and integrated with the store, but it is closed, and its reading settings are limited to what Amazon exposes. KOReader already opens up the device considerably, adding OPDS catalogues, dictionaries, statistics and a plugin system. ZenOS sits on top of that open layer and does not change the underlying capability, so the argument for it is about the shape of the interface rather than about new reading tools. The third comparison is with the Kindle jailbreak community's own interface modifications, which tend to be narrowly targeted, such as a font change or a new screensaver. ZenOS is a full re-skin with a coherent design, and the trade is that a coherent design also imposes opinions you may disagree with. For a reader who wants the KOReader capability set and a calmer screen, the arrangement makes sense. For someone who wants the Amazon store integration and the stock polish, none of this is the direction to go. ## Licence, release cadence and how it is built The licence is GPL-3.0, and the repository has a LICENSE.md file at the root. A copyleft licence is the right choice for a plugin layer that runs on other people's devices, and it also means the source of the layer itself stays open to the community it depends on. The project is not archived and the last push was on 2026-10-15, the same day as the v4.2.0 release. The recent releases show a monthly cadence with a sequence of alphas leading into it, with v4.2.0-alpha10 and v4.2.0-alpha11 released hours before v4.2.0 itself, and the same pattern visible in the earlier v4.1.x and v4.2.0 releases. Shipping alphas that turn into a final release the same day is a fast workflow, and it is worth noticing because a plugin layer has to be releasable on a schedule its users can plan around. The build is a shell script, build.sh, and the .env.example file at the root shows the one thing it needs, a path to a KOReader checkout used by the development build. ```bash KOREADER_DIR="$path/to/koreader" ``` That variable is consumed by ./build.sh --dev, so a developer working on ZenOS needs a local KOReader tree. An end user installing a release does not, which is the difference between the build script and the installation guide. Two other things in the repository are worth noting for anyone contributing. There is a .luacheckrc and a luacheck.sh, so Lua linting is part of the workflow, and a spec/ directory for tests. The repository also has a CODE_OF_CONDUCT.md, a CONTRIBUTING.md and a SECURITY.md. ## Conclusion ZenOS suits a reader on a Kindle, Kobo, PocketBook or other KOReader device who finds the stock interface cluttered and wants a home screen, a fast controls panel and a tidier library without giving up the reader underneath. It is the wrong choice for someone who wants a different reading engine, since KOReader remains the engine and this only replaces the interface, and the wrong choice if you intend to modify KOReader itself rather than configure a layer on top of it. Before installing, read the installation guide in docs/, and check that the release you take matches the KOReader version on your device, since the project is versioned alongside a moving upstream. ## FAQ ### What is ZenOS and how does it relate to KOReader? ZenOS is a customizable interface layer for KOReader. It adds a Home page, a redesigned Library, a Controls panel, a Launcher, reader tools and unified settings while keeping KOReader underneath as the reading engine. ### Which e-reader devices does ZenOS support? The repository topics name Kindle, Kobo, PocketBook, Boox, other e-ink devices, desktop and Android. Some integrations are device specific, such as holding the Bluetooth control to manage connections on Kindle, Kobo and PocketBook. ### What does the swipe-down Controls panel do in ZenOS? Swiping down from anywhere opens up to nine configurable controls plus brightness and warmth sliders. Buttons can toggle device features, run dispatcher actions, open plugins or KOReader menus, and expose integrations such as Bluetooth, Tailscale and ZenFM. ### What are the Zen Mode, Lockdown Mode and Incognito Mode in ZenOS? Zen Mode hides most of KOReader's default menu tabs and can be toggled without restarting. Lockdown Mode adds configurable restrictions for a controlled reading setup. Incognito Mode temporarily prevents reading history and statistics tracking and can switch itself off after a chosen timeout. ### Can ZenOS pull book metadata from online catalogues? Yes. The native metadata editor in the Library can change book details, filenames and covers, and can fill them from Hardcover, Google Books and Open Library. ### What licence does ZenOS use? GPL-3.0, with the terms in the LICENSE.md file at the root of the repository. ## Sources - [License: GPL-3.0](https://github.com/xZenLabs/zen-os/blob/main/LICENSE) - [Project website](https://zen-labs.org/zen-os) - [README](https://github.com/xZenLabs/zen-os/blob/main/README.md) - [Releases](https://github.com/xZenLabs/zen-os/releases) - [xZenLabs/zen-os on GitHub](https://github.com/xZenLabs/zen-os) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/xzenlabs-zen-os