Bookokrat

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

demo_combined.mp4

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.

Prerequisites (click to expand)

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

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.

SyncTeX (LaTeX ↔ PDF)

Bookokrat supports bidirectional SyncTeX navigation between LaTeX sources and PDF output. Compile your LaTeX document with pdflatex --synctex=1 (or equivalent) to generate a .synctex.gz sidecar file. When a PDF is opened and its sidecar is found, SyncTeX activates automatically.

Inverse search (PDF → source): Ctrl+click, right-click, or gd in normal mode jumps to the corresponding LaTeX source line. gd also works on selected text (the mouse selection anchor is used). Configure which editor to open 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}"

Placeholders: {file}, {line}, {column}.

Forward search (source → PDF): From your editor, send a forward search command to the running instance via Unix socket. VimTeX setup:

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

Then press \lv in Neovim to jump from source to PDF. Any editor that can shell out works — the generic form is:

bookokrat --synctex-forward LINE:COLUMN:FILE path/to/document.pdf

The synctex_editor setting can also be configured in the Settings popup (Space+s), under the Integrations tab.

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.