Getting started

Already have a terminal and Rust? This is the whole install:

cargo binstall konoma        # prebuilt binary (install cargo-binstall via Homebrew first)
# or
cargo install konoma         # build from source with the Rust toolchain

Prebuilt tarballs are also on the GitHub releases page if you don’t use cargo at all. Starting from a fresh machine? See Set up from scratch below.

Requirements

The gate for konoma’s full experience is the terminal, not the OS:

konoma runs on macOS and Linux (Unix). Windows is not supported (it uses Unix-only APIs).
The full-screen image / PDF / SVG / Mermaid / LaTeX math / video previews are drawn as real pixels in any terminal that speaks a graphics protocol — kitty graphics (Ghostty, kitty, WezTerm, Konsole), iTerm2, or sixel. konoma has its own compressed transfer for the kitty protocol, so those terminals are the fastest. Anywhere else the picture degrades to a half-block approximation — coarse, but visible. Text previews (Markdown, code, git diffs, CSV, tables) work in any terminal.
Of the OS/arch combinations, macOS on Apple Silicon is the most battle-tested. Intel macOS works too, and Linux x86_64 builds and passes the full test suite in CI, ships prebuilt binaries, and has had its previews verified rendering via kitty graphics — still beta, as it is newer than the macOS path.

Fonts — two glyph coverages matter:

Icons (ui.icons = true, the default) need Nerd Font glyphs. Add Symbols Nerd Font Mono as a fallback font, or use a Nerd-Font-patched font. No Nerd Font? Set ui.icons = false for plain ASCII symbols (no tofu).
CJK text (the jp UI, or CJK filenames / file contents) needs the terminal font to include CJK glyphs — otherwise CJK shows as tofu (□). konoma computes the display widths correctly regardless; the glyphs come from the font. A Nerd-Font-patched CJK font such as HackGen Console NF or UDEV Gothic NF covers both needs (icons and CJK) in a single font.

Optional tools, all degrading gracefully when absent: git (git suite), ffmpegthumbnailer / ffmpeg (thumbnails for the video formats konoma can’t decode itself — VP9, AV1, the older codecs, .avi), jj if you work in jj (preview — without it konoma simply falls back to git), and lazygit / lazyjj only if you want ! to open a TUI inside the hub. Images, SVG, Markdown, Mermaid, LaTeX math, CSV, code, PDF (any page, via J/K) and H.264 / HEVC video thumbnails (.mp4/.m4v/.mov and .mkv/.webm) render natively in Rust — nothing else to install at all.

Set up from scratch

Starting from a machine with nothing installed, here is the full path to a working konoma with image previews.

macOS (Apple Silicon)

Homebrew (skip if you have it) — the package manager:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

A terminal with a graphics protocol — Ghostty speaks kitty graphics, the fastest path for konoma’s images:
Terminal window
```
brew install --cask ghostty
```
(macOS’s own Terminal.app has no graphics protocol, so pictures there fall back to half-blocks; iTerm2 and any sixel-capable terminal work as well.)
A font with Nerd Font + CJK glyphs (covers icons and Japanese in one):
Terminal window
```
brew install --cask font-hackgen-console-nf
```
Then in Ghostty’s config (~/.config/ghostty/config) set:
```
font-family = "HackGen Console NF"
```
konoma — the quickest is the prebuilt binary:
Terminal window
```
brew install cargo-binstall
cargo binstall konoma
```
Prefer to build from source? Install Rust first, then cargo install konoma:
Terminal window
```
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install konoma
```
Optional tools for richer previews:
Terminal window
```
brew install git ffmpeg
brew install jj          # only if you work in jj (preview)
brew install lazygit lazyjj   # only if you want `!` to open a TUI
```
PDF pages render without any of this (pure-Rust hayro, any page via J/K), and macOS’s own qlmanage/sips — already installed — cover the rare PDF hayro can’t handle. H.264 and HEVC video in .mp4/.m4v/.mov and .mkv/.webm is decoded natively too — including what an iPhone records by default; ffmpeg adds thumbnails for the rest (VP9, AV1, older codecs). git is what the git suite runs on, and jj likewise for jj (Jujutsu) — without either, konoma simply shows no repository information for that system, and it reads a jj repository without ever writing to it. lazygit and lazyjj are only what the ! key opens; skip them and that one key says so. jj is not in Debian/Ubuntu’s archives: use its own instructions or cargo binstall jj-cli.

