---
title: Getting started
description: Install konoma, learn the two-screen model, and take the five-minute tour.
---

## Install

```sh
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](https://github.com/LESIM-Co-Ltd/konoma/releases) if you
don't use cargo at all.

**Requirements**

- macOS on Apple Silicon is the primary target (Intel macOS works; Linux x86_64
  builds are experimental; no Windows).
- Image / SVG / video-thumbnail / PDF previews need a terminal with the **kitty
  graphics protocol** — [Ghostty](https://ghostty.org) or kitty. Text previews
  work in any terminal.
- Icons need Nerd Font glyphs: add `Symbols Nerd Font Mono` as a fallback font,
  or use an NF-bundled font (HackGen Console NF, UDEV Gothic NF, …). No Nerd
  Font? Set `ui.icons = false` in the config for plain symbols.

Optional tools, all degrading gracefully when absent: `git` (git suite),
`poppler` (multi-page PDF), `ffmpegthumbnailer`/`ffmpeg` (video thumbnails),
`lazygit` (external git tool on `O`).

## The two-screen model

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

konoma has exactly two main screens and no split panes:

1. **Tree** — the full-screen file tree. Move with `j`/`k`, expand/enter with
   `l` or `Enter`, go to the parent with `h`.
2. **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

1. Launch `konoma` in a project directory.
2. Type `/` and a few letters — the tree filters as you type. `Esc` clears.
3. 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.
4. Select an image or PDF — full-screen pixels; `+`/`-` zooms, `J`/`K` turns
   PDF pages.
5. 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.
6. 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:

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

## Where next

- [Tutorial](../tutorial/) — the same tour as above, in seven guided steps.
- [Working with an AI agent](../guides/agent-watch/) — konoma's flagship workflow.
- [Previews in depth](../guides/preview/) — Markdown, tables, media, copying.
- [The git suite](../guides/git/) — hub, diffs, log, graph, branches.
- [Files, bookmarks & tabs](../guides/files/) — the file-manager side.
- [Configuration](../reference/configuration/) — every option, one page.
