Bookokrat: an EPUB, PDF and DJVU reader for the terminal

One reader for EPUB, PDF and DJVU, split into library and reading panes

Bookokrat is a terminal reader for the three book formats that keep showing up in different shapes. PDF and DJVU share a dedicated rendering pipeline. The application is a TUI built on ratatui with crossterm for events, and the layout is split: the library and table of contents sit on the left, the reader on the right.

The stated focus is speed, smooth navigation and Vim-style workflows, and the two are connected. Navigation in a terminal reader is mostly motion between pages, sections and matches, and a Vim-style keybinding model with a normal mode means that motion is expressed in the vocabulary a Vim user already has rather than in a set of arbitrary function keys. The in-app help is opened with `?`.

Beyond navigation, the feature set covers search, bookmarks, a jump list history and reading stats. Images are rendered, links are handled, and an external viewer can be handed off to when the terminal is not the right place for something. There is a theme picker with live preview, adjustable margins, and a zen mode that drops the interface down to the text.

It is worth being clear about the audience. This is a tool for someone who reads on a terminal as a matter of habit, not a browser-based reader in a text-mode fallback. The terminal is the primary interface, not a compromise.

PDF and DJVU rendering needs a terminal with a graphics protocol

The documentation is blunt about this. PDF and DJVU viewing require a graphics-capable terminal. Kitty and Ghostty are named as the best experience, iTerm2, WezTerm, Warp and Konsole are listed as good with some limitations, and terminals without graphics protocol support get EPUB support without images. PDFs and DJVUs are not supported at all there.

The mechanism behind the good case is named: Kitty SHM image transfer, which is how the fast PDF and DJVU pipeline gets rendered pages into the terminal without redrawing a grid of characters per page. A terminal that speaks the Kitty graphics protocol can receive the page as an image, which is what makes the pipeline fast rather than merely possible.

This is the single biggest constraint in the project, and it interacts with the packaging options. There are prebuilt Linux binaries on the GitHub releases page, a Homebrew formula for macOS, an AUR package, and Nix flakes. The Windows notes go further: PDF and DJVU might not work in Windows PowerShell, and for full Kitty graphics protocol support the recommendation is to use WSL with Ghostty or Kitty. There is also a fallback when the build fails, `cargo install bookokrat --no-default-features`, which drops PDF and DJVU support, so MuPDF is the dependency that has to build.

A reader on a plain xterm or a basic Linux console gets EPUB without images. That is a working configuration, but it is a different application from the one the project is describing.

SyncTeX turns the PDF reader into a LaTeX workbench

The feature that separates Bookokrat from a general PDF viewer is bidirectional SyncTeX navigation between LaTeX sources and the compiled PDF.

The mechanism is the standard SyncTeX sidecar. You compile with `pdflatex --synctex=1` or an equivalent, which produces a `.synctex.gz` file next to the PDF, and when a PDF with a sidecar is opened, SyncTeX activates automatically. No flag to pass, no separate mode to enter.

Inverse search, from the PDF back to the source, is triggered by Ctrl+click, right-click, or `gd` in normal mode, and `gd` also works on a text selection using the mouse selection anchor. Which editor gets opened is configured in `~/.bookokrat_settings.yaml`:

# Neovim via remote socket (recommended for VimTeX \lv workflow)
synctex_editor: "nvim --server /tmp/nvim.sock --remote-send '<C-\\><C-n>:e {file}<CR>:{line}<CR>'"

# Open in a new terminal nvim
synctex_editor: "nvim +{line} {file}"

The placeholders are `{file}`, `{line}` and `{column}`. The remote socket form is the interesting one, because it opens the source in an already running Neovim instance rather than starting a new one, which is what makes the VimTeX workflow coherent. The same setting is also editable in the Settings popup under Space+s, in an Integrations tab.

Forward search, from source to PDF, goes the other way: the editor sends a command to the running instance over a Unix socket. The VimTeX setup is two lines of Vim configuration:

let g:vimtex_view_method = 'general'
let g:vimtex_view_general_cmd = 'bookokrat --synctex-forward @line:@col:@tex @pdf'

Pressing `\lv` in Neovim then jumps from the source to the corresponding place in the PDF. Any editor that can shell out works, with the generic form being `bookokrat --synctex-forward LINE:COLUMN:FILE path/to/document.pdf`.

Comments, bookmarks and caches live in XDG paths, not in your book folder

Bookokrat keeps its state in XDG-compliant locations, and the documentation is explicit that this is to keep project directories clean. A book file you open does not accumulate a sibling folder of notes.

The layout is documented as a table. Bookmarks go to `<data_dir>/bookokrat/libraries/<library>/bookmarks.json`, comments to `<data_dir>/bookokrat/libraries/<library>/comments/`, the image cache to `<cache_dir>/bookokrat/libraries/<library>/temp_images/`, the log file to `<state_dir>/bookokrat/bookokrat.log`, and the settings file to `~/.bookokrat_settings.yaml`. Typical `<data_dir>` values are `~/Library/Application Support` on macOS and `~/.local/share` on Linux.