Run it — open Ghostty, then:

konoma            # the current directory
konoma ~/work     # or any directory · press ? for help

Linux (x86_64 · beta)

Commands below use apt (Ubuntu/Debian); adapt for your package manager.

A terminal with a graphics protocol — kitty is the simplest on Linux:
Terminal window
```
sudo apt install kitty
```
(Ghostty and WezTerm speak kitty graphics too; a sixel-capable terminal such as Konsole or xterm with sixel enabled also shows real pixels, just without konoma’s compressed transfer.)
Fonts — CJK glyphs plus a Nerd Font:
Terminal window
```
sudo apt install fonts-noto-cjk        # CJK glyphs
```
For a single font covering both Nerd Font icons and CJK, download a Nerd-Font-patched CJK font (e.g. HackGen NF) into ~/.local/share/fonts/, run fc-cache -f, then set it as kitty’s font_family.

konoma — the quickest is the prebuilt binary from the releases page (konoma-x86_64-unknown-linux-gnu.tar.gz); extract it onto your PATH. To build from source instead, install Rust and the C-library headers konoma’s dependencies need:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
sudo apt install pkg-config cmake libssl-dev libssh2-1-dev zlib1g-dev \
  libdbus-1-dev libxcb1-dev libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev git
cargo install konoma

Optional tools — PDF needs nothing here either: pure-Rust hayro renders every page, and there is no external PDF tool on this platform at all (the qlmanage/sips fallback is macOS-only). H.264 and HEVC video thumbnails (.mp4/.m4v/.mov and .mkv/.webm) need nothing either; ffmpeg covers VP9/AV1 and the older codecs.
Terminal window
```
sudo apt install ffmpeg git
```
Run it inside that terminal:
Terminal window
```
konoma            # press ? for help
```

The two-screen model

konoma            # browse the current directory
konoma ~/work     # or any directory

konoma has exactly two main screens and no split panes:

Tree — the full-screen file tree. Move with j/k, expand/enter with l or Enter, go to the parent with h.
Preview — the full-screen view of the selected file. q (or Esc) returns to the tree.

Everything else (git views, bookmark list, help) layers on top of these two. Two habits carry you everywhere:

? shows help for the screen you are on. Every view documents its own keys.
q goes back one level. Q quits from anywhere (with a confirmation).

Five-minute tour

Launch konoma in a project directory.
Type / and a few letters — the tree filters as you type. Esc clears.
Select a Markdown file, press Enter — it renders with headings, tables and links. Press Tab to focus a link, Enter to follow it, q to come back.
Select an image or PDF — full-screen pixels; +/- zooms, J/K turns PDF pages.
In a git repository, press o — the changes hub. Enter on a file shows its full-screen diff; l is the log; g is the commit graph. q backs out.
Press m then a to bookmark where you are; press ' to see the bookmark list and jump.

The built-in tutorial

The repository ships a hands-on tour designed to be read inside konoma — links you can follow, checkboxes you can actually toggle:

git clone https://github.com/LESIM-Co-Ltd/konoma
konoma konoma/samples        # then open tutorial.md

Where next

Tutorial — the same tour as above, in seven guided steps.
Working with an AI agent — konoma’s flagship workflow.
Previews in depth — Markdown, tables, media, copying.
The git suite — hub, diffs, log, graph, branches.
Files, bookmarks & tabs — the file-manager side.
Configuration — every option, one page.