Graphify Ts

Madar

コーディングエージェントが検索を始める前に、必要なリポジトリのコンテキストを与えます。

Madar は TypeScript または Node.js のリポジトリをローカルグラフにし、現在の質問をタスクに合わせた小さなコンテキストパックに変換します。Claude Code、Codex、Cursor、Copilot、Gemini、Aider、OpenCode は、リポジトリを一から調べ直す代わりに、関連するファイル、シンボル、スニペット、関係性を起点にできます。

• 最初は小さく： 広範な検索の前に、エージェントへ有力なエントリーポイントと実行時のパスを渡します。
• ローカルに維持： グラフの生成時にソースコードがアップロードされることはなく、クラウドサービスも必要ありません。
• 常に最新： インストール済みの MCP プロファイルは、アクティブなワークスペースが変わるとグラフを更新します。

60 秒で試す

Node.js 20 以降で Madar をインストールし、リポジトリ内で実行します。

npm install -g @lubab/madar
cd your-repository
madar try "how does authentication work?"

madar try はローカルグラフを構築または再利用し、人が読みやすい最初の結果を表示して、次に実行するエージェントのインストールコマンドを提案します。ソースコードは変更しません。

具体例として、Madar に含まれるパスワードリセット用ワークスペースには、次のパスがあります。

account-routes.ts
  -> PasswordResetService.requestPasswordReset()
  -> userRepository.saveResetToken()
  -> enqueueResetEmailJob()
  -> sendPasswordResetEmail()

このように、追加のファイル調査が必要かどうかを判断する前に、Madar は焦点を絞った開始パスをエージェントに提示します。

エージェントを接続する

使用するエージェントを選びます。Claude Code の場合：

madar claude install
madar doctor
madar status

プロファイルのインストール後、madar doctor と madar status を実行します。すると、次のような通常のプロンプトを使って、エージェントが Madar にコンテキストを問い合わせられるようになります。

How does authentication work?
Why does this endpoint return 403?
Where is the report generated?
What breaks if I change this service?
Add telemetry to this flow.

Madar は、プロジェクト内で使用する次のインストーラーに対応しています。

エージェント	インストールコマンド
Claude Code	madar claude install
Codex CLI	madar codex install
Cursor	madar cursor install
GitHub Copilot	madar copilot install
Gemini CLI	madar gemini install
Aider	madar aider install
OpenCode	madar opencode install

インストーラーの詳細は、CLI と MCP のリファレンスをご覧ください。手順に沿ったセットアップとスモークテストについては、エージェントのクイックスタートをご覧ください。

Madar をアップグレードした後は、エージェントのインストールコマンドを再実行して、管理対象のプロファイルを更新してください。古いプロファイルでは、自動更新や Codex の長い起動猶予時間が利用できない場合があります。

Codex のインストールでは、起動時間とツールのタイムアウトを長く設定した、ワークスペース単位の MCP ブロックが作成されます。初期の調整中も Madar は利用可能で、グラフの準備ができると、グラフに基づく呼び出しが利用可能になります。

0.31.3 以降、Madar が starting、pending、または reconciling のときに行われたグラフに基づく呼び出しは、再試行可能な構造化レスポンスを返します。Madar を迂回したり、生成を手動で実行したりせず、提示された待ち時間の後に、同じ Madar リクエストを再試行するようエージェントに指示してください。停止した更新処理の所有者は自動的に復旧されます。修復が求められるのは、グラフの状態に失敗、不完全、またはポリシーとの不一致がある場合のみです。

エージェントにとっての変化

Madar がない場合、コーディングエージェントはまず、ファイル名を広範囲に検索し、同じファイルを何度も読み、どのルート、サービス、ハンドラーがタスクを担っているのか推測しがちです。

Madar があれば、最初の調査で次の情報を含められます。

• 関連する可能性が高いファイル、エクスポートされたシンボル、ルート、ハンドラー
• 質問に関連する直接的なスニペット
• インポート、呼び出し、フレームワークでの役割、実行時の引き継ぎ
• グラフが裏付けている場合の静的な実行パスの仮説（実際の実行トレースではありません）
• グラフの鮮度とインデックス作成の完全性を示す情報
• 回答する、注意書きを添えて回答する、または対象を絞って検証するための明確な指針

Madar はエージェントに取って代わるものでも、エージェントがコードを読むのを妨げるものでもありません。エージェントがコードリポジトリに基づいて、より小さな範囲から調査を始められるようにします。

仕組み

Your repository
      |
      v
Local Madar graph
      |
      v
