vig ユーザーガイド

vig はリポジトリと、その周りで動いているものを見張るための閲覧専用 TUI コックピットです: git (サイドバイサイドの差分・ログ・reflog)、GitHub の issue / PR / Actions 実行 / Projects ボード、ファイルブラウザ、Docker コンテナ、プロセス、worktree / stash。全体を vim スタイルのキーで操作できます。AI エージェントが作業するリポジトリを含め、busy なリポジトリの監視を想定して作られています。

安全設計 — vig は読み取り操作と安全な git コマンド（git switch、 git branch -d）のみを実行します。merge、rebase、force delete、push などの破壊的操作は意図的に除外しています。vig はリポジトリを 眺めるためのツールであり、変更するためのツールではありません。

このガイドの構成

• Getting Started — インストール、最初の起動、 7 つのビューのツアー、必要な環境。
• ビュー — ビューごとに 1 章: 何が表示されるか、 すべてのキーバインド、各ビューの制約。
• 設定の基本 — 設定ファイルの場所、3 つの レイヤ（組み込み → ユーザー → リポジトリローカル）、vig config サブコマンド、最低限の KDL、マージ規則。
• 設定レシピ — コピーしてそのまま使える実例集: テーマ、キーバインド、タブ、レイアウト、slot、ボードの固定、 リポジトリごとの設定、ポーリング。すべての例は CI で検証されています。
• 設定リファレンス — 完全なリファレンス: すべてのノードの書式・デフォルト・マージ規則・エラーと、全ページの ペインとアクション。
• トラブルシューティング / FAQ — 設定エラー、 gh の認証とスコープ、レート制限、フォント、画像プレビュー、vig が ファイルを置く場所。

English version

このガイドの英語版はこちら: vig User Guide （リポジトリ内: docs/guide）。

Getting Started

vig はすべて端末内で動きます。インストールして Git リポジトリに cd し、 vig を実行するだけ — 設定なしでそのまま使えます。

インストール

Homebrew

brew install td72/tap/vig

ビルド済みバイナリ

GitHub Releases ページから ビルド済みバイナリをダウンロードできます:

# Linux x86_64
curl -sL https://github.com/td72/vig/releases/latest/download/vig-x86_64-unknown-linux-gnu.tar.gz | tar xz -C ~/.local/bin vig

# Linux aarch64
curl -sL https://github.com/td72/vig/releases/latest/download/vig-aarch64-unknown-linux-gnu.tar.gz | tar xz -C ~/.local/bin vig

# macOS Apple Silicon
curl -sL https://github.com/td72/vig/releases/latest/download/vig-aarch64-apple-darwin.tar.gz | tar xz -C ~/.local/bin vig

crates.io

cargo install vig

ソースからビルド

必要なもの: Rust ツールチェイン, libgit2, libssl, pkg-config

cargo install --path .

最初の起動

Git リポジトリ内で vig を実行します:

cd your-repo
vig

起動すると Git ビュー が表示されます。左に変更ファイル、その隣に ブランチと reflog、残りの画面いっぱいにサイドバイサイドの diff です。 ヘッダにはビューが番号付きタブ（1:Git、2:GitHub、…）で並び、数字キーで 切り替えられます。下部のステータスバーには現在のモードと、フォーカス中の ペインでよく使うキーが表示されます。

初日に知っておくと良いこと:

• q または Ctrl+c で終了します。
• ? で現在のビューの全キーバインドを一覧するヘルプオーバーレイが開きます。
• r で現在のビューを再読込します。Git ビューはファイルの変更を監視して 自動でも更新されます。
• vig は設定なしで動きます。変えたくなったら KDL ファイル 1 つで設定できます （--config <path>、$VIG_CONFIG、または ~/.config/vig/config.kdl）。 詳しくは設定の章を参照してください。

7 つのビューのツアー

vig には 7 つのビューがあります。それぞれ ビュー の章で詳しく 説明します。ここでは 30 秒版のツアーです。

1 — Git

vig の中心です。シンタックスハイライト付きのサイドバイサイド diff、 ステータス表示付きのファイルツリー、git log プレビュー付きのブランチ セレクタ、そして reflog。任意のブランチや reflog エントリと比較でき、 vim モーションでヤンクし、$EDITOR でファイルを開けます。

2 — GitHub

Issue、Pull Request（本文、コメント、レビュー、CI ステータス）、Actions の ワークフロー実行（ジョブ、ステップ、ジョブログ）を gh CLI 経由で 読み取り専用で閲覧できます。本文は Markdown としてレンダリングされます。

3 — Files

リポジトリをルートとした yazi 風の 3 カラムファイルブラウザです。 親ディレクトリ、現在のディレクトリ、シンタックスハイライト付きプレビュー。 画像もプレビューでき、グラフィックプロトコル対応端末では元の解像度で 描画されます。

4 — Docker

compose プロジェクトごとにまとめたコンテナ一覧、イメージ一覧、inspect サマリ、ログのライブ tail。docker CLI 経由の読み取り専用ビューです。

5 — Procs

CPU / メモリ付きのプロセスツリー、LISTEN 中のポートとその所有プロセス、 btop 風のシステム履歴グラフ、CPU / RSS スパークライン付きのプロセス詳細。 見るだけのビューで、シグナルを送ることはありません。

6 — Worktrees

worktree と stash を一覧し、HEAD コミットや stash のパッチを Git ビューと 同じサイドバイサイド diff ビューで表示します。

7 — Projects

リポジトリにリンクされた GitHub Projects (v2) のボード。Status ごとの カンバン列、ソートできるテーブルモード、全プロジェクトフィールドを表示する アイテム詳細。

vig 内でヘルプを見る

どのビューでも ? でヘルプオーバーレイが開き、現在のビューの全キー バインドが一覧されます。有効な設定から生成されるので、自分でリバインドした キーもそのまま反映されます。? または Esc で閉じます。

vig を最新に保つ

vig update

vig update は GitHub から最新リリースをダウンロードし、署名を検証して 現在のバイナリを置き換えます。ビルド済みリリースバイナリでインストールした 場合向けの機能です。Homebrew や cargo でインストールした場合は、パッケージ マネージャに任せるため brew upgrade vig / cargo install vig を使って ください。

必要な環境

vig 本体は Git リポジトリさえあれば動きます。一部のビューは外部ツールが あるときに使えます:

その他のメモ:

• Nerd Font — Files ビューのファイル種別アイコンには Nerd Font が必要です。端末のフォントが Nerd Font でない場合は設定に icons "none" を書いてください。
• $EDITOR — e で選択中のファイルを外部エディタで開きます。

ビュー

vig はビューの並びとして構成されています。ヘッダに 1:Git から 7:Projects まで番号付きタブとして並び、それぞれが独立したペイン構成と キーバインドを持ちます。続く章で 1 つずつ見ていきます。

読み取り専用という設計

キーの前に、すべてのビューを貫く方針を説明します。

vig は眺めるためのツールであり、変更しません。 プログラム全体で 書き込みを行うのは、ブランチのアクションメニューから実行できる 2 つの 安全な git コマンド — git switch と git branch -d（安全な削除。 未マージのブランチは git が拒否します）— だけです。それ以外 — GitHub、Docker、プロセス、worktree、stash、プロジェクトボード — は すべて厳密に読み取り専用です:

• GitHub ビューは実行の再実行・キャンセル・コメント・編集を一切しません。
• Docker ビューはコンテナやイメージの起動・停止・削除をせず、環境変数も 表示しません。
• Procs ビューはシグナルを送らず、環境変数を読み取り・表示しません。
• Worktrees ビューは apply も drop も prune もしません。
• Projects ビューはアイテムの追加・移動・編集・削除をしません。

vig を一日中開いていてもシステムは何も変わりません。破壊的操作（merge、 rebase、force delete、push）は「設定の奥に隠されている」のではなく、 コードに存在しません。

ビューの切り替え

数字はヘッダ内のビューの位置で、設定の pages リストの順序に対応します。 リストを絞ったり並べ替えたりすれば番号も変わります。

全ビュー共通の作法

各ビューは意図的に同じ操作感になっています:

• j / k で移動、gg / G で先頭 / 末尾、Ctrl+d / Ctrl+u で 半ページスクロール。
• Tab / Shift+Tab でビュー内のペインを順に切り替え。
• リストで項目を選ぶと詳細 / プレビューペインが即座に追従します。i または Enter でフォーカスを移し、h または Esc で戻ります。
• / でフォーカス中のペイン内を検索、n / N でマッチ間を移動 （大文字小文字を区別しません）。
• r で再読込、? でヘルプ、q / Ctrl+c で終了。

各章のキーテーブルは デフォルト のバインドで、 組み込み設定 (assets/default.kdl) に基づいており、これが正となります。 README は 要約版で、細かいキーは載っていないことがあります。すべてのキーは リバインド・アンバインドできます。詳しくは設定の章を参照してください。

Git View

vig の中心となるビューです。ワーキングディレクトリと任意に選んだ base との サイドバイサイド diff を表示します。上部のペインとメインエリア:

• Files — 変更ファイルのツリー。ステータス表示付き （A 追加、D 削除、M 変更、R リネーム、? 未追跡）。
• Branches — ローカルブランチの一覧。選択中ブランチの git log プレビューがメインエリアに表示されます。
• Reflog — リポジトリの reflog エントリ。
• Diff / Git Log — メインエリア。シンタックスハイライト付きの サイドバイサイド diff、またはブランチ / reflog を眺めている間は log プレビュー。

このビューはワーキングディレクトリを監視し、ファイルが変わると diff を 自動更新します。r で手動更新、e で選択中のファイルを $EDITOR で 開けます。

ペイン間の移動

ペイン内の移動:

ブランチリスト

ブランチを選ぶとその git log がメインエリアにプレビューされます。Enter でアクションメニューが開きます — vig 全体で唯一リポジトリに書き込む場所で、 できることはちょうど 3 つです: ブランチへの切り替え（git switch）、安全な 削除（git branch -d。未マージなら git が拒否します — vig は -D を 使いません）、そして diff base への設定（diff ペインがワーキング ディレクトリとそのブランチを比較するようになります）。

Git Log

