fancy-cat renders PDF pages in a Kitty terminal

A PDF viewer that draws into the terminal

fancy-cat is a PDF viewer for terminal emulators using the Kitty image protocol, written in Zig, and the whole approach rests on one capability. The Kitty image protocol lets a terminal application transmit graphics as escape sequences, and a PDF renderer that can emit those sequences can draw a page inside a terminal window with no separate window, no X11 dependency and no remote display needed. The repository is small and the layout shows the shape of it, with src/ holding the code, deps/ and a.gitmodules file for the dependencies, build.zig and build.zig.zon as the build definition, and docs/ holding the command and configuration references. The command line takes a path and an optional page number, so the same binary serves both the first page and a specific page, which is what you want when a document is referenced by page somewhere in a terminal session.

A modal interface borrowed from Neovim

The interaction model is the second thing to understand, and the README describes it as a modal interface similar to Neovim with two modes, view mode and command mode. You enter command mode by typing a colon by default, and the colon is configurable in the config file. The list of commands is documented separately in docs/commands.md, which is where you would look for the navigation and display verbs. The features list names the areas it covers, with filewatch for hot reload, runtime config, custom keymappings, the modal interface itself, commands, a colorize mode for dark mode, a status bar, and page navigation covering zoom, previous and next. The status bar and the modal split are what make a terminal PDF viewer usable rather than a novelty, because they give the same kind of feedback loop a Neovim user already has, and the hot reload means editing the config file takes effect without restarting the viewer.

Building it needs Zig 0.15.2 and the Kitty protocol

The requirements are short and specific. You need Zig version 0.15.2, and you need a terminal emulator with the Kitty image protocol, with Kitty, Ghostty and WezTerm given as examples. The build itself is three steps. First you fetch the submodules, because the dependencies live there.

git submodule update --init --recursive

Then you build the project in the small release mode.

zig build --release=small

And then you install the resulting binary by moving it onto your PATH.

# Add to your PATH
# Linux
mv zig-out/bin/fancy-cat ~/.local/bin/

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

The small release mode is worth noting because it is the mode the documentation uses throughout, and for a tool whose entire job is to emit image sequences into a terminal, size matters more than raw speed. To run without installing, there is a build run step that takes the same arguments as the installed binary.

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

The packaging status is tracked through a Repology badge, which is the usual way to say that the binary is packaged by a set of distributions rather than only by its author.

A processor specific build failure has a documented workaround

The build instructions include a known issue worth reading before you start, because the error message is alarming. There is a known issue with some processors where the build fails on the last steps with the error LLVM ERROR: Do not know how to expand the result of this operator!, and the documented workaround is to build with an explicit CPU target instead of letting the compiler pick.

zig build -Dcpu="skylake" --release=small

This is the kind of detail that a project publishes only after someone has hit it, and it is a good illustration of the Zig toolchain's trade-off. The same LLVM that compiles the code is the one doing the instruction selection, and a sufficiently new or unusual processor can trip it, so the escape hatch is to name a conservative target rather than to wait for a new compiler. For a reader deciding whether to adopt the project, the relevant point is that the failure mode is documented and has a one flag workaround, rather than being a mysterious crash.

The configuration file is created for you on first run

fancy-cat is configured through a JSON configuration file that it looks for in one of several locations, with the primary being the config.json path under XDG_CONFIG_HOME, the fallback being the same relative path under the home directory, and a legacy location under the home directory itself. An empty configuration file is created automatically in the primary or the fallback location on the first run, which removes the usual first-run friction of hunting for a config file that does not exist yet. The documentation also points at an example config.json and at docs/config.md, so the reference for every option is separate from the README. Two things you will want to change early are the key that enters command mode, which defaults to a colon, and the jump target, which defaults to the XDG path, and both are the kind of setting that a user of Neovim will want to align with their own muscle memory.

Where fancy-cat is the wrong tool

Three limits. The first is hard and non-negotiable, since the tool depends on the Kitty image protocol, and a terminal without it has nothing to render into. That excludes a meaningful share of terminals, including the older ones and the minimal emulators people use over SSH, and the README does not describe a text fallback, which is the right call, because a text-mode PDF viewer would be a different and much less useful project. The second is that the AGPL-3.0-or-later licence is a real consideration for anything you distribute, since it reaches networked use rather than stopping at handing over files, and that is a question for your own review rather than for this article. The third is scope. This is a viewer, not a reader, so it gives you a rendered page, page navigation and zoom, and it does not give you text selection, search inside the document, annotations or a document outline, because none of those are in the feature list. On the maintenance side the picture is modest rather than busy, with the last push to the repository on 2026-08-03 and no GitHub releases, so the build from source is the distribution path that the documentation actually supports.

Editorial conclusion

Adopt fancy-cat if you read PDFs from a terminal and your emulator supports the Kitty image protocol, since the whole tool is a single binary with a modal interface and a JSON config. Skip it if your terminal does not implement that protocol, because there is no fallback rendering path, and skip it if you want to read documents in a dedicated viewer with text selection. Before you build, confirm your emulator is on the supported list and that you have Zig 0.15.2, and read docs/config.md for the config file, since the key to enter command mode and the location of the config file are both configurable.

Frequently asked questions

Official sources

1. freref/fancy-cat on GitHub
2. Issues
3. License: AGPL-3.0
4. README