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 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.
• 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

Arch Linux

Install from the AUR using your preferred AUR helper:

yay -S bookokrat-bin

or

paru -S bookokrat-bin

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.

sudo apt update && sudo apt install build-essential

sudo dnf install gcc make

xcode-select --install

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.

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.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
• + / - - 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
• 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 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:

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.