Bookokrat

Bookokrat is a terminal-based EPUB 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 in the current directory, 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, copy snippets or entire chapters, and toggle the raw HTML source for debugging.
• Open images in-place, follow internal anchors, launch external links in your browser, and hand off the book 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

Pre-built Binaries (Linux)

Download from GitHub Releases:

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

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

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

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.

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
• + / - - 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
• Space+s - Toggle raw HTML view
• Space+c - Copy entire chapter
• Space+z - Copy debug transcript
• 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

Comments & Annotations

• a - Create or edit comment on selection
• d - Delete comment under cursor

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 book 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:

Terminal	Protocol	Reason
Kitty	Kitty	Native support
Ghostty	Kitty	Native support
iTerm2	Sixel	Native protocol causes flickering; Kitty buggy in recent betas
WezTerm	iTerm2	Kitty is buggy (#986); Sixel broken on Windows (#5758); some flickering expected
Alacritty	Halfblocks	No graphics protocol support (#910)
Others	Auto-detected	Kitty > Sixel > iTerm2 > Halfblocks

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)

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.