The per-library path is the detail worth noticing. Bookmarks, comments and the image cache are all keyed by library, so a user with separate collections keeps separate annotation sets, and the image cache never grows across unrelated books.

Comments and annotations are a first-class feature rather than a side note. They have persistent storage, they can be exported to Markdown, and the note bodies can be hidden and peeked on demand, which is the behaviour you want when you are reading rather than annotating. A jump list history and reading stats round out the state the application keeps.

Build and packaging cover the usual Linux, macOS and Nix paths

Installing is a matter of picking your platform. On macOS, `brew install bookokrat`. On Arch, the AUR package `bookokrat-bin` through `yay -S bookokrat-bin` or `paru -S bookokrat-bin`. On Nix, `nix run github:bugzmanov/bookokrat` to try it, or `nix profile install github:bugzmanov/bookokrat` to install it. Prebuilt Linux binaries are on the GitHub releases page.

The cargo route needs Rust and a C compiler with a linker, and on Linux the PDF and DJVU support pulls in extra system packages, with `pkg-config libfontconfig1-dev clang libclang-dev` named for Ubuntu and Debian. macOS needs `xcode-select --install`, and Windows needs Visual Studio Build Tools with the Desktop development with C++ workload.

cargo install bookokrat

The manifest gives the floor for the toolchain: edition 2024, `rust-version = "1.90"`. The current version is 0.3.13, and the release history shows v0.3.11 on 2026-05-19, v0.3.12 on 2026-06-06 and v0.3.13 on 2026-10-10, with the last push on 2026-10-17. The project is not archived.

The pre-release gate in the Makefile is unusual enough to note. `pre-release-check` runs clippy with warnings denied in both feature configurations, the SVG snapshot tests with the pdf feature enabled, the VHS terminal tapes against both kitty and wezterm, and finally the nix build, failing on the first broken step. The VHS tapes are real-terminal screenshots, so the interface is checked visually rather than only by unit test.

AGPL-3.0 and a vendored dependency both need a decision

The licence is GNU Affero General Public License v3.0 or later, and it is recorded as `AGPL-3.0-or-later` in both the README and the Cargo manifest, with the `LICENSE` file at the root of the repository. For a personal reading tool, the licence terms rarely come up. For anything else, the network copyleft condition is the part to understand before you modify the code or offer the application as a service, and that is a question for whoever handles licensing review rather than something this article should answer.

The attribution section records that Bookokrat is based on bookrat by Dmitry Sobolev, which is under the MIT licence. That is a different licence from the one the project itself ships under, and both are named in the same document.

A second detail is worth flagging for anyone tracking dependencies. `tui-textarea` is vendored into `vendor/tui-textarea` because, as the notice states, upstream is currently unmaintained and behind current ratatui compatibility. The vendored base comes from a specific pull request in the upstream project. Vendoring is a reasonable response to an abandoned dependency, and it also means the code in that directory is no longer updated from upstream, so it is now a fork you own the maintenance of.

The manifest also shows the application is built with a `default-run = "bookokrat"`, a library target and a binary target, and the `exclude` list drops the VHS tapes, docs, build output and test artifacts from the published package, which keeps the crate size down for anyone installing from source.

Where Bookokrat is the wrong tool

The terminal requirement is the obvious limit, and it is worth being concrete rather than repeating the documentation. A reader whose terminal lacks a graphics protocol cannot open a PDF or a DJVU at all, and gets EPUB without images. If your books are mostly PDFs, that rules the application out on that machine regardless of how good the interface is.

The second limit is the reading experience itself. A TUI reader is a text-first environment. It handles images, links and handoff to an external viewer, but the layout is a character grid, so a book that depends on precise page layout, on figures that only make sense at full width, or on colour as information is going to read worse here than in a document viewer with a real page model. The zen mode and adjustable margins suggest the author has thought about this, but they adjust a text layout, they do not turn the terminal into a page.

There is a narrower case too. This is a local application with local state and a Unix-socket forward search that expects a running instance. It is built for one person at one terminal, and it does not document anything about sharing an annotated library across machines or a team. If collaborative annotation is the goal, the Markdown export is the hand-off point, not a shared database.

Editorial conclusion

Bookokrat suits a reader who lives in a terminal and wants one application for EPUB, PDF and DJVU, and it suits a LaTeX author who wants to jump between source and PDF without leaving the keyboard. It does not suit a reader on a terminal without a graphics protocol, since PDF and DJVU are unsupported there and only EPUB without images will open. Before adopting, check the terminal note in the documentation, because Kitty and Ghostty are listed as the best experience while terminals without graphics support lose two of the three formats, and read the AGPL-3.0 terms before you consider modifying or redistributing it.

Frequently asked questions

Official sources

1. bugzmanov/bookokrat on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases