はじめる

端末と Rust が既にあるなら、インストールはこれだけです:

cargo binstall konoma        # プレビルドバイナリ(cargo-binstall は Homebrew で導入)
# または
cargo install konoma         # Rust ツールチェーンでソースからビルド

cargo を使わない場合は GitHub のリリースページから tarball を直接ダウンロードできます。何もインストールされていない状態から始める なら、下の ゼロからのセットアップ を参照してください。

動作要件

konoma の本領を発揮するゲートは OS ではなく 端末 です:

• konoma は macOS と Linux(Unix)で動きます。Windows は非対応(Unix 専用 API を 使うため)。
• 全画面の 画像 / PDF / SVG / Mermaid / LaTeX 数式 / 動画プレビューは、 グラフィックプロトコルを話す端末なら実ピクセルで描かれます — kitty graphics (Ghostty・kitty・ WezTerm・Konsole)・iTerm2・sixel。konoma は kitty 向けに自前の圧縮転送を持つので、kitty 系がいちばん速く出ます。それ以外の端末では ハーフブロックの近似表示に落ちます(粗いですが映ります)。テキスト系プレビュー (Markdown・コード・git diff・CSV・表)は どの端末でも 完全に動きます。
• OS/アーキの組合せでは macOS (Apple Silicon) が最も実績があります。Intel macOS も 動作し、Linux x86_64 は CI で全テストが通りプレビルドも配布・プレビューが kitty graphics で描画されることも検証済みですが、macOS より新しいため beta です。

フォント — 2種類のグリフが関係します:

• アイコン(ui.icons = true・既定)には Nerd Font グリフが必要。端末の フォールバックに Symbols Nerd Font Mono を足すか、Nerd Font 内蔵フォントを使用。 無ければ ui.icons = false でプレーン記号(豆腐を出さない)。
• CJK 文字(jp UI・CJK のファイル名/ファイル内容)には端末フォントに CJK グリフが必要です — 無いと CJK が豆腐(□)になります。konoma は表示幅を正しく 計算しますが、グリフ自体はフォント側が担います。Nerd Font 内蔵の CJK フォント (HackGen Console NF・UDEV Gothic NF など)なら、アイコンと CJK の両方を 1つのフォントで賄えます。

任意ツール(無くてもその機能以外は動作): git(git スイート)・ ffmpegthumbnailer/ffmpeg(konoma 自身がデコードできない動画=VP9・ AV1・旧世代コーデック・.avi のサムネイル)・jj で作業しているなら jj(プレビュー版。無ければ git に 落ちるだけ)・! で TUI を開きたいなら lazygit / lazyjj。 画像・SVG・Markdown・Mermaid・LaTeX 数式・CSV・コード・PDF (J/K で全ページ)・H.264/HEVC 動画のサムネイル (.mp4/.m4v/.mov と .mkv/.webm)は Rust ネイティブで動作 — 追加インストールは一切不要です。

ゼロからのセットアップ

何もインストールされていないマシンから、画像プレビューが動く konoma まで一通りの手順です。

macOS (Apple Silicon)

1. Homebrew(あればスキップ)— パッケージマネージャ:

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

2. グラフィックプロトコル対応端末 — Ghostty は kitty graphics を話すので、 konoma の画像がいちばん速く出ます:

   brew install --cask ghostty

   (macOS 標準の Terminal.app はグラフィックプロトコルを持たないので、画像は ハーフブロックの近似表示になります。iTerm2 や sixel 対応端末でも実ピクセルで出ます。)
3. Nerd Font + CJK グリフ入りフォント(アイコンと日本語を1つで):

   brew install --cask font-hackgen-console-nf

   Ghostty の設定(~/.config/ghostty/config)に:

   font-family = "HackGen Console NF"

4. konoma — 最速はプレビルドバイナリ:

   brew install cargo-binstall
   cargo binstall konoma

   ソースからビルドするなら、先に Rust を入れて cargo install konoma:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   cargo install konoma

