macOS

November 17, 2025 · View on GitHub

📑
fancy-cat

PDF viewer for terminals using the Kitty image protocol

demo

Usage

fancy-cat <path-to-pdf> <optional-page-number>

Commands

fancy-cat uses a modal interface similar to Neovim. There are two modes: view mode and command mode. To enter command mode you type : by default (this can be changed in the config file).

Documentation on the available commands can be found here.

Configuration

fancy-cat can be configured through a JSON configuration file located in one of several locations (primary $XDG_CONFIG_HOME/fancy-cat/config.json, fallback $HOME/.config/fancy-cat/config.json, legacy $HOME/.fancy-cat). An empty configuration file is automatically created in the primary or fallback location on the first run.

An example config.json and documentation can be found here.

Installation

fancy-cat is available in the following repositories:

Packaging status

Build Instructions

Requirements

  • Zig version 0.15.2
  • Terminal emulator with the Kitty image protocol (e.g. Kitty, Ghostty, WezTerm, etc.)

Build

  1. Fetch submodules:
git submodule update --init --recursive
  1. Build the project:
zig build --release=small

Note

There is a known issue with some processors; if the build fails on step 7/10 with the error LLVM ERROR: Do not know how to expand the result of this operator! then try the command below instead:

zig build -Dcpu="skylake" --release=small
  1. Install:
# Add to your PATH
# Linux
mv zig-out/bin/fancy-cat ~/.local/bin/

# macOS
mv zig-out/bin/fancy-cat /usr/local/bin/

Run

zig build run -- <path-to-pdf> <optional-page-number>

Features

  • ✅ Filewatch (hot-reload)
  • ✅ Runtime config
  • ✅ Custom keymappings
  • ✅ Modal interface
  • ✅ Commands
  • ✅ Colorize mode (dark-mode)
  • ✅ Status bar
  • ✅ Page navigation (zoom, prev, next, etc.)

License

AGPL-3.0-or-later

Contributing

Contributions are welcome.