Psychic: fzfのように、しかしあなたの行動から学習するファイルブラウザ
Psychic: Like fzf but learns from your actions (klauria.tech)
要約
Psychicは、ユーザーの行動履歴から学習する機械学習モデルを搭載した、高速なターミナルベースのファイルブラウザです。入力に応じてリアルタイムで検索結果をランク付けし、ファイルやディレクトリへのアクセスを劇的に高速化します。fzfやzoxideにMLの要素を加えたようなツールで、開発者のファイルナビゲーション体験を向上させることを目指しています。
全文翻訳
psychic: like fzf but learns from your actions
psychic は ML パワードのランキング機能を備えた高速ファイルブラウザ
ほとんどの日、私はターミナルでディレクトリに cd したり、エディタでファイルを開いたりしています。同じプロジェクトに取り組んでいるため、週のほとんどで同じファイルやディレクトリを扱っています。ファイルがどこにあるかを覚えておく必要があることにうんざりし、同じパスをタブ補完するのに疲れました。私のコンピュータは、私が開きたいファイルをすでに知っているはずです!
そこで、高速なターミナルベースのファイルブラウザである psychic を作成しました。これは、移動するディレクトリを追跡し、開くファイルを記憶します。データ上で軽量な ML モデルをトレーニングし、そのモデルを使用して結果をランク付けします。何よりもインタラクティビティと速度を優先しています。結果は入力中に更新され、UI は 16ms 未満でレンダリングされます。
その仕組みのすべては、重要な設計上の決定から流れています。それは、キープレス後に 1 フレーム以内に更新できるほど高速でなければならないということです。数秒で 10 回の高速検索を行う方が、数秒かかる 1 回のスマート検索よりも優れています。
私はコンピューターを使うたびに psychic を使用しています。ファイルシステムを移動する主な方法になりました。いくつかの数字:
- 2025 年 10 月に使い始めて以来、1450 回開きました。平均して、目的のものを得る前に 1.6 文字入力しました。
- 29% の時間、何も入力しませんでした!psychic は私が望むものを知っており、トップの結果でした。私がしたことは、開いて Enter を押すだけでした。
- psychic を開いてから目的の場所に移動するまでの時間の中央値は 2 秒でした。検索の 41% は 1 秒以内、69% は 3 秒以内でした。
- 80% の時間、トップの結果を選択しました。選択の 96% はトップ 3 にありました。
- 平均して、選択したパスは約 50 文字離れていました。つまり、そこに到達するためにその 3% を入力しています。
(これらは組み込みの psychic stats コマンドからのもので、自分の履歴で実行できます!)
Homebrew で利用可能です: brew install kshitijl/tap/psychic。
[動画]
左側は検索結果です。右側は現在選択されているファイルまたはディレクトリのプレビューです。下部に入力クエリを入力すると、結果がフィルタリングおよびランク付けされ、各文字で変化します。ファイルで Enter を押すと、同じウィンドウでターミナルエディタが開き、バックグラウンドで待機します。ディレクトリの場合は、そこから検索を再開します。開いたすべてのファイルとディレクトリを記憶しており、シェル統合は psychic の外部から cd したすべてのディレクトリを記録します。これらすべてが、すべての検索に含まれます。
それは、fzf と zoxide が子供を産み、あなたのパターンと好みを学習する小さな ML モデルを追加したようなものです。あなたのデータで広告最適化を行い、コンピューターをより速くナビゲートできるようにします。
仕組み
すべての検索とクリックは、コンピューター上の sqlite DB に書き込まれます。psychic はそのデータ上で LightGBM モデルをトレーニングします。モデルは、検索クエリに基づいて、どのファイルを開くかを予測することを学習します。psychic はモデルを使用して検索結果をランク付けします。キープレスごとに、psychic はモデルを再実行し、すべての結果を再ランク付けします。
詳細については、リポジトリの README を参照してください。
いくつかの重要な設計上の決定
私が使用するモデルは LightGBM で、勾配ブースティングツリーの実装です。非常に軽量で高速であり、数秒でトレーニングできます。しきい値に依存するルールを学習できます。たとえば、「1MB を超えるファイルは、過去 24 時間以内に変更された場合にのみ開かれる」といったログファイルのようなルールを学習できます。LightGBM には、この種のランキングタスクに特化された優れた LambdaRank オブジェクティブもあります。
レイテンシの予算により、ローカルではないモデルは除外されました。ネットワーク呼び出しは、簡単に 10ms 以上、あるいはそれ以上かかる可能性があります。また、LLM やあらゆる種類のトランスフォーマーモデルも除外されました。線形回帰やロジスティック回帰は単純すぎ、LightGBM よりもはるかにパフォーマンスが悪かったです。
モデルは、psychic を開くたびにゼロから再トレーニングされます。これは、常に現在の使用パターンを反映していることを意味します。トレーニングはバックグラウンドで実行され、完了するとモデルがディスクに書き込まれます。アプリがそうするように、使用中に新しいモデルに切り替えることはしません。代わりに、画面を見ていないとき、たとえばエディタでファイルを開いているときやディレクトリをクリックしたときなどを待ちます。そして新しいモデルに切り替えます。この慎重な小さなダンスを誇りに思っています。
ユーザーが psychic を使い始めたばかりで、トレーニングするクリック数が十分でない場合。最近のクリック、最近の変更時間、クエリとファイル名の間のあいまいな一致を優先する単純なモデルを使用します。最終スコアは、単純なモデルと ML モデルの加重合計です。クリック数が少ない場合、単純なモデルが支配的になります。クリック数が蓄積されるにつれて、ML モデルのスコアの重みが増し、最終的にはほぼ 1 になります。
psychic になる方法
どのファイルを開くかを予測するために、慎重に選択した機能セットを使用しています。いくつかの機能は単純です。psychic 内で最後にクリックした時期、変更時間、ファイル名がクエリで始まるかどうか、クエリとファイル名の間のあいまいなテキスト一致スコア。これは、機能とパフォーマンス統計の一部を示すデバッグペインです。
[画像: デバッグペインと機能名]
このデバッグペインは、奇妙な結果や遅延を特定するのに役立ちました。最近では psychic はかなり安定していますが、それでも時々開くのが好きです。
機能の 1 つは、「このファイルと同じディレクトリ内にあるファイルに対する最近のクリック数」です。この機能は、モデルが現在アクティブなプロジェクト内のファイルをブーストするのに役立ちます。
「このクエリに対するクリック数」という機能は、ファイル名やクエリテキストを文字通り覚える必要なしに、モデルが特定のクエリと特定のファイルを関連付けるのに役立ちます。このように、モデルはファイル名を直接見ませんが、関連性を記憶できます。
[画像: トレーニング図]
各トレーニング実行は、いくつかの統計情報を含む PDF を書き出します。ここでは、トレーニング曲線と各機能のゲインを見ています。
エピソードは、psychic を開いてから(または最後のクリックから)アイテムをクリックするまでのすべてとして定義されます。したがって、単一のエピソードには、バックスペースのヒットや新しいクエリの試行など、多くのクエリが含まれます。「エピソード内のクエリに対するエンゲージメント」機能は、現在のクエリを持つエピソードで、ファイルをクリックした回数をカウントします。たとえば、「es」と入力して「bayesian-estimate.md」をクリックした場合、モデルはその関連性を確認できます。次回「es」と入力すると、モデルはそのファイルをリストのトップに配置します。
[画像: SHAP 値]
ここでは SHAP 値とドットチャートを示します。これらは、機能がモデルの出力にどれだけ影響するかを理解し、モデルがそのように動作する理由を解釈するのに役立ちます。たとえば、ドットチャートは、モデルが最近変更されたファイルを好むこと、そしてほとんどの大きなファイルを好まないことを示しています。
コンピューターを高速化する
パフォーマンスを綿密に監視し、優れたベンチマーク設定とパフォーマンスログに多くの労力を費やしました。すべてのコミットにはパフォーマンスベンチマークが含まれています。psychic を使用してパフォーマンスが低下した場合は、バグです!お知らせいただければ修正します。
私の技術選択はパフォーマンスによって推進されました。おそらく最も重要な選択は Rust と LightGBM でした。
システムコールは高価ですが、もちろんこのプログラム全体はシステムコールです。システムコールの数を最小限に抑えようとしました。メインのレンダリングループにファイルシステムシステムコールはありません。ファイルシステムをウォークする際にファイルメタデータを要求し、それをどこでも持ち運ぶように注意深くしました。