5. 任意ツール(リッチなプレビュー用):

   brew install git ffmpeg
   brew install jj               # jj で作業している場合だけ(プレビュー)
   brew install lazygit lazyjj   # `!` で TUI を開きたい場合だけ

   PDF はこれ無しで全ページ描画できます(純 Rust の hayro・J/K で ページ送り)。hayro が扱えない稀な PDF は macOS 同梱の qlmanage/sips が拾うので、こちらも導入不要です。.mp4/.m4v/.mov と .mkv/.webm の H.264 と HEVC(iPhone の既定録画形式)もネイティブでサムネイル化するので不要。 ffmpeg はそれ以外(VP9・AV1・旧世代コーデック)のサムネイル用、 git は git スイートの動作に必要で、jj (Jujutsu) で作業して いるなら jj も同様です(どちらも無ければ、そのシステムのリポジトリ情報が出なく なるだけ。konoma は jj リポジトリを読むだけで書き込みません)。 lazygit と lazyjj は ! キーで開く外部 TUI 専用で、押さないなら不要です。 jj は Debian/Ubuntu の公式リポジトリには無いので、 jj 自身の手順 か cargo binstall jj-cli で入れてください。
6. 起動 — Ghostty を開いて:

   konoma            # カレントディレクトリ
   konoma ~/work     # 任意のディレクトリ · ? でヘルプ

Linux (x86_64 · beta)

以下は apt(Ubuntu/Debian)の例です。お使いのパッケージマネージャに読み替えてください。

1. グラフィックプロトコル対応端末 — Linux では kitty が最も簡単:

   sudo apt install kitty

   (Ghostty・WezTerm も kitty graphics 対応。Konsole や sixel を有効にした xterm など sixel 対応端末でも実ピクセルで出ます。konoma の圧縮転送が効かないだけです。)
2. フォント — CJK グリフ + Nerd Font:

   sudo apt install fonts-noto-cjk        # CJK グリフ

   アイコンと CJK を1フォントで賄うなら、Nerd Font 内蔵 CJK フォント(HackGen NF 等)を ~/.local/share/fonts/ に入れて fc-cache -f、kitty の font_family に設定。
3. konoma — 最速は リリースページの プレビルド(konoma-x86_64-unknown-linux-gnu.tar.gz)を展開して PATH に置く。 ソースからビルドするなら、Rust と依存 C ライブラリのヘッダを入れます:

   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

4. 任意ツール — PDF はここでも何も要りません(純 Rust の hayro が全ページを 描画)。このプラットフォームには外部 PDF ツールがそもそも無く、 qlmanage/sips のフォールバックは macOS 専用です。.mp4/.m4v/.mov と .mkv/.webm の H.264/HEVC 動画サムネイルも不要で、ffmpeg は VP9/AV1 と 旧世代コーデックのためのものです。

   sudo apt install ffmpeg git

5. 起動 — その端末の中で:

   konoma            # ? でヘルプ

2画面モデル

konoma            # カレントディレクトリを開く
konoma ~/work     # 任意のディレクトリ

konoma のメイン画面は2つだけで、分割ペインはありません:

1. ツリー — 全画面のファイルツリー。j/k で移動、l か Enter で 展開/潜行、h で親へ。
2. プレビュー — 選んだファイルの全画面表示。q(または Esc)でツリーへ。

git ビューやブックマーク一覧・ヘルプは、この2画面の上に重なります。 覚えるべき習慣は2つ:

• ? = いま見ている画面のヘルプ。 すべてのビューが自分のキーを説明します。
• q = 一段戻る。 Q はどこからでも終了(確認付き)。

5分ツアー

1. プロジェクトのディレクトリで konoma を起動。
2. / を押して数文字入力 — ツリーが絞り込まれます。Esc で解除。
3. Markdown ファイルを選んで Enter — 見出しや表つきで描画されます。 Tab でリンクをフォーカス、Enter で辿り、q で戻る。
4. 画像や PDF を選ぶ — 実ピクセルの全画面表示。+/- でズーム、 PDF は J/K でページ送り。
5. git リポジトリ内で o — 変更ハブが開きます。ファイル上の Enter で 全画面 diff、l で log、g でコミットグラフ。q で戻る。
6. m → a で現在地をブックマーク。' で一覧が開き、英字キーでジャンプ。

組み込みチュートリアル

リポジトリには konoma 自身で読むハンズオンツアーが同梱されています — 実際に辿れるリンクと、実際にトグルできるチェックボックス付きです:

git clone https://github.com/LESIM-Co-Ltd/konoma
konoma konoma/samples        # tutorial.ja.md を開く

次に読む

• チュートリアル — 7ステップのガイド付きツアー。
• AI エージェントと働く — konoma の看板ワークフロー。
• プレビューを使い倒す — Markdown・テーブル・メディア・コピー。
• git スイート — ハブ・diff・log・グラフ・ブランチ。
• ファイル・ブックマーク・タブ — ファイルマネージャとしての顔。
• 設定リファレンス — 全オプションを1ページで。