Bookokrat

Terminal EPUB/PDF/DJVU reader focused on speed, smooth navigation, and Vim-style workflows.

https://github.com/user-attachments/assets/0ebe61c6-4629-4bde-8bd4-50feb9a424a3

Highlights

• EPUB, PDF, and DJVU support in one TUI app
• Split layout: library/TOC on the left, reader on the right
• Fast PDF/DJVU pipeline with Kitty SHM image transfer in supported terminals
• Search, bookmarks, jump list history, reading stats
• Inline comments/annotations with persistent storage and Markdown export
• Image rendering, link handling, and external viewer handoff
• Theme selection, adjustable margins, zen mode
• Vim-style keybindings and normal mode

Install

Homebrew (macOS)

brew install bookokrat

Arch Linux (AUR)

Install from the AUR:

yay -S bookokrat-bin
# or
paru -S bookokrat-bin

Nix / NixOS (flakes)

nix run github:bugzmanov/bookokrat
# or install into profile
nix profile install github:bugzmanov/bookokrat

Prebuilt Linux binaries

Download from GitHub Releases.

Cargo (all platforms)

Build from source. Requires Rust and a C compiler/linker.

<details> <summary>Prerequisites (click to expand)</summary>

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install build-essential

# For PDF / DJVU support:
sudo apt install pkg-config libfontconfig1-dev clang libclang-dev

Linux (Fedora/RHEL):

sudo dnf install gcc make

macOS:

xcode-select --install

Windows: Install Visual Studio Build Tools with the "Desktop development with C++" workload.

Windows notes:

• PDF/DJVU might not work in Windows PowerShell.
• For full Kitty graphics protocol support, consider using WSL with Ghostty or Kitty.
• If MuPDF fails to build, disable PDF/DJVU support: cargo install bookokrat --no-default-features

</details>

cargo install bookokrat

Build without PDF / DJVU support:

cargo install bookokrat --no-default-features

Quick Start

bookokrat

Optional direct open:

bookokrat path/to/book.epub
bookokrat path/to/book.pdf
bookokrat path/to/book.djvu
bookokrat path/to/book.epub --zen-mode

Press ? inside the app to open the built-in help.

Documentation

• Full usage and keyboard reference: readme.txt

Terminal Notes

PDF and DJVU viewing require a graphics-capable terminal.

• Best experience: Kitty, Ghostty
• Good: iTerm2, WezTerm, Warp, Konsole (with some limitations)
• Terminals without graphics protocol support - EPUB support without images. PDFs and DJVUs are not supported

For protocol details and troubleshooting, see the in-app help (?) and readme.txt.

Data Storage

Bookokrat stores state in XDG-compliant locations and keeps project directories clean.

| Data | Location | |------|----------| | Bookmarks | <data_dir>/bookokrat/libraries/<library>/bookmarks.json | | Comments | <data_dir>/bookokrat/libraries/<library>/comments/ | | Image cache | <cache_dir>/bookokrat/libraries/<library>/temp_images/ | | Log file | <state_dir>/bookokrat/bookokrat.log | | Settings | ~/.bookokrat_settings.yaml |

Typical <data_dir> paths:

• macOS: ~/Library/Application Support
• Linux: ~/.local/share

Vendored Dependency Notice

tui-textarea is vendored in vendor/tui-textarea because upstream is currently unmaintained and behind current ratatui compatibility. The vendored base comes from PR #118: https://github.com/rhysd/tui-textarea/pull/118/changes

Attribution

Bookokrat is based on bookrat by Dmitry Sobolev (MIT).

License

GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE.