cheatreader: a floating reader that stays out of the way

A window that is supposed to disappear

cheatreader is a floating desktop reader for low-distraction reading, and the README states the premise in one line: it keeps books visible in the corner of your screen without turning your desktop into a full reading app. The stated reason it exists is that traditional reading apps want your full attention, and this one does the opposite, staying light, quiet and easy to tuck into the edge of your workspace while you keep doing other things.

The feature that follows from that premise is the transparent text-only mode, which lets the app disappear into your desktop. Around it are the details that make such a mode usable rather than annoying. There are compact single-line and multi-line reading modes, and mode switching is configurable through a double click, a middle click, or a keyboard shortcut. Line spacing, reading width and the keyboard controls are adjustable for longer sessions.

The navigation is direct rather than incremental. You can jump by line, by page, by percentage, or by searching the text, and the previous and next match navigation moves through the hits. There is also built-in custom font loading with a dedicated user-selected font option, which matters for a transparent overlay, because the default system font is rarely the one you want for reading.

The application is written in Dart with Flutter, and the platform support table is honest about where the work has been done. macOS is the best supported platform, with the transparent overlay mode fully tuned there. Windows is supported, with the same reading flow in a frameless desktop window, and the note says testing on the target machine is recommended. Linux is supported with the same flow, and the Ubuntu startup now prefers multi-line recovery-safe behaviour.

The topic list also names epub, markdown and macos, and the repository carries a Chinese README alongside the English one, so the project is not a single language project even if the documentation is primarily English.

Text extraction is the model, not a document renderer

The format table is the most important part of the documentation for anyone deciding whether this reader fits their library, and the design is uniform: everything except plain text is reduced to text and pushed through the same reading flow.

Plain text is the only format marked as full support, and the note is that the import is encoding-aware. The rest are all text extraction. For epub, the chapter text is extracted into the existing reader flow. For html, htm and xhtml, the page chrome is ignored and the readable body text is kept. For md and markdown, the markdown syntax is stripped into plain readable text. For fb2, the FictionBook section text is pulled into the reader. For docx, the readable document body text is extracted into the existing text-first flow.

The PDF entry is the one to read carefully. It is described as best-effort text-layer extraction, and the note says that image-only or layout-heavy PDFs may fail or read imperfectly. That is a candid statement of the limit, and it is the practical dividing line: a scanned book in PDF will not read, and a document whose meaning depends on its two column layout will read badly.

The other half of the design is what the reader refuses to do. The important notice at the top of the README states that cheatreader is only a local multi-format file reader, and that it does not support importing books or content from any URL, web link, online source or remote feed. There is no catalogue, no download, no sync. The README also states that the project does not support, encourage or endorse any act that infringes the lawful rights of writers, publishers or other copyright holders, that it is shared for learning and technical exchange only, and that the author does not intend to use it commercially.

That makes the scope unambiguous. It is a local reading surface, and the formats it handles are the ones whose content survives being flattened into text.

The boss key hides the reader without losing your place

The feature that most distinguishes this reader is a system wide boss key that hides and restores the window on Windows, macOS and Linux X11 without losing the reading state.

That word system wide is the whole point. A window that hides when it loses focus is not a boss key, it is a normal application behaviour. What is described here is a global shortcut that works while another application has focus, which is the only version of the feature that is worth having, and the fact that the reading state survives the hide is what makes it usable in the first place.

The state preservation is not a small detail either. The library section of the highlights mentions local managed library copies so imported books still restore after restart, which is the same idea applied to persistence: the window can be dismissed and the book comes back.

The rest of the reading interaction is deliberately short on modes. Single-line and multi-line reading, a mode switch by double click, middle click or shortcut, adjustable line spacing and width, direct jumps, and text search with match navigation. There is no library browser to speak of in the highlights beyond the bookshelf, and no annotation or highlighting feature listed, which is a notable omission for a reading application and tells you the project is aimed at reading text you brought with you rather than at managing a collection.

The scope of what the window does is the scope of the application. Everything here serves the same goal, which is a book on screen that you can dismiss instantly and get back to instantly.

Running it from source is two commands and a desktop target

The development path is a standard Flutter desktop flow, and the README gives the macOS case first.

flutter pub get
flutter run -d macos

The other platforms need their desktop target enabled before they can be run, which is a Flutter requirement rather than something specific to this project.

flutter config --enable-windows-desktop
flutter run -d windows

flutter config --enable-linux-desktop
flutter run -d linux

Verification is the two commands a Flutter project would use, tests and static analysis, and the README adds a manual step for the part that cannot be automated.

flutter test
flutter analyze

For desktop floating-window changes, the README asks you to also run the manual checklist in manual-test-files/regression-checklist.md, and platform builds can be produced with flutter build windows and flutter build linux.

That manual checklist is worth noticing as a project signal. A floating transparent window is exactly the kind of behaviour that automated tests cannot judge, since the properties that matter, where the window sits, whether it overlaps, whether it hides on the right key, are visual and positional. A project that keeps a written regression checklist for that is telling you it takes the window behaviour seriously.

