konoma

Terminal file browser built for AI pair-programming — full-screen previews (Markdown, images, PDF, CSV), a git suite, and an agent-watch mode that follows your AI's edits. macOS & Linux · 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.

📖 Documentation: lesim-co-ltd.github.io/konoma — getting started, guides and full reference, in English and 日本語.

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

Agent watch — konoma follows your AI's edits

Press F and konoma stops being a browser you drive: whenever a file changes on disk, it jumps there by itself and shows a diff of what changed since you pressed F — not the full git diff. That distinction is the point. A working tree you hand to an agent usually already has your own edits in it; follow mode hides those and shows you only what the agent just did. Press f to swap between the two views, n/N to cycle the files touched in this session, and q to stop.

Features

• Full-screen preview: images, Markdown, Mermaid, code, SVG, video thumbnails, and PDF (multi-page, navigate with J/K) rendered to fill the screen.
• Table preview: CSV/TSV render as an aligned, rainbow-column table with a cell cursor; archives (.zip/.tar/.tar.gz) list their entries — name, size, modified date — in the same grid, without extracting anything.
• 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: on a kitty-graphics terminal konoma transmits images itself, zlib-compressed, so a full-screen image or a zoom step appears immediately instead of streaming megabytes of escape codes. Other terminals (sixel, iTerm2, half-blocks) fall back to ratatui-image.
• Agent watch: F follows whatever your AI edits — konoma jumps to each file on its own and shows the diff since you pressed F, so pre-existing changes stay out of the way.
• 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)

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

• A terminal that speaks the kitty graphics protocol — Ghostty, kitty, WezTerm, or Konsole — for the image / PDF / SVG / video previews. Text previews (Markdown, code, git diffs) work in any terminal.
• OS: konoma runs on macOS and Linux (Unix). Of the 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. Windows is not supported (Unix-only APIs; no kitty graphics in Windows terminals).
• Fonts: icons need Nerd Font glyphs (or set ui.icons = false), and CJK text (the jp UI, CJK filenames/contents) needs the terminal font to include CJK glyphs or it shows as tofu (□) — konoma computes the widths correctly regardless. A Nerd-Font-patched CJK font like HackGen Console NF covers both in one font.
• Optional tools (all degrade gracefully): ffmpeg (video thumbnails), git (git suite), lazygit (external git tool on !). PDF, images, SVG, Mermaid, LaTeX math and CSV need nothing — konoma renders them itself.

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.

Take the tour: open samples/tutorial.md (日本語) inside konoma — a hands-on walkthrough with links you can follow and checkboxes you can actually toggle.

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:

brew install ffmpeg git           # macOS
sudo apt install ffmpeg git       # Debian / Ubuntu

• poppler (pdftoppm / pdftocairo) — PDF pages render natively in Rust (hayro, no external tool needed, any page via J/K); poppler (plus macOS's built-in qlmanage/sips) is only a fallback for the rare PDF the built-in renderer can't handle (encrypted, corrupt, or otherwise unsupported).
• 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.

Images, SVG, Markdown, Mermaid, LaTeX math, CSV and code need nothing extra — konoma renders them itself. The picture formats do need a terminal that speaks the kitty graphics protocol; text previews work anywhere.

Configuration

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

• CONFIGURATION.md — full reference: every [ui] option, colors/themes, preview rules (built-in renderers & external-command delegation), external editor, git integration, and the complete keybinding model.
• config.example.toml — a fully commented example config; copy it as a starting point. A Japanese-annotated copy is at config.example.ja.toml.

License

MIT © LESIM