Skip to content
konoma
konoma — sunlit forest seen through the gap between two trees

See everything, full screen.

konoma is a terminal file browser with one idea: pick in a tree, preview full screen. Markdown, images, PDFs, CSV tables, git diffs and commit graphs — rendered right in your terminal, and built to sit next to an AI coding agent.
Get startedTutorialView on GitHub

Why konoma?

Section titled “Why konoma?”

Full-screen previews

No split panes. The tree is full screen, the preview is full screen, and you flip between them with two keys. Markdown renders decorated (tables, Mermaid diagrams, inline images, interactive checkboxes), code gets syntax highlighting, CSV becomes a navigable table, images/PDF/SVG draw as real pixels through your terminal’s graphics protocol.

Built for AI pair work

Put konoma on the left, your coding agent on the right. Follow mode (F) automatically shows the diff of whatever the agent just changed, C lists every uncommitted file, and one key copies @path#L12-34 references to paste into the conversation.

A real git client

Stage, unstage, commit, full-screen diffs, a log, branches, and a custom-rendered commit graph with square corners and a pinnable base branch — all inside the browser.

Config-driven, safe by default

Every format→viewer mapping and every key is declared in one TOML file. Unknown files degrade to a safe screen instead of crashing; deletions go to the trash behind a confirmation; a broken config never bricks the UI.

In action

Section titled “In action”
konoma tour — tree, full-screen image preview, Markdown, code with a git gutter, and the git graph

Tree view with git status colors

Custom git commit-graph renderer

A Mermaid diagram and LaTeX math rendered as real images in a Markdown preview

A sequence diagram with an actor, an activation bar and an alt block, drawn by konoma’s own Mermaid renderer

Tables with inline styling and alignment, a horizontal rule, and interactive task lists in a Markdown preview

GitHub-style alerts, autolinks, emoji, and footnotes in a Markdown preview

Documentation

Section titled “Documentation”
Getting startedInstall, the two-screen model, a five-minute tour.
TutorialA guided tour in seven steps — follow along in your terminal.
Working with an AI agentFollow mode, changed-files view, @path references.
Previews in depthMarkdown, checkboxes, tables, media, copying.
Mermaid catalogAll 23 diagram kinds, drawn by konoma itself.
The git suiteHub, diffs, log, commit graph, branches.
Files, bookmarks & tabsFiltering, safe file ops, bookmarks, tabs.
ConfigurationEvery option — UI, colors, preview rules, keys.
Default keymapKey bindings per screen, all rebindable.

Install

Section titled “Install”
Terminal window
cargo binstall konoma       # prebuilt binary (needs cargo-binstall)
# or
cargo install konoma        # build from source

macOS on Apple Silicon is the primary target. Intel macOS and Linux x86_64 also build, pass the full test suite in CI, and ship prebuilt binaries; on Linux the image, PDF, and Markdown previews are verified to render via kitty graphics (still beta — newer than the macOS path). Pictures are drawn as real pixels in any terminal that speaks a graphics protocol — kitty graphics (e.g. Ghostty), iTerm2, or sixel — and degrade to a half-block approximation elsewhere. Then:

Terminal window
konoma [DIR]

Press ? on any screen for help, and take the built-in tour: open samples/tutorial.md from the repository in konoma and learn by doing.