Context for the current question
      |
      v
Claude, Codex, Cursor, or another coding agent

1. Madar は、ソースファイル、シンボル、インポート、呼び出し、ルート、ハンドラー、フレームワークのメタデータ、選択したドキュメントをインデックス化します。
2. 質問に応じて、リポジトリ全体をプロンプトに投入するのではなく、範囲を限定したコンテキストパックを選択します。
3. 回答では、証拠の強さ、網羅性、鮮度、および対象を絞った検証がまだ必要かどうかを示します。
4. インストール済みの MCP プロファイルは、アクティブなワークスペースを監視し、関連する変更後にグラフに基づくコンテキストを更新します。

範囲を限定した復旧と回答可能性の状態を含む、応答仕様の全体は「MCP response shape」に記載されています。

MCP を使わずに Madar を使用する

CLI を使えば、エージェントとの統合をインストールせずにコンテキストを生成して調査できます。

madar generate .
madar summary
madar pack "how does auth work?" --task explain --format text

デフォルトでは、madar generate . は JavaScript／TypeScript 向けに SPI メタデータと実証済みのレガシーセマンティクスを組み合わせ、その他のサポート対象言語ではレガシーフォールバックを使用します。厳格モードについては、CLI リファレンスをご覧ください。

プロバイダーですぐに使えるプロンプトを作成します。

madar prompt "how does auth work?" --provider claude

別のコーディングツールに渡すための、安全に共有できる引き継ぎ情報を作成します。

madar handoff "add auth telemetry" --task implement --consumer copilot

生成されたグラフとインデックス作成マニフェストは、プロジェクトの出力先に保持されます。再現可能なサンプルワークスペースと期待される出力については、「Getting started」チュートリアルをご覧ください。

Madar の活用場面

Madar が特に役立つのは、次のような場合です。

• リポジトリが中規模または大規模である
• プロジェクトの主な言語が TypeScript または Node.js である
• エージェントが同じファイルを何度も開いたり、関係のないフォルダーを検索したりする
• アーキテクチャ、実行時のフロー、レビュー、影響範囲について質問する
• トークン使用量、レイテンシ、またはローカルリポジトリのプライバシーが重要である

次のような場合は、役立つ範囲が限られます。

• リポジトリが小さい、またはタスクの内容が1つのファイルから明らかである
• 静的解析では観測できない、実行中の動作に関する質問である
• グラフに含まれていない動的なパターンにコードが大きく依存している
• グラフが古い、または関連するソースファイルをインデックス化できていない

Madar はエージェントや IDE のインデックス機能を補完します。ホスト型ナレッジベース、実行時トレーサー、PR レビューツール、脆弱性スキャナーではありません。

ローカルで完結する設計

• プライバシー： Madar のグラフ生成はローカルで実行され、API キーは不要です。ただし、コーディングエージェントの設定によっては、そのエージェントがプロンプトや選択されたファイルのコンテキストを独自のモデルプロバイダーに送信する場合があります。
• 機密ファイル： 通常のセキュリティ関連ソースコードは引き続きインデックス作成の対象となりますが、秘密鍵、.env*、認証情報ストア、既知のソースコード以外の秘密情報は除外されます。これはパスに基づくポリシーであり、コンテンツレベルで秘密情報をスキャンするものではありません。
• 鮮度： インストール済みの MCP プロファイルでは自動更新が有効です。CLI を手動で使用する場合は、madar generate . で再生成できます。厳格なワークフローでは、--require-fresh-context または --require-fresh-graph を必須にできます。
• ワークツリー： Madar とエージェントは、同じリンク済み Git ワークツリーから実行してください。各ワークツリーのグラフ生成物はチェックアウトの外部に分離して保存されます。ワークツリーを切り替えた後は、MCP サーバーに再接続してください。
• テレメトリ： 明示的に有効にしない限り、テレメトリは無効です。設定方法と、ソース情報を含まない正確なイベントスキーマについては、テレメトリに記載されています。

ローカルにインストールする MCP、フック、エージェントプロファイルはすべて、ローカルの信頼境界の一部として扱ってください。MCP の脅威モデルでは、この境界について詳しく説明しています。

エビデンスと限界

Madar は、ベンチマークに関する主張の根拠となるプロンプト、回答、トレース、共有しても安全なレポートを公開しています。公開されている実験には異なる問いに答える 2 種類があり、同じテストであるかのように比較すべきではありません。

v0.30 の統制実験によるエビデンス