The repository layout is consistent with a Flutter project that targets several platforms, with android/, ios/, linux/, macos/, web/ and windows/ directories, lib/ for the application code, test/ for the tests, tool/ for tooling, an openspec/ directory, a snap/ directory, a l10n.yaml for localisation, an analysis_options.yaml for the analyser configuration, and a pubspec.lock for reproducible dependency resolution.

Packaging is where the real friction sits

The installation sections are longer than the usage sections, which is unusual and informative.

On macOS, the released app is unsigned, so the first launch can be blocked by Gatekeeper. The documented fix is to remove the quarantine flag, and the path is the one where the app actually is.

xattr -dr com.apple.quarantine /Applications/cheatreader.app

On Linux, the released Debian package has a dependency story that the README spells out. The system tray integration needs libayatana-appindicator3-1, and the global shortcuts on X11 need libkeybinder-3.0-0. The release packages should be installed with APT so that dependencies are resolved automatically.

sudo apt install ./cheatreader-v0.1.29-linux-amd64.deb

On Ubuntu 20.04 that runtime lives in the universe repository, and the README gives the repair sequence if APT reports it as unavailable, which is to add the universe repository, update, fix the broken package state, install the missing library and then install the package again.

sudo add-apt-repository universe
sudo apt update
sudo apt --fix-broken install
sudo apt install libayatana-appindicator3-1

The README also tells you to confirm the selection with apt-cache policy, and warns against dpkg -i for this package because it does not resolve missing dependencies. That is a small, specific piece of advice that saves an evening.

The build dependencies for Linux are listed as clang, cmake, ninja-build and pkg-config, plus the GTK development packages that Flutter desktop needs, with a typical Ubuntu and Debian setup given as an apt-get install line. The Windows prerequisites are Flutter with the Windows desktop target enabled and Visual Studio with the Desktop development with C++ workload.

Wayland breaks the boss key, and the tray icon is the fallback

One platform limitation is stated clearly enough to plan around. Global boss-key registration works on Linux X11. Wayland compositors generally block applications from registering arbitrary global shortcuts, so Wayland users can still use the shortcut while cheatreader is focused, and they can restore a hidden reader from its tray icon.

That is a genuine loss of the feature's value on a modern Linux desktop, since the whole point of the boss key is that it works while another application has focus. The tray icon becomes the recovery path, which is a weaker and more visible mechanism.

The dependency chain explains why this is not fixable inside the application. The global shortcut on X11 is provided by libkeybinder, and the tray icon by the appindicator library, both of which are X11 era technologies. Moving to a portal based shortcut registration API would be a different implementation, and the README does not claim one exists.

There is a related piece of state management in the same area. The README describes a reset for when a saved floating-window layout becomes hard to find, which resets just the display related settings without wiping the bookshelf.

cheatreader --reset-display

A command that clears one class of settings and leaves the library alone is a thoughtful thing to ship, because a floating window that has been dragged onto a disconnected monitor is a common enough accident that a targeted escape hatch is worth having.

What the project is, and what it is not

The scope statement at the top of the README is the most important paragraph in the project, and it is worth reading as a set of commitments rather than as a disclaimer.

cheatreader is only a local multi-format file reader. It does not support importing books or content from any URL, web link, online source or remote feed. It does not support, encourage or endorse any act that infringes the lawful rights of writers, publishers or other copyright holders. It is shared for learning and technical exchange only, and the author does not intend to use it commercially or to profit from it.

Those sentences define a project that is deliberately small and local, and they explain why there is no import-from-URL feature, no store, no account and no sync. The app's job is to read the file you already have.

The licence is recorded as a custom one that GitHub cannot classify, with the terms in the LICENSE file at the top of the repository, so that file is the only statement of what you may do with the code. The project is not archived, the last push was on 2026-09-09, and the release list shows v0.1.33 on 2026-09-09 with v0.1.32 and v0.1.31 published the same day, which is the pattern of a project iterating on packaging and window behaviour rather than on features.

The Todo section is written unusually well, with completed items ticked and the open ones phrased as user feedback. The open items are a better bookshelf experience with better organisation and recovery for imported books, easier desktop installation and distribution so that first-time setup feels less like work, and continued improvement of import stability. That last one is the one to watch, because the import path is where a text extraction reader is most likely to fail on an unusual file, and the PDF entry in the format table says as much about image-only and layout-heavy documents.

Editorial conclusion

cheatreader fits a reader who wants a book open in the corner of the screen while working and who can accept a local file library rather than a synced catalogue, and it does not fit anyone who needs the boss key on Wayland or expects PDF to be a first class format. Before adopting it, read the format table for the types you actually read, and on Linux confirm that the appindicator and keybinder runtime packages are present before you rely on the tray icon and the global shortcut.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. yaoyao2mm/cheatreader on GitHub