メインエリアの log プレビューはそれ自体を操作できます。コミットをたどり、 ハッシュをヤンクし、GitHub 上のコミットへジャンプできます。

Reflog

reflog ペインは「さっき何をした？」を diff で確認できるようにします。 任意の reflog エントリを選んで Enter を押すと diff base に設定され、 メインペインにその状態からの変更が表示されます。

Diff ペイン: モード

diff ペインは Scroll モードで始まり、j / k / h / l で スクロールします。i で Normal モードに入ると文字カーソルと vim モーションが使え、そこから v / V で選択を開始できます — vim のバッファ そのままの操作感です。

ヤンク（コピー）

Normal / Visual モードでのヤンクはシステムクリップボードに入ります:

テキストオブジェクトも対応: iw, aw, i", a", i(, a(, i{, a{

検索

全ペイン（DiffView、FileTree、CommitLog、Reflog）で検索でき、大文字小文字を 区別しません。

制約

• アクションメニューの git switch と git branch -d が vig 全体で 唯一の 書き込み操作です。ステージング・コミット・merge・rebase・ push・force delete はありません — 実装漏れではなく設計です。
• diff の片側は常にワーキングディレクトリで、もう片側の base（HEAD、 ブランチ、reflog エントリ）を選ぶのがあなたです。

GitHub View

GitHub の Issue・Pull Request・Actions のワークフロー実行を vig 内で直接 閲覧できます。上部に 3 つの列が並び、それぞれに詳細ビューがあります。 GitHub CLI (gh) のインストールと認証が必要で、 無い場合はペインの代わりに案内を表示します。

本文とコメントは Markdown としてレンダリングされます（見出し・リスト・ タスクリスト・コード・可能な範囲でペイン幅に収まるよう縮めたテーブル）。 sub-issue は親 issue の下に、GitHub Stack （gh stack で作るスタック PR）は 下から順に土台の PR の下にツリー表示されます。

Issue と Pull Request

j / k でリストを移動すると詳細が追従します。i または Enter で詳細 ビューに入り、h / l で本文と右側のサブペイン（コメント、レビュー、PR の CI ステータス）を切り替えます。o でブラウザで開きます。issue / PR の詳細 では w で watch モード を切り替えられます。約 10 秒ごとに表示中の アイテムを再取得するので、返信や CI の結果を待つあいだ最新のまま眺めて いられます。

issue / PR の一覧も API ポイントを使わずに最新を保ちます。vig は github-poll-interval ごとに、リポジトリで最後に更新された issue / PR を 1 件だけ 条件付き リクエストで問い合わせ（304 Not Modified の応答は 無料）、その答えが変わったときだけ両方の一覧と表示中の詳細を再取得します。 ステータスバーには一覧の経過時間（lists 12s ago）と、再取得直後は短く ↻ updated が出ます。このチェックも他のポーリングと同様に github-auto-refresh・アイドル時の間隔延長・残量が少ないときの抑制に 従います。

Workflow Runs

3 列目には最新 50 件のワークフロー実行（gh run list）がステータス・ ワークフロー名・実行番号・ブランチ・イベント・所要時間（実行中は経過時間）・ 経過日時とともに並び、queued / in progress の実行がある間は 5 秒ごとに 更新されます。

実行を選ぶと詳細エリアの Jobs サブペインにジョブがステップをぶら下げた ツリーで表示され（失敗したステップは赤）、ジョブまたはステップで Enter を 押すとそのジョブのログが Log サブペインに表示されます（ステップ境界と ##[group] はセクション行）。実行中ジョブのログは 5 秒ごとにポーリングして tail のように追記されます。] / [ で失敗ステップ間をジャンプ、G で 末尾へ移動して follow を再開します。

キーバインド

制約

• すべて gh CLI 経由なので、その認証とレートリミットの影響を受けます。
• このビューが実行を再実行・キャンセル・削除することはありません。 コメントも編集もマージもできません。読むだけです。

Files View

リポジトリをルートとした読み取り専用のファイルブラウザで、 yazi 風のレイアウトです。左カラムが 親ディレクトリ、中央が現在のディレクトリ、右が選択中エントリのプレビュー （テキストはシンタックスハイライト、ディレクトリは一覧）です。.git の 内部ファイルは隠され、シンボリックリンクには印が付きます。エントリには ファイル種別ごとの Nerd Font アイコンが付きます。端末のフォントが Nerd Font でない場合は設定に icons "none" を書いてください。

画像プレビュー

画像 (PNG / JPEG / GIF / WebP) はペイン内にプレビューされ、1 行目に形式・ 寸法・サイズ・使用中のレンダラが表示されます。グラフィックプロトコル対応 端末 (Kitty, WezTerm, Ghostty, iTerm2、foot などの Sixel 対応端末) では元の 解像度で描画され、それ以外では Unicode 半ブロックにフォールバックします。 設定の image-preview "halfblocks" で端末検出をスキップ、"none" で メタデータのみの表示になります。20 MB を超える画像はデコードしません。

Markdown プレビュー

Markdown ファイル（拡張子 .md / .markdown）はプレビューでレンダリング されます: 見出し・強調・リスト・タスクリスト・コード・GFM テーブル。 テーブルはペイン幅に合わせて調整され、リサイズで再レイアウトされます。 先頭の YAML フロントマターは薄い色でそのまま表示します。m でレンダリング と生テキスト（ハイライト表示）を切り替えられ（ペインタイトルに markdown / raw と表示）、既定は設定の markdown-preview で選べます。

長いファイルを読む

プレビュー内では h / l（または ← / →）で長い行を横スクロール できます — 折り返しはせず、行番号の欄はその場に残ります。/ で表示中の 内容（Markdown モードならレンダリング後のテキスト、それ以外は生の行）を 大文字小文字を区別せず検索でき、一致がハイライトされ、n / N で順に 移動し、現在の一致が見えるよう縦横にスクロールします。Esc は検索を クリアし、もう一度押すとファイル一覧に戻ります。画像プレビューには検索 対象がありません。

vig の外でファイルを開く

プレビューに加えて、Files ビューはファイルを他のプログラムに渡せます。 「アプリで開く」の概念があるのはこのビューだけです:

• e は選択中のファイルを外部エディタ（$EDITOR）で開きます。
• o は選択中のファイル / ディレクトリを OS の既定アプリで開きます （open / xdg-open / explorer）。
• O はアプリ名を入力して、そのアプリで開きます（macOS では open -a <app>）。

キーバインド

制約

• ブラウザのルートはリポジトリで、リポジトリより上へは移動しません。
• 厳密に読み取り専用です。作成・リネーム・削除・コピー・移動はできません。 できるのはファイルを $EDITOR や OS のオープナーに渡すところまでです。

Docker View

ローカルの Docker デーモンを読み取り専用で閲覧するビューです。docker CLI の JSON 出力 (docker ps / docker images / docker inspect / docker logs) だけを使います。docker がインストールされていない、または デーモンが起動していない場合はペインの代わりに通知を表示します。

コンテナは compose プロジェクトごとにまとめて表示され（実行中が先頭）、 詳細ペインには選択中のコンテナ / イメージの inspect サマリ、ログペインには 選択中コンテナのログ (--tail 200 のあと follow 中は毎秒 --since で追記) が表示されます。一覧は 5 秒ごとに更新されます。

キーバインド

制約

• docker CLI と起動中のデーモンが必要です。無い場合は通知が表示されます （デーモンを起動してから r を押してください）。
• 環境変数は 決して表示されません — inspect サマリから意図的に 除外しています。
• このビューがコンテナやイメージを起動・停止・再起動・削除することは ありません。実行するのは参照系の docker サブコマンドだけです。

Procs View

「いま何が動いているか」を読み取り専用で眺めるビューです。プロセスを親 pid ごとのツリーで CPU % と常駐メモリ付きで表示し、LISTEN 中の TCP / UDP ポートとその所有プロセス、選択中プロセスの詳細（pid、ppid、ユーザー、状態、 経過時間、CPU / メモリ、完全なコマンドライン、cwd、実行ファイル、 子プロセス、LISTEN ポート）を表示します。権限がなく読めない値は (no access) と表示されます。

プロセス情報は sysinfo、ポートは macOS では lsof、Linux では ss から取得します。ビュー表示中は 2 秒ごと （設定の procs-refresh-interval）と r で再読込します。

System グラフ

上部の System ペインはマシン全体の値を btop 風の塗りつぶしエリアチャートで 表示します。グローバル CPU %（直近ピーク付き）と使用メモリを直近 procs-history サンプル分（デフォルト 120 = 2 秒間隔で 4 分）描き、 スワップがあれば Swp 行も表示します。各サンプル列は負荷で色分けされます — 50 % 未満は緑、50 % 以上は黄、80 % 以上は赤 — パーセント表示のラベルも 同じ色です。

c で CPU チャートをコアごとの小さなゲージ表示（同じグラデーション）に 切り替えられます。チャートはバッファが埋まるまで右詰めで伸び、ビュー表示中 のみサンプリングされ、常にマシン全体が対象です（プロセス別の値ではなく 数値のみを描画します）。詳細ペインには選択中プロセスの CPU %（色分けあり）/ 常駐メモリの履歴チャートが CPU / MEM 欄の下に表示されます。

キーバインド

制約

• このビューは見るだけです — シグナルは送りません。kill も renice も stop もありません。
• 環境変数は一切読み取り・表示しません。
• 権限が足りない値は (no access) と表示され、ポートの所有情報も不完全に なることがあります。
• 他のビューを表示している間はサンプリングが止まるため、グラフはこの ビューを見ていた時間だけを描きます。

Worktrees View

リポジトリの worktree と stash を読み取り専用で一覧するビューです。左上の ペインは worktree の一覧（git worktree list）で、パス（可能なら main worktree からの相対パス）、チェックアウト中のブランチ（detached HEAD の 場合はそのハッシュ）、[main] [locked] [prunable] [bare] などの フラグを表示します。vig を起動した worktree には * が付きます。左下の ペインは stash の一覧（stash@{n}、メッセージ、作成元ブランチ、経過時間） です。

プレビューペイン

右のプレビューは選択に追従します:

• worktree を選ぶと HEAD コミット（ハッシュ、作者、日時、サブジェクト） と変更ファイルを表示します。
• stash を選ぶとその差分（untracked ファイルを含む）を Git ビューと 同じサイドバイサイド diff ビューで表示します。シンタックスハイライト、 検索、Normal / Visual モードとヤンクもそのまま使えます。複数ファイルの stash では [ / ] でファイルを移動できます。

キーバインド

制約

• このビューから apply・drop・追加・削除・lock・prune を行うことは一切 ありません。一覧とプレビューだけです。worktree や stash の管理は シェルで行ってください。

Projects View

現在のリポジトリにリンクされた GitHub Projects (v2) を読み取り専用のボード として眺めるビューです（リンクの取得は gh repo view --json projectsV2、 ボードは ボード本体は GraphQL）。

ボードは全幅で表示され、最初のリンク済みプロジェクトがすぐに読み込まれます。 列は Status の選択肢を GitHub 上の順に 1 列ずつ、加えてステータス未設定の アイテム用の No status 列です。カードにはアイテム種別（● issue、⇅ pull request、✎ draft）、番号、タイトル、担当者を表示し、別リポジトリの アイテムには番号の前に薄い色で owner/repo が付きます。

複数のリンク済みプロジェクトと固定

リンクされたプロジェクトが複数あるときはヘッダに Board: <タイトル> (i/n) と出て、p / P で順に切り替えられます。1 つもリンクされていないときは リンク方法（リポジトリの Projects タブ、または gh project link）を案内 します。設定のトップレベルに projects-board を書くと、タイトルまたは プロジェクト番号でボードを 1 つに固定できます — 設定リファレンスの projects-board を参照してください。

テーブルモードと詳細ペイン

t でテーブルモードに切り替わり、1 行 1 アイテムでプロジェクトの フィールド（Status、Priority、Estimate、Iteration、日付、カスタムの テキスト / 数値フィールド）を列として表示・ソートできます。h / l と s でソート列を選びます。

詳細ペインは選択中アイテムの全フィールド値に続けて、GitHub View と同じ issue / PR の本文とコメントを表示します（draft は本文のみ）。

オプションの projects 一覧ペイン

projects 一覧ペインも実装されていますが、組み込みレイアウトには配置 されていません。設定でレイアウトに配置すると、リンク済みプロジェクトを 選べる一覧が戻ってきます。貼り付けられるレイアウト例は 設定レシピ を参照してください。

保存済みビュー

プロジェクトの保存済みビュー（ProjectV2.views。gh project からは取れない ため GraphQL で取得）はボードと一緒に読み込まれます。ヘッダに現在のビュー名 とレイアウト（Board: vig demo board · Sprint [board] (2/3)）が表示され、 v / V で切り替えられます。保存済みビューが無いプロジェクト（またはビュー 取得に失敗した場合）は従来どおり Status 固定の kanban になります。 Table ビューは定義どおりに描画されます: 表示フィールドがそのまま列に （ビューの順、先頭に # 列）、ビューのソートが初期ソートに（降順は ▴ 表示）、グループ化はグループごとの太字見出し行に（No <field> は最後） なります。

Board ビューもビューの定義に従います: 列はビューの列フィールド （verticalGroupByFields — 単一選択またはイテレーションフィールド、 オプション順 + No <field>。未設定なら Status）、ソートは各列内の カード順、水平グループはスイムレーン（値ごとの帯 + 見出し行）に なります。Space で選択中レーンの折りたたみ、列の端で j / k を 押すと隣のレーンへ移動します。Roadmap ビューはタイムラインを描画します: 左にアイテム行、右に 時間軸（アイテムごとのバー、黄色の今日マーカー、イテレーションの帯）。 期間はプロジェクトの日付フィールド（名前に start / begin を含む ものが開始、target / end / due / finish を含むものが終了。日付 フィールドが 1 つだけなら点）から、日付の無いアイテムはイテレーション の開始 + 期間から求めます。+ / - で月 / 週 / 日のズーム、h / l で横スクロール、t でテーブルと行き来できます。期間の無いアイテムは バー無しで並びます。

ビューのフィルタ式（status:Todo -label:bug assignee:@me is:issue no:milestone …）は、取得済みのアイテムに対して手元で評価します（追加の API 呼び出しなし）。どのレイアウトでもグループ化・ソートの前に適用され ます。対応: タイトルの自由語、field:value（, 区切りの複数値・引用符付き の値）、- による否定、is:issue|pr|draft、no: / has:、assignee: （@me はサインイン中のログイン）、label:、milestone:、repo:。範囲 （>、..）・ワイルドカード・is:open|closed は評価できないため、 ステータスバーに ⚠ filter: unsupported "…" と出して無視します。フィルタ で隠れた件数もステータスバーに (3 filtered out) と表示されます。

キーバインド

自動更新

ページを表示している間、vig は projects-poll-interval （既定 30 秒）ごとにボードが変わったかを GitHub に尋ねます。プローブは プロジェクトの updatedAt だけを読み（GraphQL 1 ポイント。カードの移動や フィールド編集で動きます）、動いたときだけボードを再取得します。選択・ ビュー・ソートはそのまま保たれます。ステータスバーにはボードの経過時間 （board 12s ago）と、再取得直後は短く ↻ updated が出ます。5 分以上 経ってからページに戻ったときの stale 再取得もこれまで通りです。どちらも github-auto-refresh・アイドル時の間隔延長・残量が少ないときの抑制に 従います。

制約

• gh project にはトークンの project スコープが必要です。無い場合は ペインの代わりに案内を表示するので、gh auth refresh -s project を 実行してから r を押してください。
• ボードは GraphQL 2 リクエスト（フィールド・保存済みビュー・アイテム 数、次にその数に合わせたページでアイテム）で、表示に必要なものだけを 取得します。コストはアイテム × フィールド 100 組あたり約 1 ポイント （小さなボードで ~2 ポイント）。500 件を超える分はステータスバーに (truncated) と出ます。
• アカウントの GraphQL クォータ（5,000 ポイント/時）の残りが 1,500 を 切るとヘッダに ⚠ api N left と警告し、自動再取得は自分で減速・停止 します — トラブルシューティング参照。
• このビューからアイテムの追加・移動・編集・削除は一切行いません。

設定の基本

vig には完全な組み込み設定が入っていて、設定ファイルを書く必要は ありません。何かを変えたくなったら（テーマ、キー、タブ、レイアウト）、 1 つの KDL ファイルに変更点だけを書けば、vig がデフォルトの上に マージします。変えたい部分だけを書けばよい、ということです。

この章では、設定ファイルの場所、レイヤの重なり方、vig config サブコマンド、ファイルを読み書きするのに必要な最低限の KDL、そして マージ規則を説明します。次の 設定レシピ の章は 実例集で、掲載しているすべてのスニペットはそのまま動く完全な設定です。

3 つのレイヤ

vig は最大 3 つのレイヤを順に重ねて、有効な設定を組み立てます:

3. リポジトリローカル   worktree ルートの .vig.kdl   （個人用・リポジトリごと）
2. ユーザー             ~/.config/vig/config.kdl     （自分用・全リポジトリ共通）
1. 組み込み             埋め込まれたデフォルト        （常に存在）

vig config path を実行すると、3 つのレイヤそれぞれのパスと、 見つかったか・読み込まれたかの状態がいつでも確認できます。

1 — 組み込み

デフォルトはバイナリに埋め込まれています。それ自体が完全な KDL 設定 — vig config dump が出力するのと同じ assets/default.kdl — なので、設定できるものすべてがコメント付きで 1 か所にまとまって います。

2 — ユーザー

あなた自身の設定ファイルです。vig は次の順で探します:

1. コマンドラインフラグ --config <path>
2. 環境変数 $VIG_CONFIG
3. $XDG_CONFIG_HOME/vig/config.kdl。XDG_CONFIG_HOME が未設定なら ~/.config/vig/config.kdl — macOS を含む すべての OS で同じです （vig は意図的に ~/Library/Application Support を使いません。 zellij / helix などのユーザーがどのプラットフォームでも期待するのは ~/.config/vig だからです）

デフォルトの場所にファイルが無ければ単に「デフォルトを使う」ですが、 --config や $VIG_CONFIG で明示したパスは存在しなければなりません — 無ければ vig は起動を拒否するので、パスのタイポが黙って別の設定に すり替わることはありません。なお --config / $VIG_CONFIG はユーザー レイヤを置き換えるものであって、4 つ目のレイヤを増やすものでは ありません。

3 — リポジトリローカル（.vig.kdl）

vig は現在の worktree のルートにある個人用 .vig.kdl も読み、ユーザー 設定の上にマージします。これにより、リポジトリごとに別のテーマ・タブ・ キーバインドを持たせられます。スキーマはユーザー設定とまったく同じで、 gitignore しておく想定のファイルです — プロジェクトのものではなく、 あなたのファイルです。何を書くかは リポジトリごとの設定レシピ を参照してください。

クローンしたリポジトリがコミット済みの .vig.kdl を同梱している 可能性があるため、信頼するかどうかは git の追跡状態で決まります:

• 未追跡の .vig.kdl はあなた自身のファイルです。黙って読み込まれ、 起動時にステータスバーへ loaded .vig.kdl と一度表示されます。
• 追跡中の .vig.kdl はリポジトリ由来です。アプリが組み立てられる 前に信頼ダイアログが表示されます（回答次第でどのページ・どの キーバインドが存在するかまで変わるためです）。y で読み込んで記憶、 n で無視して記憶、v でファイルの中身を確認してから判断、Esc は 今回だけ無視して何も記憶しません。

決定は $XDG_STATE_HOME/vig/trust.json （~/.local/state/vig/trust.json）に、worktree パスとファイル内容の ハッシュをキーとして保存されます — ファイルが変わると（pull の後 など）古い決定は適用されず、もう一度確認されます。vig config trust で記憶済みの決定を一覧でき、vig config trust --forget <path> で 1 件を忘れさせられます。

このレイヤには、どちらも意図的な性質が 2 つあります:

• 中断せず、劣化する。 .vig.kdl のエラーが vig の起動を妨げる ことはありません。組み込み + ユーザーの設定で起動し、ステータス バーに ignored .vig.kdl: <理由>（stderr にも 1 行）が出ます。
• 自分のスイッチを自分で操作できない。 ユーザー設定に repo-config "off" と書けばこのレイヤは完全に無効になります — 読み込みもダイアログもなし。有効なのはユーザー設定の値だけで、 .vig.kdl 自身に repo-config を書くことは（"on" でも） 拒否されます。

vig config サブコマンド

どのサブコマンドも --config / $VIG_CONFIG を尊重するので、 vig --config ./try.kdl config path でそのファイルがどう扱われるかを 確かめられます。

dump をコピーして、削る

最初の設定ファイルを書く快適な方法:

mkdir -p ~/.config/vig
vig config dump > ~/.config/vig/config.kdl

ファイルを開き、変えたいところを変えたら、変えなかった部分をすべて 削除してください。あなたのファイルは部分上書きです: 書かれて いないものはデフォルトのままです。削ることが大事な理由はもう 1 つ あります: dump の完全コピーはすべてのデフォルトを今日の値で凍結して しまうので、将来の vig がデフォルトのバインドやレイアウトを改善しても、 「触っていないのにコピーされた」値が黙ってそれを上書きします。削った 設定はあなたの意見だけを、それ以外は何も語りません。

削り終えたファイルは、たいていこのくらい小さくなります:

theme "Solarized (dark)"
icons "none"
pages "git" "github" "worktrees"

vig は起動時にファイルを検証するので、編集 → vig 実行 → エラーを 読む → 直す、のループを素早く回せます。本物の設定に触らず実験するには 別ファイルを指せば安全です: vig --config ./try.kdl。

最低限の KDL

設定は KDL ドキュメントです。読み書きに必要な 考え方は 5 つだけです:

• ノードは名前 + 引数: theme "Solarized (dark)"。
• 引数はダブルクォートの文字列で、複数並べられます: pages "git" "files" "worktrees"。（例外が 1 つだけ裸の整数を 取ります: projects-board 2。）
• プロパティはノードに付く名前付きの値: split direction="horizontal"。
• ノードは { … } の子ブロックを持て、何段でもネストできます。
• コメント: 行末までの //、範囲の /* … */、そして KDL 特有の slashdash /- — 直後のノードを子ごと丸ごとコメントアウトします。

5 つ全部を 6 行で:

theme "Solarized (dark)"        // 文字列引数 1 つのノード
/- icons "none"                 // slashdash: このノードは無視される
page "git" {                    // 子ブロック
    layout {
        split direction="horizontal" {      // プロパティ
            place "file_tree" size="30"
            place "diff_view" size="min:20"
        }
    }
}

（この例は実際に読み込めます — 同時に Git ビューのレイアウトをファイル ツリーと diff だけに置き換える例にもなっています。詳しくは レイアウトのレシピ を参照。）

マージの仕組み

あなたのファイルはノード単位でデフォルトにマージされ、ノードによって マージのされ方が違います。3 つのクラスがあります:

その帰結を具体的に:

• トップレベルの値はオール・オア・ナッシング — それぞれが単一の 値なので自然な規則です。pages のリストはデフォルトのリストを 丸ごと置き換えます: 書かなかったページは移動ではなく無効化です。
• キーのブロックは追記式。 page "git" { pane "file_tree" { keys { "o" "ExpandOrOpen" } } } は バインドを 1 つ足すだけで、file_tree の他のキーはすべてデフォルト のままです。特別なアクション "None" に割り当てるとキーを削除 できます。キーバインドの微調整が、40 個のデフォルトの書き直しでは なく 2 行で済むのはこのためです。
• レイアウトは追記式ではありません。 ページに layout を書いたら、 それはそのページのレイアウト全体です — 木を書き直さずに 1 つの ペインのサイズだけ動かす方法はありません。vig config dump の該当 ブロックをコピーして編集してください。tabs（ペインの巡回順）と bind（選択→詳細の接続）も同じで、ユーザーの bind を 1 行でも 書くと、そのページのデフォルトの bind 行はすべて置き換わります。

ページ名とペイン名は固定です — 並べ替え・リサイズ・リバインドは できますが、新しく発明することはできません。有効なページは git、 github、files、docker、procs、worktrees、projects で、 各ページのペインは vig config dump で確認できます。

リポジトリローカルの .vig.kdl もまったく同じ規則で、1 段あとに マージされます: 組み込み → ユーザー → リポジトリローカル、で リポジトリローカルが勝ちます。

エラーは大声で

ユーザー設定に問題があれば — 構文エラー、未知のノード、存在しない テーマ名、同じペインを 2 回置く・何も置かないレイアウト — vig は 起動せず、ファイル名（構文エラーなら行:桁も）を含むメッセージを 出します。設定ファイルがあるのに黙ってデフォルトへフォールバック することはないので、タイポが見過ごされることはありません:

theem "Solarized (dark)"
// → invalid config file ~/.config/vig/config.kdl:
//   unknown top-level block "theem" (expected `theme`, `icons`, ...)

唯一の例外はリポジトリローカルレイヤで、 前述の通り中断せず劣化します。

設定レシピ

実際によく変える設定の実例集です。各レシピは、困りごと + ~/.config/vig/config.kdl にそのまま貼れる完全な設定 + 画面がどう 変わるか、で構成されています。このページの kdl ブロックはすべて、 vig のテストスイートがユーザー設定とまったく同じ経路で読み込んで 検証しています — 壊れた例は出荷されません。

設定の基本 をまだ読んでいない場合の 1 行 まとめ: あなたのファイルは デフォルト の部分上書きで、キーのブロックはキー単位でマージ、レイアウトは丸ごと 置換です。

見た目

シンタックスハイライトのテーマを変える

diff の配色が端末に合わない。

vig config themes    # 選択肢を一覧。`*` が現在有効なもの

theme "Solarized (dark)"

次回起動から diff ビュー（Git と Worktrees）と Files のプレビューの 配色が変わります。テーマから使われるのは前景色だけなので、ライト系 テーマ（InspiredGitHub、Solarized (light)、base16-ocean.light）が 読みやすいのは主にライト背景の端末です。

ファイルアイコンを消す

Files ビューのアイコンが豆腐 / 文字化けになる。

あれは Nerd Font のグリフで、端末のフォントに入っていないのが原因 です。Nerd Font を入れるか、こうします:

icons "none"

Files ビューはプレーンなファイル名だけを表示します。

画像プレビューを抑える

SSH 越し / この端末だと画像プレビューが崩れる。

デフォルト（"auto"）では Files ビューが端末のグラフィック プロトコル（Kitty、iTerm2、Sixel）を検出し、なければユニコードの ハーフブロックにフォールバックします。上書きは 2 通り:

image-preview "halfblocks"   // 検出せず、常にハーフブロック

image-preview "none"         // 画像は一切描画しない

キーバインド

キーを足す・付け替える

ファイルマネージャと同じく、Git のファイルツリーでも o で開きたい。

page "git" {
    pane "file_tree" {
        keys {
            "o" "ExpandOrOpen"
        }
    }
}

キーはキー単位でマージされます: これはバインドを 1 つ足す（o に 既存のバインドがあれば上書きする）だけで、file_tree の他のキーは デフォルトのままです。ヘルプオーバーレイ（?）は有効な設定から生成 されるので、自動で反映されます。

キーは文字列で書きます: 1 文字（"j"、"G"、"/"）、名前付きキー （"Enter"、"Esc"、"Tab"、"BackTab"、"Space"、"Backspace"、 "Delete"、"Up"、"Down"、"Left"、"Right"、"Home"、"End"、 "PageUp"、"PageDown"）、または Ctrl+ の組み合わせ （"Ctrl+d"）。アクション名はペインごとに決まっています — vig config dump が全ペインのデフォルトを示し、 設定リファレンス がすべてを一覧する予定です。

グローバルなキーは app ブロックに書き、全ページで効きます:

app {
    "q" "Quit"            // ペインからでなく、どこからでも終了
    "Ctrl+g" "page:git"   // Git ビューへジャンプ
}

app のアクションは "Quit" と "page:<name>" です — ページ切り替え は名前で指すので、タブを並べ替えてもバインドはそのまま効きます。

バインドを消す

Space でディレクトリが開閉するのが誤爆する。

予約アクション "None" に割り当てます:

page "git" {
    pane "file_tree" {
        keys {
            "Space" "None"
        }
    }
}

そのペインでキーは何もしなくなり、ヘルプオーバーレイからも消えます。 preset 由来のキーにも効きます — ペインで "n" "None" と書けば、 そのペインの検索ネクストが消えます。

preset とは何か

vig config dump を見ると、ほぼすべてのペインの keys に preset "nav" と preset "search" があります。preset は標準バインドの 名前付きセットで、その場に展開されます:

規則は 2 つです:

• 明示が preset に勝つ。 preset が先に展開され、同じペイン内の 明示バインド — デフォルト設定のものでもあなたのものでも — が同じ キーについて勝ちます。上のレシピで preset "search" 由来の n を "None" で消せたのはこのためです。
• preset は置換されず、常に追加される。 キーのマージ時、あなたの preset 行は既存の行に並んで追加されます。もし search を持たない ペインがあれば、preset "search" の 1 行で検索キー 3 つを足せます。

タブ

タブを絞る・並べ替える

Git と Files と Worktrees しか使わない。

pages "git" "files" "worktrees"

ヘッダは 1:Git 2:Files 3:Worktrees になります。pages はデフォルトの リストを丸ごと置き換えます: リスト内の位置がタブ番号で、書かなかった ページは完全に無効です — 起動されず、タブもバックグラウンドの ポーリングもありません。

並べ替えも同じ書き方です:

pages "github" "git" "files" "docker" "procs" "worktrees" "projects"

数字キーはページに名前で結び付いたバインドです — どちらの設定でも、 組み込みの page:git バインドは新しい位置の Git ビューにちゃんと 届きます。無効化したページの組み込みキーは黙って外されますが、 あなた自身の app ブロックから pages に無いページへのバインドは エラーです。決して動きようがないからです:

pages "git" "files"
app {
    "d" "page:docker"    // → エラー: page "docker" is not listed in `pages`
}

レイアウト

レイアウトの木を読む

各ページの配置は、layout { } の中の 3 種類の要素からなる木です:

• split direction="horizontal" { … } は子を左右に並べ、 direction="vertical" は上下に積みます。各子は size= を取れます。
• place "<pane>" はペインを表示します。
• slot "<name>" … { … } は時によって別のペインを表示する 1 つの 領域です — 後述。

サイズは "30"（ちょうど 30 セル）、"40%"、"min:20"（最低 20 セル、残りを取る）。省略は min:0 です。デフォルトの Git ビューの レイアウトに注釈を付けると:

page "git" {
    layout {
        split direction="vertical" {                    // 2 段
            split direction="horizontal" size="40%" {   // 上段: 高さ40%、3 列
                place "file_tree" size="30"             //   幅ちょうど 30 セル
                place "branch_list" size="35%"          //   幅の 35%
                place "reflog" size="min:20"            //   残り全部、最低 20
            }
            slot "main" size="min:3" then="git_log" default="diff_view" {
                triggers "branch_list" "reflog" "git_log"
            }                                           // 下段: log か diff
        }
    }
}

このブロック自体が有効な設定です — ページのデフォルトレイアウトを そのまま書き直しても何も変わりません。そしてそれがすべてのレイアウト 編集の始め方です: vig config dump からそのページの layout を コピーして、調整する。あなたが書いた layout はページの レイアウト全体を置き換えます。部分マージはありません。

制約は 2 つで、どちらも起動時に検査されます: レイアウトは各ペインを 高々 1 回しか置けず、最低 1 つのペインを置かなければなりません。

ペインを広げる

Files のプレビューが狭い。

dump から Files のレイアウトをコピーして数字をずらします:

page "files" {
    layout {
        split direction="horizontal" {
            place "parent_dir" size="15%"   // デフォルト: 20%
            place "dir_list" size="25%"     // デフォルト: 30%
            place "preview" size="min:20"   // 空いた分を取る
        }
    }
}

プレビューの幅が約 50% から約 60% になります。

ペインを置かない

reflog は見ない。その場所をブランチにあげたい。

レイアウトに書かなかったペインは非アクティブになります: 領域を 持たず、Tab 巡回もフォーカスもスキップし、そのペインを指す bind 行は無視されます。tabs やキーを直す必要はありません — 勝手に 適応します。

page "git" {
    layout {
        split direction="vertical" {
            split direction="horizontal" size="40%" {
                place "file_tree" size="30"
                place "branch_list" size="min:20"     // reflog の場所はあなたのもの
            }
            slot "main" size="min:3" then="git_log" default="diff_view" {
                triggers "branch_list" "git_log"
            }
        }
    }
}

Projects のリストペインを復活させる

p で巡回ではなく、リンクされたボードを一覧で見たい。

Projects ページには意図的に置かれていないペインがあります: リポジトリにリンクされたボードの一覧 projects です。デフォルトの レイアウトはボードとアイテム詳細だけを表示します（ボードは p / P で巡回）。リストを置けば生き返ります — 組み込みの bind select="projects" detail="board" も、置いた瞬間から自動で 効き始めます:

page "projects" {
    layout {
        split direction="horizontal" {
            place "projects" size="22%"
            split direction="vertical" size="min:30" {
                place "board" size="60%"
                place "detail" size="min:5"
            }
        }
    }
    tabs "projects" "board" "detail"
}

リストでプロジェクトを選ぶと右にそのボードが読み込まれます。Enter で中へ、ボードから Esc でリストへ戻ります。（このレイアウトは assets/default.kdl にコメントとして載っているものと同じです。）

slot: 1 つの領域に複数のペイン

slot、when、then とは？

slot は、フォーカスの位置によって別のペインを表示するレイアウト 領域です。実例は GitHub ビューの詳細領域 — 下部の 1 領域に、 3 つの候補が入ります:

page "github" {
    layout {
        split direction="vertical" {
            split direction="horizontal" size="40%" {
                place "issue_list" size="33%"
                place "pr_list" size="34%"
                place "run_list" size="33%"
            }
            slot "detail" size="min:3" default="issue_detail" {
                when "pr_list" "pr_detail" then="pr_detail"
                when "run_list" "run_detail" then="run_detail"
            }
        }
    }
}

slot の読み方: 各 when はトリガーになるペインを列挙し、表示する ペインを then= で指名します。フォーカス中のペインを含む最初の when が勝ち、どれにも当たらなければ default= が表示されます。 つまり: PR 列（あるいは PR 詳細の中 — pr_detail 自身がトリガーに 入っているのはそのためです）にフォーカス → 領域は pr_detail。 実行列にフォーカス → run_detail。それ以外はどこでも issue_detail。各 when が自分の then ペインを自分のトリガーに 含めている点に注目してください — そうしないと、詳細の中へ フォーカスを移した瞬間に領域が別のペインへ切り替わってしまいます。

単一ケースの省略形 — slot 自体に then= を付け、子に triggers を 書く形 — もあり、Git ビューが使っています: branch_list・reflog・ git_log のどれかにフォーカスがある間は git_log、それ以外は diff_view（上の レイアウトの木を読む を 参照）。両方の形は 1 つの slot で併用でき、slot の名前（"detail"、 "main"）はただのラベルです。

slot を自分のものにする変種 — PR で暮らしているなら、pr_detail を 定位置にします:

page "github" {
    layout {
        split direction="vertical" {
            split direction="horizontal" size="40%" {
                place "issue_list" size="33%"
                place "pr_list" size="34%"
                place "run_list" size="33%"
            }
            slot "detail" size="min:3" default="pr_detail" {
                when "issue_list" "issue_detail" then="issue_detail"
                when "run_list" "run_detail" then="run_detail"
            }
        }
    }
}

ペイン配置の数え方として、slot は表示しうる各ペインを 1 回ずつ 「置いた」ことになります — なので他の place が pr_detail を重ねて 置くことはできず、「高々 1 回」規則は木全体に効きます。

Projects

ボードを 1 つに固定する

リポジトリに 5 つボードがリンクされているが、見るのは 1 つだけ。

タイトルで（リンクされたプロジェクトに対して大文字小文字を無視して 照合）:

projects-board "Roadmap"

またはプロジェクト番号で:

projects-board 2

Projects ページはそのボードだけを表示します。p / P は巡回しなく なり（押すとステータスバーに board pinned by config (projects-board) と出ます）、ヘッダから (i/n) カウンタが消えます。一致するプロジェクトが無ければ、ボード ペインが指定名を挙げてそう伝えます。番号の形は、設定の中で唯一 クォート無しの整数を書く場所です。

リポジトリごとの設定

1 つのリポジトリのための .vig.kdl

このリポジトリだけタブ構成を変えて、ボードも固定したい。

worktree のルートに .vig.kdl を置きます（そして gitignore して ください — 個人用です）:

// .vig.kdl — このリポジトリだけ
pages "git" "github" "projects"
projects-board "Roadmap"
github-poll-interval "10s"

ユーザー設定の上に同じ規則でマージされます（組み込み → ユーザー → リポジトリローカル、でリポジトリローカルが勝ち）。そのリポジトリで だけ真になることはここに書きます: 固定するボード、絞ったタブ、忙しさ に合わせたポーリング間隔、そのプロジェクトの端末プロファイルに合う テーマ。あなたに付いて回る好み — キーバインドやアイコン — は ユーザー設定へ。

ここでのエラーが vig を止めることはありません: 壊れた .vig.kdl は ステータスバーで報告され（ignored .vig.kdl: …）、vig は組み込み + ユーザーで起動します。

信頼ダイアログ

.vig.kdl が git に追跡されている場合、それはリポジトリと一緒に やって来たものなので、vig は読み込む前に確認します — 設定はどの ページ・どのキーバインドが存在するかを決めるものなので、黙って読み 込みはしません。ダイアログは UI が始まる前に表示されます:

• y — 読み込み、この内容のファイルについて回答を記憶
• n — 無視して、記憶
• v — まずファイルを見てから決める
• Esc — 今回だけ無視。次回の起動でまた確認

記憶された決定は worktree と内容ハッシュがキーなので、ファイルが 変わると（pull の後など）もう一度確認されます。CLI から管理できます:

vig config trust                     # 記憶済みの決定を一覧
vig config trust --forget ~/src/foo  # その worktree で次回また確認させる

自分の未追跡の .vig.kdl でダイアログが出ることはありません — ステータスバーに loaded .vig.kdl と出て、黙って読み込まれます。

リポジトリレイヤを切る

リポジトリに自分の vig を触らせたくない。

ユーザー設定に:

repo-config "off"

.vig.kdl は一切読み込まれず、ダイアログも出ません。有効なのは ユーザー設定の値だけです — .vig.kdl は repo-config をそもそも 書けないので、リポジトリ側からスイッチを戻すことはできません。

ポーリングと履歴

GitHub のポーリングを落ち着かせる（or 速める）

実行中のジョブを眺めている間、vig のポーリングが多すぎる。

github-poll-interval "10s"

これは GitHub ビューが何かが動いている間にポーリングする間隔です — 実行中の Workflow Runs 列、ウォッチモード（w）の PR チェック、 実行中ジョブのログ。デフォルト "5s"、最小 "2s"（設定で API クォータを溶かせないようにするため）。別のビューを表示している間、 ポーリングは完全に止まります。レート制限への対処はこの設定とは別に 組み込まれています: GitHub がリクエストを拒否すると vig は指数 バックオフし、リセット時刻をステータスバーに表示します。

Procs のサンプリング間隔と履歴の深さ

グラフを滑らかにして、履歴も長く取りたい。

procs-refresh-interval "1s"
procs-history "600"

procs-refresh-interval は Procs ビューが表示中にプロセスとポートを 読み直す間隔です（デフォルト "2s"、最小 "250ms"、"1.5s" / "500ms" のような値も可。他のビューではサンプリングは止まります）。

procs-history は履歴グラフ — システムの CPU / メモリのチャートと プロセスごとのスパークライン — が保持するサンプル数です。1 回の リフレッシュにつき 1 サンプルなので、2 つの設定は掛け算になります: 上の例は 600 × 1s = 10 分の履歴です。デフォルト "120"（"2s" で 4 分）、許容範囲は "10" 〜 "10000"。

設定リファレンス

vig の KDL 設定の完全なリファレンスです: 設定ファイルが受け付けるすべての ノードを、書式・デフォルト・マージ規則・エラーとともに記載します。 引きやすさを優先して、トップレベルノードごとに 1 セクション、続いて page ブロックの要素、最後に全ページのペインとアクション、の構成です。

設定にはじめて触れる場合は、設定の基本 （場所・レイヤ・マージモデル）と 設定レシピ （実例集）から読んでください。この章はそれらを前提に、網羅性を目指します。

この章の表記:

• 書式 — ノードの書き方。特記がない限り値はクォートされた文字列です。 唯一の例外は projects-board 2（裸の整数）。
• デフォルト — 組み込みの値。 assets/default.kdl （vig config dump の出力）と同じです。
• マージ — あなたの設定がそのノードを書いたときに起きること。
• そのまま読み込める完全な例は kdl ブロックで示します — vig のテスト スイートが、ユーザー設定とまったく同じ経路で各例を読み込んで検証して います。断片やエラーの実演は ignore 指定で示し、出るエラーを注釈します。

トップレベル一覧

トップレベルノードをすべて書いた設定（各値はデフォルトなので、これは 読み込めて、かつ何も変えません）:

theme "base16-eighties.dark"
icons "nerd"
image-preview "auto"
markdown-preview "render"
procs-refresh-interval "2s"
procs-history "120"
github-poll-interval "5s"
github-auto-refresh "on"
projects-poll-interval "30s"
pages "git" "github" "files" "docker" "procs" "worktrees" "projects"
repo-config "on"
app {
    "Ctrl+c" "Quit"
}

これ以外のトップレベルノードはエラーです:

colors "red"
// → unknown top-level block "colors" (expected `theme`, `icons`,
//   `image-preview`, `markdown-preview`, `procs-refresh-interval`,
//   `procs-history`, `github-poll-interval`, `github-auto-refresh`,
//   `projects-poll-interval`, `projects-board`, `pages`, `repo-config`,
//   `app`, or `page`)

トップレベルノード

theme

diff ビュー（Git と Worktrees）と Files のプレビューで使う シンタックスハイライトのテーマ。

• 書式 — theme "<name>"
• デフォルト — "base16-eighties.dark"
• マージ — デフォルトを置換。

使えるのは syntect 同梱のテーマ だけです。vig config themes で一覧できます（* が現在有効なもの）: InspiredGitHub、Solarized (dark)、Solarized (light)、 base16-eighties.dark、base16-mocha.dark、base16-ocean.dark、 base16-ocean.light。テーマから使われるのは前景色だけなので、ライト系 テーマが読みやすいのは主にライト背景の端末です。

theme "Solarized (dark)"

theme "Solarised (dark)"
// → unknown theme "Solarised (dark)"; available: InspiredGitHub, ...

icons

Files ビューのファイル種別アイコン。

• 書式 — icons "<mode>" — "nerd" または "none"
• デフォルト — "nerd"
• マージ — デフォルトを置換。

"nerd" はファイル種別ごとの Nerd Font グリフを表示し、端末に Nerd Font が必要です。"none" は プレーンな名前だけを表示します （レシピ）。

icons "none"

image-preview

Files ビューの画像プレビュー（PNG / JPEG / GIF / WebP）の描画方法。

• 書式 — image-preview "<mode>" — "auto"・"halfblocks"・"none"
• デフォルト — "auto"
• マージ — デフォルトを置換。

"auto" は端末のグラフィックプロトコル（Kitty、iTerm2、Sixel）を検出し、 なければユニコードのハーフブロックへフォールバックします。 "halfblocks" は検出をスキップして常にハーフブロック、"none" は画像を 一切描画しません（プレビューにはメタデータ行だけが出ます）。

image-preview "halfblocks"

markdown-preview

Files ビューが Markdown ファイル（.md / .markdown）をどうプレビューするか。

• 書式 — markdown-preview "<mode>" — "render" か "raw"
• デフォルト — "render"
• マージ — デフォルトを置換。

"render" はレンダリング表示（見出し・強調・リスト・コード・ペイン幅に 合わせた GFM テーブル）、"raw" はシンタックスハイライトされた生テキスト です。どちらの場合も m でセッション内の切り替えができます。

markdown-preview "raw"

procs-refresh-interval

Procs ビューが表示中に、プロセス一覧と LISTEN ポートを読み直す間隔。 他のビューを表示している間、サンプリングは止まります。

• 書式 — procs-refresh-interval "<duration>" — s か ms 付きの 数値（"2s"、"1.5s"、"500ms"）をクォートして書く。最小 "250ms"
• デフォルト — "2s"
• マージ — デフォルトを置換。

procs-refresh-interval "5s"

procs-refresh-interval "100ms"
// → bad procs-refresh-interval "100ms"; expected a duration such as
//   "2s" or "500ms" (at least 250ms)

procs-history

Procs ビューの履歴グラフ — graphs ペインのシステム CPU / メモリの エリアチャートと、詳細ペインのプロセスごとの履歴チャート — が保持する サンプル数。1 回のリフレッシュにつき 1 サンプルなので、 procs-refresh-interval との掛け算が 履歴の長さになります。

• 書式 — procs-history "<n>" — "10" 〜 "10000" の数値を クォートして書く
• デフォルト — "120"（デフォルトの "2s" で 4 分）
• マージ — デフォルトを置換。

procs-history "300"

procs-history "5"
// → bad procs-history "5"; expected a sample count between 10 and 10000

github-poll-interval

GitHub ページが何かが動いている間にポーリングする間隔 — queued / in progress の実行がある Workflow Runs 列、ウォッチモード（w）の PR チェック、実行中ジョブのログ。別のページを表示している間、 ポーリングは止まります。issue / PR 一覧の変更チェック（304 応答なら API ポイントを消費しない条件付きリクエスト 1 回。変化したときだけ一覧を 再取得）も同じ間隔です。

• 書式 — github-poll-interval "<duration>" — s か ms 付きの 数値をクォートして書く。最小 "2s"（設定で API クォータを溶かせない ようにするため）
• デフォルト — "5s"
• マージ — デフォルトを置換。

レート制限への対処はこの設定の上に組み込まれています: GitHub が リクエストをレート制限で拒否すると、ページはすべてのポーリングを指数 バックオフ（30 秒、60 秒、…最大 10 分）で停止し、ステータスバーに ⚠ GitHub rate limited (resets in Nm) を表示します。リセット時刻は 1 回の gh api rate_limit 呼び出しから取得します（このエンドポイント 自体はレート制限されません）。r で即時リトライ、成功すれば バックオフは解除されます。詳しくは トラブルシューティング。

github-poll-interval "10s"

projects-poll-interval

Projects ページを表示している間、表示中のボードに変更があったかを GitHub に尋ねる間隔。プローブはプロジェクトの updatedAt だけを読み （GraphQL 1 ポイント。アイテムの移動やフィールド編集で動きます）、 動いたときだけボードを再取得します。他のページを表示中は止まります。

• 書式 — projects-poll-interval "<duration>" — s か ms 付きの 数値をクォートして書く。最小 "5s"（プローブ 1 回が 1 ポイントのため）
• デフォルト — "30s"（ページを開いたままで 120 ポイント/時、 アイドル時は 20）
• マージ — デフォルトを置換。

プローブは github-auto-refresh とアイドル / 残量による間隔延長に従い、レート制限された応答は GitHub ページと同じ バックオフで休みます。

projects-poll-interval "60s"

projects-poll-interval "2s"
// → bad projects-poll-interval "2s"; expected a duration such as "30s" or "60s" (at least 5000ms)

github-auto-refresh

vig が GitHub のデータを自動で更新するか: GitHub ページのポーリング （実行、watch モード、実行中ジョブのログ、issue / PR 一覧の変更チェック） と、Projects ページに戻ったときの stale 再取得およびボードの変更プローブ。

• 書式 — github-auto-refresh "<mode>" — "on" か "off"
• デフォルト — "on"
• マージ — デフォルトを置換。

"off" は手動の r だけを残します — 共有トークン、CI 端末、vig を多数 起動するマシン向け。on でも自動更新は自分で控えめになります: キー入力が 10 分無いと全間隔が ×6（ヘッダに idle）、GraphQL クォータ（毎時）の残り 20% 未満で ×2、5% 未満で停止（refresh stopped）。残り 1,500 ポイント 未満ではヘッダに ⚠ api N left も出ます。

github-auto-refresh "off"

projects-board

Projects ページを 1 つのボードに固定します。引数は 1 つで、ボードの タイトル（文字列。リポジトリにリンクされたプロジェクトに対して大文字 小文字を無視して照合）か、プロジェクト番号 — 設定の中で唯一の裸の 整数 — です:

• 書式 — projects-board "<title>" または projects-board <number>
• デフォルト — なし: リンク済みプロジェクトすべてが対象で、 p / P で巡回
• マージ — デフォルトを置換。

projects-board "Roadmap"

projects-board 2

設定するとページはそのボードだけを表示します: p / P は巡回しなく なり（押すとステータスバーに board pinned by config (projects-board) と出ます）、ヘッダから (i/n) カウンタが消えます。一致するプロジェクト が無ければ、ボードペインが指定名を挙げてそう伝えます。

projects-board "Roadmap" 2
// → bad projects-board (one argument required); expected exactly one
//   argument, a board title (`projects-board "Roadmap"`) or a project
//   number (`projects-board 2`)

pages

有効にするページを、タブ順で並べます。リスト内の位置がページの スロット — ヘッダに出る番号（1:Git、2:GitHub、…）であり、Tab 巡回の到達位置です。

• 書式 — pages "<name>" "<name>" ... — 名前は git、github、 files、docker、procs、worktrees、projects から。最低 1 つ、 重複なし
• デフォルト — この順で全 7 ページ
• マージ — デフォルトのリストを丸ごと置換。

書かなかったページは無効です — 起動されず、タブもバックグラウンドの ポーリングもありません:

pages "git" "files" "worktrees"

は 1:Git 2:Files 3:Worktrees の 3 タブ構成になります。

キーはスロットではなくページに名前で結び付いたバインドです: app { "<key>" "page:<name>" } はページがどこにいても名前で指すので、 並べ替え後も組み込みの 1 … 7 は同じページに切り替わります。無効化 したページの組み込みキーは外されますが、あなたの app { } ブロック から pages に無いページへのバインドはエラーです（app 参照）。

pages "git" "filez"
// → pages: unknown page "filez"; expected one of: git, github, files,
//   docker, procs, worktrees, projects

pages "git" "git"
// → pages: page "git" listed twice

pages
// → pages must list at least one page

v0.7.0 の actions ページは v0.8.0 で github ページ（Workflow Runs 列）に統合されました。まだ書いてある設定は、その旨のメッセージとともに 拒否されます:

pages "git" "actions"
// → pages: page "actions" was folded into the "github" page (v0.8.0);
//   remove it from pages / app bindings

repo-config

リポジトリローカルの .vig.kdl レイヤ （設定の基本）を そもそも読むかどうか。

• 書式 — repo-config "on" または repo-config "off"
• デフォルト — "on"
• マージ — デフォルトを置換。有効なのはユーザー設定の値だけ。

"off" にすると .vig.kdl は一切読み込まれず、信頼ダイアログも出ません。 このスイッチはリポジトリレイヤをマージする前に読まれるので、.vig.kdl が自分自身を on/off することはできません — .vig.kdl に repo-config を書くこと自体が（"on" でも）拒否されます: repo-config can only be set in the user config, not in .vig.kdl。

repo-config "off"

app

全ページで効くグローバルキーバインド。

• 書式 — app { "<key>" "<action>" ... }
• デフォルト — "Ctrl+c" "Quit" と、"1" … "7" の 7 ページへの 名前バインド
• マージ — キー単位でマージ: 書いたキーだけがそのキーのデフォルトを 置き換え、書かなかったキーはそのまま。

app {
    "q" "Quit"            // ペインからでなく、どこからでも終了
    "Ctrl+g" "page:git"   // Git ビューへジャンプ
    "7" "None"            // 組み込みの Projects 切替を解除
}

存在はするが有効化されていないページへの、あなた自身の page: バインド はエラーです（無効化したページの組み込みバインドは黙って外されます）:

pages "git" "files"
app {
    "d" "page:docker"
    // → app block: "d" "page:docker": page "docker" is not listed in
    //   `pages` (git, files)
}

キー

キーは文字列で、3 つの形のどれかで書きます:

• 1 文字 — "j"、"G"、"/"、"]"。大文字小文字は区別されます: "g" と "G" は別のキーです。
• 名前付きキー — "Enter"、"Esc"、"Tab"、"BackTab"、 "Space"、"Backspace"、"Delete"、"Up"、"Down"、"Left"、 "Right"、"Home"、"End"、"PageUp"、"PageDown"。別名も いくつか使えます: Enter の "Return" / "CR"、Esc の "Escape"、 BackTab の "S-Tab"、Backspace の "BS"、Delete の "Del"。
• Ctrl+ の組み合わせ — "Ctrl+d"、"Ctrl+u"、"Ctrl+c"。 修飾キーは Ctrl のみ対応です。Alt+ やファンクションキーは ありません。

予約アクション "None" に割り当てるとキーは削除されます — app { } でも、どのペインの keys { } でも同じです。

preset

preset は標準バインドの名前付きセットで、ペインの keys { } ブロック内 にその場で展開されます。2 つあります:

Nav.* と Search.* のアクションは、デフォルトに該当 preset を持つ ペインでなら個別にもバインドできます。規則は 2 つ （背景）: preset が先に展開され、 同じペイン内の明示バインドが同じキーについて勝つこと。そしてキーの マージ時、preset 行は置換されず常に追加されることです。

page "git" {
    pane "diff_view" {
        keys {
            "J" "Nav.HalfPageDown"   // preset のアクションを明示バインド
            "n" "None"               // preset 由来のバインドを削除
        }
    }
}

page ブロック

page "<name>" {
    layout { <split | place | slot> }     // 丸ごと置換
    tabs "<pane>" "<pane>" ...            // 丸ごと置換
    bind select="<pane>" detail="<pane>"  // bind 行はまとめて置換
    pane "<name>" { keys { ... } }        // keys はキー単位マージ
}

ページ名とペイン名は固定です — 並べ替え・リサイズ・リバインドはできます が、新しく作ることはできません。どのブロックも省略可能で、page ブロックは書いたものだけを変えます。

layout

ルート要素はちょうど 1 つ。3 種類の要素を何段でもネストできます:

• split direction="horizontal" { <children> } — 子を左右に並べる。 direction="vertical" は上下に積む。各子は size="..." を取れる。
• place "<pane>" — ペインを表示する。
• slot "<name>" ... — フォーカスに応じて別のペインを表示する 1 つの 領域。後述の slot 参照。

サイズ — "30"（ちょうど 30 セル）、"40%"（割合）、"min:20" （最低 20 セル、残りを取る）。省略は "min:0"。

マージ — layout を書くと、そのページのレイアウト全体を置き換え ます。部分マージはありません。vig config dump の該当ブロックから 始めて編集してください（レシピ）。

規則（どちらも起動時に検査されます）:

• 各ペインを置けるのは高々 1 回 — place 行と、slot については その slot が表示しうる各ペインを 1 回と数えます。
• 最低 1 つのペインを置くこと。
• レイアウトに書かなかったペインは非アクティブです: 領域を持たず、 Tab 巡回とフォーカスにスキップされ、そのペインを指す bind 行は 無視されます。組み込みの Projects ページ自体がこの形です — ページ projects 参照。

page "git" {
    layout {
        split direction="vertical" {
            place "diff_view"
            place "diff_view"
        }
    }
}
// → page "git": layout places pane "diff_view" more than once

page "git" { layout { } }
// → page "git" layout is empty

slot

slot は、時によって別のペインを表示するレイアウト領域です: 現在 フォーカス中のペインにマッチするケースが勝ちます。形は 2 つあり、 1 つの slot で併用できます:

• 単一ケース — slot 自体の then= と、子の triggers:

  slot "main" size="min:3" then="git_log" default="diff_view" {
      triggers "branch_list" "reflog" "git_log"
  }
  

  branch_list・reflog・git_log のどれかにフォーカスがある間は git_log、それ以外は diff_view（Git ビューの下段）。

• 複数ケース — when の子。それぞれトリガーになるペインを列挙し、 表示するペインを指名します。フォーカス中のペインを含む最初の when が勝ち、どれにも当たらなければ default=:

  slot "detail" size="min:3" default="issue_detail" {
      when "pr_list" "pr_detail" then="pr_detail"
      when "run_list" "run_detail" then="run_detail"
  }
  

  GitHub ビューの詳細領域です。各 when が自分の then ペインを自分の トリガーに含めている点に注意 — こうしないと、詳細の中へフォーカスを 移した瞬間に領域が切り替わってしまいます。

slot の名前（"main"、"detail"）はただのラベルです。配置の 「高々 1 回」規則では、slot は表示しうる各ペインを 1 回ずつ置いたことに なります。読み解きは slot のレシピ に あります。

tabs

Tab / BackTab で巡回するペインを順に並べます。

• 書式 — tabs "<pane>" "<pane>" ...
• マージ — 書けば丸ごと置換。

レイアウトが置いていないペインはスキップされるので、デフォルトの tabs はあなたのレイアウトの下でもそのまま有効です — tabs を書き直す のは巡回順を変えたいときと、デフォルトの順に無いペインを入れたいとき だけです。

bind

選択ペインがどの詳細ペインを駆動するか — 例えば file_tree でファイル を選ぶと diff_view に読み込まれる、の接続です。

• 書式 — bind select="<pane>" detail="<pane>"。複数書けます
• マージ — ユーザーの bind を 1 行でも書くと、そのページの デフォルトの bind 行はすべて置き換わります。

置かれていないペインを指す bind は無視されます — そしてレイアウトが そのペインを置いた瞬間から自動で効き始めます（Projects ページのリスト ペインが生き返る仕組みです。ページ projects 参照）。

pane と keys

page "git" {
    pane "file_tree" {
        keys {
            "o" "ExpandOrOpen"   // バインドを追加・上書き
            "Space" "None"       // バインドを削除
        }
    }
}

• マージ — キー単位で、そのペインのデフォルトキー（展開済み preset を含む）の上にマージ。preset 行は追加されます。

各ペインが受け付けるアクションは、下のページ別一覧の通りです。view という名前のペインは特別で、実体のあるペインではなくページ全体のキー （終了・ヘルプ・リフレッシュ・タブ / ペイン巡回）の置き場です。 レイアウトに置くことはできません。ヘルプオーバーレイ（?）はマージ後の キーマップから生成されるので、常にあなたのバインドを反映します。

ページとペイン

ページごとに: ペイン、各ペインのバインド可能なアクション、各アクションの 組み込みキー。Nav.* と Search.*（preset 参照）は、 デフォルトに該当 preset を持つすべてのペインで追加で使えます — 下の表 では nav / search preset を持つペインに印を付けています。Esc は すべての操作可能なペインのアクションです（ペインを抜ける / 検索を クリア）。デフォルトのバインド全体を KDL の形で見るには vig config dump を実行してください。

ページ git

ペイン: file_tree、branch_list、git_log、reflog、diff_view — デフォルトレイアウトはすべて配置します（git_log と diff_view は main slot を共有）。

ページ github

ペイン: issue_list、pr_list、run_list（3 つの列）と issue_detail、pr_detail、run_detail（detail slot を共有）。

run_detail では Nav.JumpBottom（G）が、実行中ジョブのログの follow 再開も兼ねます。

ページ files

ペイン: parent_dir、dir_list、preview — すべて配置。parent_dir は表示専用です: キーの無い pane ブロックを持ち、アクションを受け 付けません。

ページ docker

ペイン: containers、images、detail、logs — すべて配置。

logs では Nav.JumpBottom（G）が tail の follow 再開も兼ねます。

ページ procs

ペイン: processes、ports、detail、graphs — すべて配置。

ページ worktrees

ペイン: worktrees、stashes、preview — すべて配置。

ページ projects

ペイン: projects、board、detail。組み込みレイアウトが置くのは board と detail だけで、projects 一覧ペインは定義されているのに 置かれていません — 代わりに p / P がリンク済みプロジェクトを 巡回し、トップレベルの projects-board でボードを 固定するとそれも止まります。一覧を戻すには置くだけです — 組み込みの bind select="projects" detail="board" は置いた瞬間から自動で効きます （レシピ）:

page "projects" {
    layout {
        split direction="horizontal" {
            place "projects" size="22%"
            split direction="vertical" size="min:30" {
                place "board" size="60%"
                place "detail" size="min:5"
            }
        }
    }
    tabs "projects" "board" "detail"
}

ボードでの Esc は、プロジェクト一覧が置かれていればそこへ戻ります。

起動時エラー

ユーザー設定に問題があると、vig は起動せず、ファイル名を含むメッセージを 出します — 設定ファイルがあるのに黙ってデフォルトへフォールバックする ことはありません。カテゴリ:

• 構文エラー — ファイル:行:桁 とパーサのメッセージ付き。例えば page "git" { を閉じ忘れると:

  Error: failed to parse config file /home/you/.config/vig/config.kdl
    /home/you/.config/vig/config.kdl:1:12: No closing '}' for child block
  

• 未知の名前 — トップレベルブロック、ページ、ペイン、テーマ、 icons / image-preview のモード、preset 名、キー、アクションはすべて 検証され、エラーには期待される候補が並びます。タイポは見過ごされ ません。

• 構造エラー — 同じペインを 2 回置く・何も置かないレイアウト、 then= / when ケースの無い slot、select= / detail= の無い bind。

• 値エラー — 最小値未満・単位無しの間隔、範囲外の procs-history、 引数の形がおかしい projects-board、"on" / "off" 以外の repo-config。

• 相互参照 — pages に無いページ、または廃止された actions ページへの、あなたの app バインド。

唯一の例外はリポジトリローカルの .vig.kdl レイヤで、中断ではなく劣化 します（ステータスバーに ignored .vig.kdl: <理由>）。実際のメッセージ の読み方は トラブルシューティング を参照してください。

トラブルシューティング / FAQ

実際に踏みがちな問題を、vig が表示するそのままのメッセージと、それぞれの 抜け道つきでまとめます。設定変更で直るものは 設定リファレンス にリンクしています。

vig が起動しない（設定エラー）

vig は起動時にユーザー設定を検証し、フェイルファストです: 構文 エラー・未知のノード・不正な値など、どんな問題でもファイル名を含む メッセージとともに vig は止まります。黙ってデフォルトにフォールバック することはありません。実物:

Error: invalid config file /home/you/.config/vig/config.kdl

Caused by:
    unknown top-level block "theem" (expected `theme`, `icons`, `image-preview`,
    `procs-refresh-interval`, `procs-history`, `github-poll-interval`,
    `projects-board`, `pages`, `repo-config`, `app`, or `page`)

読み方: 1 行目がファイル名、Caused by が vig の受け付けなかったものと、 期待される候補です — ここでは theme のタイポ。構文エラーにはさらに ファイル:行:桁 が付きます。カテゴリの一覧は 起動時エラー にあります。

素早く直すための道具が 3 つ:

• vig config path — 各レイヤの状態を表示。壊れたユーザー設定は TUI を 起動しようとせず、同じメッセージ付きで invalid (…) と出ます。
• vig --config ./try.kdl — 本物の設定に触らず、別ファイルで実験。
• vig config dump — 常に正しい形を写せるリファレンス。

リポジトリローカルの .vig.kdl だけは起動を止めません: 壊れていると vig は組み込み + ユーザーで起動し、ステータスバーに ignored .vig.kdl: <理由>（stderr にも 1 行）が出ます。

GitHub ビューがペインの代わりにエラーを表示する

GitHub・Projects ビュー（とそのポーリング）は GitHub CLI（gh） を経由します。よくある 原因は 2 つ:

• gh が入っていない — ステータスバーに起動エラー（例: gh not found: No such file or directory）が出ます。GitHub CLI を インストールして PATH に置いてください。
• gh が未認証 — gh のエラーがそのまま表示されます。 gh auth login を実行してから、ビューで r を押してリトライして ください。

vig 自身があなたのトークンを読むことはありません — 認証は完全に gh のものです。

Projects ビュー: gh needs the project scope

Projects ビューは gh project … を使い、これにはトークンの project スコープが必要です — gh auth login がデフォルトでは付けないスコープ です。無い場合、ビューはペインの代わりに案内を表示し、ステータスバーに こう出ます:

gh needs the project scope: run `gh auth refresh -s project`

そのまま実行してください:

gh auth refresh -s project

その後ビューで r を押します。（GitHub ビューはこのスコープ無しで 動きます。必要なのは Projects だけです。）

⚠ GitHub rate limited

GitHub がリクエストをレート制限で拒否すると、GitHub ページはすべての ポーリングを止めて指数バックオフします — 30 秒、60 秒、…最大 10 分 — そしてステータスバーに ⚠ GitHub rate limited (resets in Nm) を表示 します。リセット時刻は 1 回の gh api rate_limit 呼び出しから取得 します（このエンドポイント自体はレート制限されません）。r で即時 リトライ、最初に成功したフェッチでバックオフは解除されます。

頻繁に当たるならポーリングを遅くしてください — vig がポーリングするのは 何かが動いている間だけ（実行中のワークフロー、ウォッチモード、実行中 ジョブのログ）で、間隔は github-poll-interval （デフォルト "5s"、最小 "2s"）です:

github-poll-interval "15s"

クォータはあなたのトークンを使うすべてと共有です — 同じアカウントを ポーリングする他のツールも同じ上限を消費します — 開いている vig の インスタンス全部もです。vig は自分でクォータを守ります: キー入力が 10 分 無いと忘れられたインスタンスはポーリングを 6 分の 1 に減らし（ヘッダに idle）、GraphQL の残り（5,000/時）が 20% 未満で自動更新の間隔を 2 倍、 5% 未満で自動更新を停止（refresh stopped。r は使えます）、残り 1,500 ポイント未満でヘッダに ⚠ api N left を出します。同じリポジトリの インスタンスはディスクキャッシュを共有するので、他のインスタンスが取得 したばかりのボードは再取得せずディスクから読みます。自動更新を完全に 止めるには github-auto-refresh "off" を設定してください。

Files ビューのアイコンが豆腐 / 文字化けになる

あれは Nerd Font のグリフで、端末のフォントに入っていないのが原因です。 Nerd Font を入れるか、アイコンを切って ください（icons）:

icons "none"

画像プレビューがおかしい（低解像度なのはなぜ？）

Files ビューが画像を元の解像度でプレビューできるのは、グラフィック プロトコルを持つ端末 — Kitty、WezTerm、Ghostty、iTerm2、foot などの Sixel 対応端末 — だけです。それ以外（および多くの SSH / マルチプレクサ 構成）ではユニコードのハーフブロックにフォールバックし、これは意図的に 粗い表示です。プレビューの 1 行目に使用中のレンダラが出るので、どちらの 経路になったか確認できます。

自動検出があなたの端末で誤動作する場合は上書きしてください （image-preview）:

image-preview "halfblocks"   // 検出せず、常にハーフブロック

image-preview "none"         // 画像は描画しない。メタデータのみ

20 MB を超える画像はデコードしません。

.vig.kdl の信頼ダイアログが何度も出る

ダイアログが出るのは git に追跡されている .vig.kdl（リポジトリと 一緒に来たもの）で、記憶される回答は worktree パスとファイル内容の ハッシュがキーです — つまりファイルが変わると（pull の後など）意図的 にもう一度確認され、Esc は何も記憶しません（記憶するのは y / n です）。記憶は CLI から管理できます:

vig config trust                     # 記憶済みの決定を一覧
vig config trust --forget <path>     # その worktree で次回また確認させる

リポジトリローカルレイヤ自体が不要なら、ユーザー設定でスイッチを 切ってください（repo-config）— 読み込みもダイアログも無くなります:

repo-config "off"

あなた自身の未追跡の .vig.kdl でダイアログが出ることはありません。

vig がファイルを置く場所（と消し方）

vig が書き込むのは 3 か所で、どれも消して安全です:

vig が認証情報を保存することはありません — GitHub アクセスは gh 経由 で、トークンは gh が管理します。

FAQ

vig がリポジトリを変更することはある？

設計上ありません。vig が行うのは読み取り操作と、ちょうど 2 つの安全な git コマンド — git switch と git branch -d（マージ済みでない ブランチを拒否する安全な削除）— だけで、どちらもブランチのアクション メニューから、確認のうえでのみ実行されます。merge、rebase、force delete、push、stash の変更、コンテナ操作、プロセスへのシグナルは一切 ありません。

キーが効かない / 変な動きをする — どこを見る？

? を押してください: ヘルプオーバーレイはマージ後の設定から生成 されるので、あなたのリバインドを含めて、いま何がバインドされているかが 正確に出ます。そこに無いキーは "None" で外されたか、レイアウトで ペインが非アクティブになっています。どのレイヤが読まれているかは vig config path で分かります — リポジトリローカルの .vig.kdl も キーをリバインドできることを忘れずに。

ペインが画面から消えたのはなぜ？

設定（または .vig.kdl）のレイアウトがペインを書かないと、そのペインは 非アクティブになります — 領域なし、Tab からもスキップ。これは機能 です（レシピ）。Projects ページに は意図的に置かれていないペインすらあります （ページ projects）。ペインを 置いた layout を書き直せば戻ります。

vig のアップデート方法は？

vig update が最新リリースをダウンロードし、署名を検証してバイナリを 置き換えます — ビルド済みバイナリからのインストール向けです。Homebrew や cargo で入れた場合は brew upgrade vig / cargo install vig を 使ってください。

gh や Docker が無くても動く？

動きます。ビューは独立に劣化します: gh が無ければ GitHub と Projects ビューが案内を表示し、Docker デーモンが無ければ Docker ビューが表示 します。Git・Files・Procs・Worktrees ビューはどちらも必要としません。 使わないビューは pages で丸ごと無効化 できます。