Bookokrat - Terminal EPUB Reader with Full HTML Rendering
Author: Rafael Bagmanov
Description: Full-featured terminal EPUB reader with complete HTML/EPUB rendering, inline images, MathML support, vim keybindings, mouse support, and inline annotations. Read technical books without leaving your terminal.
Keywords: epub reader, terminal epub reader, tui epub, command line ebook reader, rust epub reader, vim keybindings, mathml rendering, technical book reader, terminal application

for terminal workflows

# TERMINAL
EPUB
READER

// FULL-FEATURED EPUB RENDERING • IMAGES • TABLES & CODE BLOCKS • VIM KEYBINDINGS • MOUSE SUPPORT
INLINE ANNOTATIONS • LOCAL & GLOBAL SEARCH
READ TECHNICAL BOOKS WITHOUT LEAVING YOUR TERMINAL

Install
features

## Built for technical reading

Everything you need to read and research technical books in your terminal

### Complete EPUB/HTML rendering

Proper table layouts, syntax-highlighted code blocks, bold/italic text, blockquotes, lists, and MathML equations. Uses html5ever parser—reads like the author intended.

### Annotate & research

Press 'a' on any selection to attach timestamped notes. Full-text search across books. Copy chapters or selections. Your reading workspace in the terminal.

### Vim keybindings + mouse support

Full vim motions (j/k, gg/G, /, Ctrl+o/i) for keyboard users. Comprehensive mouse support for everyone else. Use whichever you prefer—or both.

### Never lose your place

Automatic bookmarks per book. Reading history popup (Space+h). Chapter statistics and progress tracking. Jump list remembers your navigation path.

### Works in any terminal

Auto-detects true color (24-bit) or falls back to 256-color palette. Images render via Kitty, Sixel, iTerm2, or Unicode halfblocks—whatever your terminal supports.

### Cross-platform

Native binaries for macOS (Intel & Apple Silicon) and Linux. Install via Homebrew, download pre-built binaries, or build from source on any platform including Windows.

installation

## Get Started

### Homebrew (macOS)

`brew install bookokrat`

### Pre-built Binary (Linux)

Download from GitHub Releases. Static musl binary works on all distributions.

`curl -LO https://github.com/bugzmanov/bookokrat/releases/latest/download/bookokrat-v0.2.1-x86_64-unknown-linux-musl.tar.gz`

### Cargo (all platforms)

Build from source with Cargo (Rust's package manager). Get Rust at rustup.rs

// Prerequisites (Cargo only)

Building from source requires a C compiler/linker:

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 "Desktop development with C++" workload
`cargo install bookokrat`
// Quick Start
1. Navigate to a directory with EPUB files
2. Run `bookokrat`
3. Use `j/k` to navigate, `Enter` to open a book, `?` for help
// Troubleshooting
Error: "linker 'cc' not found"
Install a C compiler: `xcode-select --install` (macOS), `sudo apt install build-essential` (Debian/Ubuntu), or `sudo dnf install gcc make` (Fedora).
demo

## See it in action

Watch bookokrat handle real technical content

comparison

## How does it compare?

Terminal EPUB readers compared side-by-side

Feature ↓ / Reader → | Bookokrat | bk | epr | epy | baca | Lue
--- | --- | --- | --- | --- | --- | ---
EPUB support | ✓ | ✓ | ✓ | ✓ | ✓ | ✓
Inline images in terminal | ✓ | ✗ | ✗* | ✗* | ✓ (ANSI) | ✗
MathML rendering | ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Table of contents | ✓ | ✓ | ✓ (basic) | ✓ | ✓ | ✗
Search | ✓ (chapter & book) | ✓ (incremental) | ✓ (regex) | ✓ | ✓ (regex) | ✗
Bookmarks / resume | ✓ | ✓ | ✓ | ✓ | ✓ | ✓
Highlights / notes | ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Text-to-speech (TTS) | ✗ | ✗ | ✗ | ✓ | ✗ | ✓
Multi-format (beyond EPUB) | ✗ | ✗ | ✗ | ✓ | ✓ | ✓
Library / history view | ✓ | ✗ | ✓ | ✓ | ✓ | ✗

* epr/epy can open images via external viewer; not inline in the terminal.
terminal support

## Image Rendering

Bookokrat auto-detects the best image protocol for your terminal. Here's what to expect.

★★★
EXCELLENT
Kitty
Ghostty
iTerm2
★★☆
GOOD
WezTerm
(some flickering)
★☆☆
BASIC
Alacritty
Linux default terminal
(halfblocks)
✗
NO IMAGES
macOS
Terminal.app

Terminal | Protocol | Notes
--- | --- | ---
Kitty | Kitty | Native support
Ghostty | Kitty | Native support
iTerm2 | Sixel | Native protocol causes flickering; Kitty buggy in recent betas
WezTerm | iTerm2 | Kitty buggy (#986); Sixel broken on Windows (#5758)
Alacritty | Halfblocks | No graphics protocol support (#910)
Others | Auto-detect | Kitty → Sixel → iTerm2 → Halfblocks

?
Images look wrong? Check `bookokrat.log` for the detected protocol.
Experiencing issues not covered above? Just open an issue — happy to help!