Bookokrat

Bookokrat is a terminal-based EPUB and PDF reader with a split-view library and reader, full MathML and image rendering, automatic bookmarks, inline annotations, and customizable themes.

Demo

What You Can Do

• Browse every EPUB & PDF in the current directory or automatically detect and read from your Calibre library with proper metadata.
• Drill into the table of contents, and resume exactly where you left off.
• Search inside the current chapter or across the whole book, jump through a per-book history, and inspect reading statistics.
• Highlight text, attach comments, export annotations to Markdown, copy snippets or entire chapters, and toggle the raw HTML source for debugging.
• Read PDFs with a dedicated renderer (TOC navigation, page/scroll modes, bookmarks, and annotations) in graphics-capable terminals.
• Open images in-place, follow internal anchors, launch external links in your browser, and hand off the current document to your system viewer.
• Customize with multiple color themes, adjustable margins, and zen mode; settings persist across sessions.
• Enter a Vim-style normal mode in the reader for precise motions, visual selection, and yanking to clipboard.
• Load EPUB bundles (exploded .epub directories, including Apple Books exports) without repackaging.
• Read complex HTML tables and rich cell content with improved rendering and image support.

Installation

Homebrew (macOS)

brew install bookokrat

Arch Linux

Install from the AUR using your preferred AUR helper:

yay -S bookokrat-bin

or

paru -S bookokrat-bin

Nix/NixOS (via Flakes)

If you have Nix with Flakes enabled, you can run Bookokrat directly:

nix run github:bugzmanov/bookokrat

To install it into your Nix profile:

nix profile install github:bugzmanov/bookokrat

Pre-built Binaries (Linux)

Download from GitHub Releases:

# x86_64 (Intel/AMD)
curl -LO https://github.com/bugzmanov/bookokrat/releases/latest/download/bookokrat-v0.3.4-x86_64-unknown-linux-musl.tar.gz
tar -xzf bookokrat-v0.3.4-x86_64-unknown-linux-musl.tar.gz
sudo mv bookokrat /usr/local/bin/

# arm64 (AArch64)
curl -LO https://github.com/bugzmanov/bookokrat/releases/latest/download/bookokrat-v0.3.4-aarch64-unknown-linux-gnu.tar.gz
tar -xzf bookokrat-v0.3.4-aarch64-unknown-linux-gnu.tar.gz
sudo mv bookokrat /usr/local/bin/

Cargo (all platforms)

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

Linux (Ubuntu/Debian):

sudo apt update 
sudo apt install build-essential

# For PDF to work:
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.

cargo install bookokrat

Note: PDF support is enabled by default. If you want to build without PDF support:

cargo install bookokrat --no-default-features

If you need symbols for profiling or debugging, build with the debug release profile:

cargo build --profile release-debug

Vendored Dependency Notice

Important: tui-textarea is vendored in vendor/tui-textarea because the upstream repository (https://github.com/rhysd/tui-textarea) is currently unmaintained and out of step with the latest ratatui. Our vendored copy is based on PR #118: https://github.com/rhysd/tui-textarea/pull/118/changes

Getting Started

Navigate to a directory with EPUB files and run bookokrat. Use j/k to navigate, Enter to open a book, and ? for help.

You can also open a specific file or start in zen mode, but this is not the main flow:

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

Keyboard Reference

Bookokrat follows Vim-style keybindings throughout the interface for consistent, efficient navigation.

Global Commands

• q - Quit application
• Tab - Switch focus between library/TOC and content panels
• Esc - Clear selection/search or dismiss popups
• Ctrl+z - Toggle zen mode (hide sidebar/status bar)
• ? - Show help screen
• Space+t - Open theme selector
• Space+s / Ctrl+s - Open settings (PDF support + render mode)
• + / - - Increase/decrease content margins

Navigation (Vim-style)

• j/k - Move down/up (works in all lists and reader)
• h/l - Collapse/expand in TOC; previous/next chapter in reader
• Ctrl+d / Ctrl+u - Scroll half-page down/up
• gg - Jump to top
• G - Jump to bottom
• Ctrl+o / Ctrl+i - Jump backward/forward in history

Search

• / - Start search (filter in library/TOC; search in reader)
• n / N - Jump to next/previous match
• Space+f - Reopen last book-wide search
• Space+F - Start fresh book-wide search

Library & TOC Panel

• Enter - Open highlighted book or heading
• h / l - Collapse/expand entry
• H / L - Collapse/expand all

Reader Panel

• h / l - Previous/next chapter
• ss - Toggle raw HTML view
• Space+c - Copy entire chapter (EPUB) / extract current page text (PDF)
• Space+z - Copy debug transcript
• z (PDF) - Zoom to fit height
• Z (PDF) - Zoom to fit width
• i (PDF) - Toggle image inversion
• c or Ctrl+C - Copy selection
• p - Toggle profiler overlay
• n - Toggle normal mode (Vim motions, visual selection, yanking)
• v / V (normal mode) - Enter visual character/line selection; y to yank, Esc to exit
• Enter (normal mode) - Open link under cursor

Comments & Annotations

• a - Create or edit comment on selection
• d - Delete comment under cursor
• Space+e - Export all annotations to Markdown (in comments viewer)

Popups & External Actions

• Space+h - Toggle reading history popup
• Space+d - Show book statistics popup
• Space+a - Open comments/annotations viewer
• Space+o - Open current document in OS viewer
• Enter - Open image popup (when on image) or activate popup selection

Popup Navigation

All popups (search results, reading history, book stats) support:

• j/k - Move up/down
• Ctrl+d / Ctrl+u - Half-page scroll
• gg / G - Jump to top/bottom
• Enter - Activate selection
• Esc - Close popup

Image Rendering

Bookokrat automatically selects the best image protocol for your terminal:

Experience by terminal:

• Excellent: Kitty, Ghostty, iTerm2
• Good: WezTerm (some flickering)
• Basic: Alacritty, Linux default terminals (Halfblocks fallback)
• No images: macOS Terminal.app (no graphics protocol support)

PDF viewing requires a graphics-capable terminal. For the best PDF experience, Kitty or Ghostty are strongly recommended—they support SHM-based image transfer for smooth 60fps rendering. WezTerm and iTerm2 work but with reduced performance and some feature limitations. Use the settings popup (Space+s or Ctrl+s) to disable PDF mode if your terminal does not support graphics.

If images look wrong, check bookokrat.log for the detected protocol. Experiencing issues not covered above? Just open an issue — happy to help!

Mouse Support

• Scroll with the wheel over either pane; Bookokrat batches rapid wheel events for smooth scrolling.
• Single-click focuses a pane; double-click in the library opens the selection; double-click in the reader selects a word; triple-click selects the paragraph.
• Click-and-drag to highlight text; release on a hyperlink to open it; drag past the viewport edges to auto-scroll.
• Click images to open the zoom popup; click again or press any key to close; clicking history or stats entries activates them immediately.

Attribution

This project is based on bookrat by Dmitry Sobolev, licensed under the MIT License.

License

This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE for details.