trailhq/Trail-Code

Trail（旧称 Graft）– コードベースを認識するアシスタントヘルパー

それは何か – Trail は、リポジトリの軽量でローカルな「グラフ」を構築する TypeScript/Node.js CLI です。グラフは、短く平易な英語の要約、主要なコード抜粋（核心）、および概念間の型付きリンクを含む Markdown ファイルで構成されます。このグラフを Claude Code、Cursor、Codex、Gemini、または LLM 駆動の「コーディングアシスタント」などのコーディングエージェントに配線することで、Trail はエージェントがプロジェクトの構造を認識した状態でセッションを開始できるようにし、通常トークン、ツール呼び出し、レイテンシを消費する「再探索」フェーズを回避します。

なぜ重要か – 典型的な AI コーディングアシスタントは、すべての新しいタスクをコードベースを見たことがないかのように扱います。繰り返し grep し、ファイルを開き、インポートを追跡するため、トークン使用量が増加し、応答が遅くなります。Trail はその理解を一度キャプチャし、ローカルに保存し、エージェントのプロンプトに注入します。README は、正確性を失うことなく最大 4 倍安く、3 倍速く 実行でき、SWE-bench ベンチマークで精度が測定可能なほど向上すると主張しています。

主な機能

• ワンタイムグラフ構築（graft init / trail init）は、tree-sitter でソースファイルを解析し（モデル不要、API キー不要）、オプションでファイルごとに言語モデルを 1 回実行して人間が読める要約を生成します。
• Markdown ノード：各ノードには、要約、最も関連性の高いコード行、ソースファイルのハッシュ、wikilink スタイルの型付きエッジ（depends_on、uses など）が含まれます。
• ローカルキャッシュ：graft/ フォルダーは .gitignore に追加されます。小さな配線ファイル（.claude/、AGENTS.md）のみがコミットされます。
• 自動フレッシュネス：回答する前に、ツールはファイルハッシュをチェックし、変更された部分のみを再構築するため、エージェントは未コミットの編集があっても常に現在の作業ツリー状態を確認できます。
• エージェント統合：Claude Code（深い統合）の組み込みサポートと、他のエージェント用の汎用 MCP サーバーフック。
• CLI ユーティリティ – graft ask、graft grep、graft map、graft viz、graft check で、グラフの検索、視覚化、検証ができます。
• マルチリポジトリ / monorepo サポート と広範な言語カバレッジ（TS/JS、Python、Go、Java、Rust、C/C++ など 23 言語）。
• プロバイダーに依存しない LLM 使用 – 要約ステップに OpenAI、Anthropic、OpenRouter、Groq、LiteLLM、またはローカルモデルを独自の API キーでプラグインできます。

典型的なワークフロー

1. CLI をインストールします（npm i -g @trailhq/trail または npm i -g @nanonets/graft）。
2. trail init（または graft init）を実行します – 使用するエージェントを選択すると、ツールが graft/ ディレクトリと配線ファイルを作成します。
3. 次回 Claude Code セッションを開始すると、Trail が関連ノードの要約をプロンプトに注入するため、モデルははるかに少ないツール呼び出しで回答できます。
4. 各コーディングセッション後、行った修正は .trail/learnings/ の下に「学び」として保存されます。これらは、将来のセッションでエージェントが自動的に適用するルールになります。
5. PR の前に、trail check が既存の学びと衝突する変更をフラグします。

ベンチマーク（報告による）

• コールド vs. Graft（Claude Code）：ツール呼び出しが 46% 減、トークンが 42% 減、レイテンシが 60% 減、SWE-bench で正確性が 12 ポイント向上（54% → 66%）。
• コスト：タスクあたり $0.029 vs. $0.042（約 32% 安い）。

誰が使うか – LLM ベースのコーディングアシスタントに大きく依存し、API コストを削減し、応答を高速化し、機関知識（チーム固有の決定、パターン、修正）をリポジトリに直接キャプチャしたい開発チーム。

---

TL;DR：Trail（旧称 Graft）は、コードベースの人間が読める Markdown ベースの知識グラフを構築し、AI コーディングエージェントに配線する CLI で、繰り返しのコード探索を削減し、トークンと時間を節約し、チームの学びを将来のセッションのために永続化します。