6 月に実施した TypeScript のランタイムフローに関する 6 回の試験では、タスク固有の証拠プロファイルを適用したソースのチェックアウトを使用しました。これらの統制された実行では、各行につき Madar を 1 回呼び出し、記録された結果は次のとおりでした。

• ツール呼び出しが 3.5x から 18.5x 減少
• プロバイダーが報告した入力が 2.2x から 15.6x 減少
• レイテンシが 1.65x から 7.09x 低下

これらの記録は、プロファイルを利用した Madar の実測値です。適切なタスクの証拠が利用できる場合に、このワークフローで実現可能なことを示しています。調整されていない npm インストールが任意の質問に対して同じ結果を再現する証拠ではありません。以前のプロンプトとチェックアウトからの情報取得には、通常のパッケージ利用者には提供されない、ベンチマーク固有の要件が含まれていたためです。

v0.31 本番成果物の検証

7 月の再実行ではそうした補助を取り除き、分離して展開した同一の @lubab/[email protected] パッケージ成果物を使用しました。6 つのリポジトリのうち 4 つでエージェントによる採用失敗が記録され、Madar MCP の呼び出しを確認できませんでした。残りの 2 つでは Madar が呼び出されたものの、厳格なプロンプトまたは回答の合格基準を満たしませんでした。正しい結果は有効なパフォーマンス比較がゼロ件であり、製品が 6 件すべてで劣ったということではありません。これらの再実行で明らかになったのは採用と回答の完全性に関する課題であり、以前の統制された効率測定の結果を肯定も否定もするものではありません。

ベンチマーク一式と日付入りの全記録、または簡潔な主張とエビデンスの対応表をご覧ください。

現在のリリース

現在のバージョン：0.32.3。

0.32.3では、トークナイザーとWebAssemblyパーサーを更新し、開発ツールを刷新して、開発依存関係のセキュリティアドバイザリに対応しました。

0.31.4では、レシートを表示中のコンテキストに紐付けたままにし、Claude/Codexのフック処理を強化しました。

0.31.3では、応答しなくなった更新処理の所有者から復旧し、実行中の更新処理との競合中は待機するようにしました。また、一時的な調整中には、エージェントにMadarのバイパスを促すのではなく、再試行シグナルを返します。

0.31.2では、初回の自動グラフ更新中もCodexのMCP接続が応答するようにし、Codexの起動時間を明示的に180秒確保しました。また、更新後のグラフが準備できるまで、グラフを利用した回答を使用できないようにしました。

0.31.1では、公開オンボーディングの流れを再構築し、各ベンチマーク実験で何が証明されるのかを明確にしました。実行時の動作は0.31.0から変更されていません。

0.31.0では、コードグラフをデフォルトで有向にし、エビデンスの強さと回答の準備状況を分離しました。また、範囲を限定したコンテキストの復旧機能を追加し、インデックス作成の完全性を明示しました。さらに、自動更新時の生成ポリシーを保持し、リンクされた作業ツリーのアーティファクトを分離して、本番環境の検索からベンチマークの期待値を取り除きました。

詳細は0.32.3の変更履歴をご覧ください。

ドキュメント

必要な情報	まずはこちら
初回実行	はじめに
エージェントのセットアップ	エージェントのクイックスタート
CLIとMCPツール	CLIとMCPのリファレンス
コンテキストパック	コンテキストパックの概念
最新性と自動更新	自動更新ポリシー
インデックス作成の網羅性	インデックス作成の完全性
プライバシーとMCPの信頼性	脅威モデル
エビデンスとベンチマーク	主張とエビデンス
ロードマップ	公開ロードマップ
リリース履歴	変更履歴

貢献

現在、特に役立つ貢献は、実際のTypeScriptおよびNode.jsリポジトリでのテスト、見落とされたコンテキストの報告、Windows/WSL/MCPの信頼性向上、フレームワークの検出、そしてセットアップ例の改善です。

nextブランチに対して、イシューまたはプルリクエストを作成してください。PRを作成する前に、次を実行してください。

npm test
npm run build
npm run release:verify

GitHubのコントリビューターで、コントリビューターの全体像をご覧ください。

貢献者

Madar の発展に貢献してくださった皆さまに感謝します。以下のリストは、main へのプッシュごとに自動的に再生成されます。

mohanagy

Gunselheli

qorexdevs

zhengjynicolas

jamemackson

Madar 初のコミュニティ提供機能である #54 を提供してくださった @jamemackson に、特別な感謝を申し上げます。

ライセンス

MIT。自由に使い、フォークし、公開してください。