konoma

Full-screen preview-focused terminal file browser. macOS / Apple Silicon · Rust · MIT

Pick something in the tree, and preview it full-screen. konoma is a terminal file browser built around that single idea. It is made for a side-by-side workflow where you keep konoma on one half of the screen and work on the other.

The name "konoma" (木の間, "between the trees") comes from the tool's character: peering through the gaps between the trees to look into the contents of the file tree.

Why it exists

When you want a tree + preview pane filling one half of the screen while you work on the other, existing TUI file managers (such as yazi) cannot structurally remove the file-list panel, so they cannot show only the selected file full-screen. konoma solves that one thing with mode transitions: Tree (full-screen) ⇄ Preview (full-screen), with no in-between split view.

Screenshots

Features

• Full-screen preview: images, Markdown, Mermaid, code, SVG, video thumbnails, and PDF (multi-page, navigate with J/K) rendered to fill the screen.
• Config-driven delegation: declare how each format is previewed in TOML — delegate to a built-in renderer or an external command. Unsupported formats safely show [can not preview] full-screen instead of crashing.
• kitty graphics: images use the kitty graphics protocol via ratatui-image for high quality.
• Git suite: status, diff, log, a custom commit-graph renderer, branches, and commits, all in-app.
• File manager: create / rename / delete (trash by default) / copy / move, plus search, bookmarks, and sorting. Destructive actions require a confirmation dialog.
• Optional dependencies: the app never breaks when an external tool (mpv, etc.) is missing. It runs from a plain cargo install.

Status

Pre-release (feature-complete). The milestones below track what is implemented.

• Tree view & navigation, mode transitions, can not preview fallback (M0/M1)
• Full-screen images with zoom/pan (M2)
• Markdown / Mermaid rendering (M3)
• Tabs and path copy (M4)
• Git integration: status, diff, log, graph, branches, commits (M5)
• Video thumbnails (representative frame; no in-terminal playback) and GIF/SVG preview (M6)
• PDF preview (multi-page, one page at a time)
• File manager: create / rename / delete / copy / move, search, bookmarks, sorting (M7)
• Configurable keymap with conflict detection
• crates.io publish
• Prebuilt binaries and cargo binstall (macOS, Linux x86_64)

Requirements

• macOS on Apple Silicon is the primary target. macOS on Intel (x86_64) also has prebuilt binaries. Linux (x86_64) builds in CI and has prebuilt binaries too, but is experimental — its runtime (previews, clipboard, trash) is not yet verified. Windows is not supported.
• A terminal that supports the kitty graphics protocol (e.g. Ghostty) for image, SVG, video-thumbnail, and PDF previews. Without it, text-based previews still work.

Install

Prebuilt binaries (fastest — no compilation) via cargo-binstall:

cargo binstall konoma

Or compile and install from crates.io:

cargo install konoma

Prebuilt archives for macOS (Apple Silicon / Intel) and Linux (x86_64) are also attached to each GitHub Release.

Or build from source:

cargo build --release

Usage

konoma [DIR]     # opens DIR (defaults to the current directory)

Press ? in the app for the full, context-sensitive key reference.

Optional tools

konoma never breaks when an external tool is missing — the relevant preview just degrades to a hint (principle: "unsupported is shown safely, never a crash"). Install these to enable richer previews:

• poppler (pdftoppm / pdftocairo / pdfinfo) — PDF rendering and multi-page navigation. Without it, macOS falls back to qlmanage/sips for the first page only.
• ffmpeg or ffmpegthumbnailer — video thumbnail frames.
• git — the in-app git suite (status / diff / log / graph / branches). Enabled by default; build with --no-default-features to drop it.

Configuration

~/.config/konoma/config.toml (works with defaults if absent). See config.example.toml.

License

MIT © LESIM