jahala/tilth

tilth – 人間とAIエージェントのためのスマートなコードリーディング

概要 – tilth は、ソースコードをtree‑sitterで解析し、インデックスを構築せずにコードベースの構造を照会できる単一バイナリのコマンドラインツール（およびMCPサーバー）です。シンボルが定義されている場所、呼び出し元、ファイルが依存しているもの、さらにはコミット間の関数レベルの差分を表示できます。

AIエージェントにとって重要な理由 – 大規模言語モデルは、関数を見つけるために安価なツール（glob→grep→read）の連鎖に頼ることが多く、呼び出し元や依存関係を発見するために多くのファイルを読む必要があります。tilth はワンステップで重い処理を行います。構文ツリーを理解するため、エージェントは正確な定義、コールグラフ、ファイルレベルのアウトラインを即座に取得でき、ツール呼び出しの回数やプレーンテキスト検索による誤検出の可能性を減らします。

---

主な機能

機能	得られるもの
ファイルアウトライン / セクションビュー	小さなファイルは全体が印刷され、大きなファイルは行範囲ブロックを含む構造的アウトラインを返します。--section を使用して特定の範囲やマークダウンヘッダーを取得します。
シンボル検索	tilth <シンボル> --scope <ディレクトリ> は最初に定義を見つけ、次に使用箇所を周囲のコードスニペットとともに表示します。--expand は上位の一致のソースを追加し、--full は一致上限を引き上げます。
呼び出し元と呼び出し先	--callers はすべての呼び出しサイトをリストします（テキスト一致だけでなく構造的に）。展開された定義には、呼び出す関数を含む-- calls --フッターが含まれます。
ファイルレベルの依存関係	tilth <ファイル> --deps は、ファイルがインポート/使用しているものと、それをインポートしている他のファイルを報告します – リファクタリング前に便利です。
grok	シンボルのシグネチャ、ドキュメントコメント、本体、呼び出し先、呼び出し元、兄弟、関連テストを返すワンショットコマンド。
構造的差分	tilth diff <コミット> は、追加・削除・変更された関数を行番号付きで表示します（生の差分だけでなく）。
MCPサーバーモード	同じ機能をMCPプロトコルで公開し、AIエージェント（Claude‑code、Cursor、Geminiなど）がツールチェーンから直接tilth_search、tilth_deps、tilth_grokなどを呼び出せるようにします。
編集モード	--edit を使用すると、サーバーはハッシュアンカー付きの行参照を使用してファイルを安全に編集するtilth_write/tilth_readも提供します。

---

典型的なユースケース

• AIアシスタントツール – tilth をClaude‑code、Cursor、またはMCP互換のエージェントにプラグインして、モデルが「ServeHTTPを呼んでいるのは誰？」や「recovery.goで何が変わった？」と尋ねられるようにします。カスタムスクリプトは不要です。
• 開発者ナビゲーション – ターミナルから関数定義をすばやく見つけ、そのコールグラフを表示し、ファイルの外部依存関係を理解します。
• コードレビューとリファクタリング – コミット間の関数レベルの差分を生成したり、リネームが呼び出し元を壊さないことを確認したりします。
• 大規模コードベース – 数千ファイルのプロジェクト（FastAPI、Gin）で数十ミリ秒で動作します。構文ツリーを並列で走査するためです。

---

インストールと開始

# Rustのパッケージマネージャーを使用
cargo install tilth
# またはnpmでワンオフバイナリ（コンパイル済みバイナリを同梱）
npx tilth

プリビルドバイナリはGitHubリリースページでも利用できます。

MCPサーバーとして実行するには（ほとんどのエージェントが使用するモード）：

tilth --mcp            # サーバーを起動
# エージェント用のクライアント設定をインストール、例：
tilth install claude-code   # ~/.claude.jsonを書き込み

サーバーは--editで起動して、安全なファイル編集機能を有効にできます。

---

アーキテクチャの概要

• 言語解析 – tree‑sitter（17のサポート言語）を使用して、各ファイルのインメモリ構文ツリーを構築します。型解決はなく、構造解析のみです。
• 検索エンジン – tree‑sitterクエリ（定義、呼び出し元、呼び出し先）をripgrepクレートと組み合わせて、プレーンテキスト/正規表現/glob検索を行います。
• 並列処理 – ディレクトリの走査（ignoreクレート）とシンボルルックアップはrayonで並列化され、中規模リポジトリで100ms未満の応答時間を実現します。
• キャッシュ – アウトラインキャッシュ（DashMap経由）はファイルの変更時間が変更されたときに無効化され、繰り返しのクエリを高速化します。
• ゼロランタイム依存関係 – バイナリは純粋なRust（約35k行）で、ネットワーク呼び出しを行わないため、すべてのコードがローカルに保たれます。

---

制限事項

• 型推論なし – tilth は純粋に構文に基づいて動作します。ジェネリック型やオーバーロードを解決できません。
• 呼び出し元の名前のみ一致 – 異なるモジュールで同じ名前の関数が2つある場合、呼び出し元が曖昧になる可能性があります。
• 言語カバレッジ – tree‑sitter文法を持つ言語のみが完全にサポートされ、その他はプレーンテキスト検索にフォールバックします。
• 動的ディスパッチ – リフレクションやランタイムコード生成を介して呼び出される関数は検出されません。

---

ライセンスとコミュニティ

• ライセンス: MIT – 寛容で、商用およびオープンソースプロジェクトに適しています。
• サポート: 著者はBuy‑Me‑A‑Coffeeで寄付を受け付けています。問題や機能リクエストはGitHubで対応しています。

---

TL;DR

tilth は、AIエージェント（および開発者）に、インデックス不要で構文認識型のコードベースビューを提供します。定義の検索、コールグラフの追跡、ファイル依存関係の検査、関数レベルの差分の表示を、小さなRustバイナリまたはMCPサーバーからすべて行えます。raw grepスタイルのツールとヘビー級言語サーバーの間のギャップを埋め、コード理解ツールをより効率的で信頼性の高いものにします。