karst

karst

変更によって何が壊れるかを把握できます。コードをマシンの外に出す必要はありません。 karst は、Cursor、Claude Desktop、カスタムエージェントなど、あらゆる AI コーディングツールにコードベースのローカルマップを提供します。正確な file:line の引用付きで質問に答えるだけでなく、実際の呼び出し／インポート／継承グラフをたどって、変更の影響範囲を算出します。つまり、「ここを変更したら、ほかに何が壊れるか？」という、通常の検索やエージェントによる grep では答えられない質問に答えます。

ローカルで動作し、MCP に対応しているため、あらゆるエージェントに組み込めます。また、テレメトリーはありません。CLI が単独で何かを外部に送信することはありません。インデックス作成、検索、影響分析で LLM が呼び出されることもありません。LLM を呼び出すのは karst ask と karst review だけで、設定済みの場合に限られます。マシンの外に送信される情報では、すべてのケースを一覧にしています。さらに、パック単位の検索により、質問ごとの入力トークンを約 60% 削減できます。

規制対象、エアギャップ環境、または知的財産に配慮が必要なチーム向けですか？ karst は、クラウド型コーディングツールでは構造上利用できない環境向けに構築されています。完全オフラインで、テレメトリーがなく、監査可能なソースを提供します。まずはマシンの外に送信される情報と、コンプライアンスとエアギャップ向けパック（証明資料、ネットワークの外部送信一覧表、記入済みのセキュリティ質問票、オフラインインストール）をご確認ください。

uv tool install karst      # recommended — fast, and puts `karst` on PATH for you
# or
pipx install karst         # isolated install, also handles PATH
# or
pip install karst          # if `karst` isn't found after, use `python -m karst …`

uv と pipx が最も簡単です。karst コマンドが自動的に PATH に追加されます。通常の pip --user（特に Microsoft Store 版 Python）では、コマンドが PATH に追加されない場合があります。その場合は python -m karst … を使えば、PATH の設定は不要です。

初回実行：ダウンロードされるもの

karst 自体のコードはネットワーク要求を行いませんが、依存関係のうち 2 つは、初めて必要になったときにファイルを取得します。どちらもディスクにキャッシュされるため、それぞれ 1 回だけ実行されます。

1. Tree-sitter パーサー（tree-sitter-language-pack）。このホイールには文法が含まれていません。言語を初めて使用するときに、パーサーバンドルをダウンロードし、その言語のライブラリを展開します。karst が現在解析する 6 つの言語を取得するには、karst がインストールされている Python 環境で次のコマンドを 1 回実行します。

   python -c "from tree_sitter_language_pack import get_parser; [get_parser(n) for n in ('python', 'javascript', 'typescript', 'go', 'rust', 'java')]"
   

   .tsx ファイルは typescript 文法で解析されるため、tsx の個別項目はありません。キャッシュはユーザーごと、かつ tree-sitter-language-pack のバージョンごとに作成され、仮想環境ごとではありません。そのため、同じバージョンがインストールされている Python ならどれでもキャッシュを作成できます。これは、karst がプライベート環境にインストールされる uv tool や pipx のインストールで便利です。

2. 埋め込みモデル（BAAI/bge-small-en-v1.5、約 65 MB、huggingface.co から）。初回の index、quickstart、ask、review、または MCP の search_code でダウンロードされます。小規模なリポジトリで karst quickstart を 1 回実行して取得した後、KARST_OFFLINE=1 を設定すると、それ以降のモデルのダウンロードを禁止できます。

tree-sitter-language-pack 1.9.1（pyproject.toml で固定されているバージョン）のパーサーのダウンロード詳細：

ホスト	GitHub の kreuzberg-dev/tree-sitter-language-pack のリリース v1.9.1：マニフェスト、parsers.json、およびプラットフォームごとのアーカイブ（parsers-<os>-<arch>.tar.zst、約 18～21 MB）。GitHub は xberg-io/tree-sitter-language-pack（リポジトリの新しい名前）にリダイレクトし、アーカイブは release-assets.githubusercontent.com から配信されます。HTTPS のみです。HTTPS_PROXY／ALL_PROXY が適用されます。
整合性	アーカイブの SHA-256 は、マニフェスト内の値と照合されます。一致しない場合は ChecksumMismatchError が発生し、何もキャッシュされません。マニフェストとアーカイブは同じリリースから取得されるため、破損したダウンロードや改変されたダウンロードは検出できますが、リリース自体が侵害された場合は検出できません。署名の検証は行われず、展開されたライブラリ（ネイティブコードであり、karst のプロセスに読み込まれます）は、後続の実行時に再ハッシュされません。
キャッシュ	Linux ${XDG_CACHE_HOME:-~/.cache}/tree-sitter-language-pack/v1.9.1/libs、macOS ~/Library/Caches/tree-sitter-language-pack/v1.9.1/libs、Windows %LOCALAPPDATA%\tree-sitter-language-pack\v1.9.1\libs。python -c "import tree_sitter_language_pack as t; print(t.cache_dir())" を実行すると、キャッシュの場所が表示されます。（Microsoft Store 版 Python では、Windows のフォルダーは独自の LocalCache\Local ディレクトリ内にあります。）
ミラー／オフライン	TREE_SITTER_LANGUAGE_PACK_MANIFEST_URL（https:// または file:// URL）を設定すると、マニフェスト URL が置き換わります。エアギャップ環境のマシンで使うには、接続されている同じ OS・CPU のマシンで上記のコマンドを実行し、libs フォルダーを同じパスにコピーしてください。

このコマンドを 1 回実行すれば、analyze、graph-index、impact はネットワーク要求を行いません。ある言語のライブラリがキャッシュにあれば、パックはそれをディスクから読み込み、GitHub に接続することはありません。6 つすべてがキャッシュされていれば、マニフェストもネットワークも不要で動作します。この動作は、そのバージョンのキャッシュフォルダーが完全な状態である間に限られます。異なるバージョンの tree-sitter-language-pack は別のキャッシュフォルダーを使用するため、再度ダウンロードされます。

この用途に、パック独自の download([...]) は使用しないでください。1.9.1 では、パックにすでに登録されている言語に対しては、何も取得せずに戻ります。karst が行うように get_parser を呼び出すことで、ダウンロードが実行されます。KARST_OFFLINE=1 が対象とするのは埋め込みモデルのみで、パーサーは対象外です。

パーサーのダウンロードは Python ではなく、パックのネイティブコード内で行われます。Python レベルのネットワークフック（socket.socket のモンキーパッチや socket.connect の監査フック）では検知できないため、karst がオンラインになったかどうかは確認できません。代わりに、ファイアウォールのログや、Linux の strace -f -e trace=network など、OS レベルで確認してください。

その理由

多くの「コードベースとチャット」ツールは、質問のたびに、関連性が曖昧な数万トークンをモデルに投入します。何が読み込まれたのか確認できず、対象を絞ることもできず、月末には請求が届きます。karst はその逆を行います。

• 対象を絞る — パックで絞り込んだ検索では、5,000 件ではなく約 200 件のチャンクを読み取ります。
• 引用する — すべてのチャンクに正確な file:line が付いています。信頼するのではなく、検証できます。
• 予測する — 実際の呼び出し／インポートグラフにより、「これを変更すると、ほかに何が壊れるか？」に答えられます。埋め込みだけではできません。

実際の 246 ファイルの NestJS + Next.js リポジトリで測定：906 件のチャンクをインデックス化し、増分再インデックスは 343s → 2.3s、Sonnet 4.6 で質問あたり 約 $0.019（呼び出し前に表示）、パックを付けるとトークンを 60% 削減しました。

クイックスタート（CLI）

karst コマンドが見つからない場合：Python の Scripts ディレクトリが PATH に含まれていません（Microsoft Store 版 Python でよくあります）。以下はすべて python -m karst … でも同じように動作するため、PATH の設定は不要です。（または uv／pipx でインストールすると、karst が PATH に追加されます。）

cd your-project

# one command: index + call/import graph + suggested packs
karst quickstart                 #  or:  python -m karst quickstart

# ask questions about the code (defaults to this folder's index)
karst ask "how does checkout charge the user?" --no-llm    # cited code, no API key
karst ask -i                     # interactive: ask many questions

# what breaks if I change a function? (run inside the project; it finds the graph itself)
karst impact --target checkout

# review a diff with severity-tagged, cited findings
karst review --staged --storage ~/.karst/indexes/<your-project>-<hash>   # the path quickstart prints

karst examples                   # a copy-paste cheatsheet of everything

karst quickstart は、インデックスのパスを埋め込んだ正確な次のコマンドを表示します。ANTHROPIC_API_KEY／OPENAI_API_KEY が設定されている場合、karst ask は LLM の回答を書き込みます。その際、取得したコードが該当プロバイダーに送信されます（お使いのマシンから送信される情報を参照）。引用付きチャンクのみを取得し、ネットワーク呼び出しを行わない場合は、--no-llm を追加してください。以下の MCP サーバーにもキーは不要です — モデルは IDE が提供します。

IDE から使用する（MCP）

karst には MCP サーバー（karst-mcp）が付属しており、stdio 経由で 5 つのツール — search_code、find_impact、list_packs、index_status、index_repository — を公開します。

Claude Desktop（claude_desktop_config.json）または Cursor （.cursor/mcp.json）— お使いのランチャーを選んでください。

{
  "mcpServers": {
    "karst": { "command": "uvx", "args": ["--from", "karst", "karst-mcp"] }
  }
}

uvx には事前インストールが不要です。必要に応じて karst を取得して実行します。すでにインストール済みの場合は、{ "command": "karst-mcp" } も使えます。PATH をまったく使わない場合は、{ "command": "python", "args": ["-m", "karst.mcp_server"] } を使ってください。

ホストを再起動して、普段どおり質問してください。必要に応じて karst のツールが呼び出され、対象を絞り込んだ引用付きのコンテキストが返されます。設定の詳細は docs/MCP.md をご覧ください。

ガイド

初めての方は、ご自身に合ったものから始めてください。

• karst とは？ — karst の概要と用途を、平易な言葉で説明します。どんな問題を解決するのか分からない場合は、まずこちらをお読みください。
• クイックスタート — API キー不要で、実際の出力を確認しながら、5 分で実際の質問ができるようになるまでを説明します。
• バイブコーディングをする方へ — CLI コマンドを使わず、チャットするだけで Cursor／Claude Desktop から karst を使えます。
• AI ツールを接続する — すべてのクライアント向けに、MCP の設定をコピー＆ペーストで行えます。Claude Desktop、Claude Code、Cursor、Windsurf、VS Code、Zed、JetBrains、およびウェブアプリに対応しています。
• セルフホストとエアギャップ環境 — ローカルモデルを使って、karst と AI の回答をすべて自分のマシン上で実行します。コードをクラウドに送れないチーム向けです。
• クックブック — オンボーディング、影響範囲、トークンコストの削減、差分のレビューなど、実際のシナリオをコピー＆ペースト可能なコマンドとともに紹介します。
• MCP の設定 — karst をあらゆる MCP クライアントに接続します。

仕組み

1. インデックス作成 — tree-sitter がすべての関数、クラス、メソッドを AST を認識したチャンク（Python、JS、TS、Go、Rust、Java）に分割し、チャンクをローカルの Qdrant ストアに埋め込みます。増分処理では、SHA マニフェストと埋め込みキャッシュにより、変更されていないファイルをスキップします。
2. グラフ — CALLS／IMPORTS／CONTAINS／IMPLEMENTS エッジで構成される NetworkX ナレッジグラフが、影響分析（「これは何に依存されていますか？」。インターフェースを実装するクラスや、基底クラスを拡張するクラスも含みます）を支えます。
3. パック化 — 関連ファイルを、名前を付けてアタッチできるコンテキストパック（auth、billing）にまとめます。クエリでは、そのパックだけを読み込みます。
4. 提供 — MCP サーバーが、順位付けされ、file:line の引用付きチャンクを返します。ホスト側のモデルが、それらを基に推論します。

すべてローカルで実行され、オフラインでも使用できます（FastEmbed／ONNX の埋め込み、Qdrant のローカルモード、sqlite キャッシュを使用。Docker もデーモンも不要です）。初回のダウンロードと、ネットワークに接続する可能性があるすべての処理を以下に記載しています。

マシンの外部に送信されるもの

CLI にはテレメトリ、分析、更新チェック、ホームへの通信はなく、karst 自体のコードにも HTTP クライアントは含まれていません。ネットワーク通信が発生するのは、以下の項目のみです。それぞれ、データを一切送信しない初回のみのダウンロードか、ユーザーが開始または設定する処理のいずれかです。

コマンド／フラグ	送信される内容	送信先	タイミング
analyze、graph-index、impact、packs …、MCP find_impact／list_packs／index_status	何も送信されません	—	送信されません。（analyze、graph-index、packs suggest はコードを解析するため、次の行に記載されているパーサーが必要です。）
言語の初回解析（analyze、graph-index、index、quickstart、packs suggest、MCP index_repository）	お客様のデータは送信されません。tree-sitter パーサーバンドルを通常の方法でダウンロードします（約 18～21 MB）。他のダウンロードと同様に、GitHub にはお客様の IP アドレスが通知されます。ネイティブコードからダウンロードされるため、Python レベルのソケットフックでは検知できません。OS レベルで監視してください。	github.com（release-assets.githubusercontent.com にリダイレクト）	パーサーのバージョンごとに 1 回。ただし、すでにキャッシュされている場合を除きます。事前にダウンロードできます。
初回の埋め込み（index、quickstart、ask、review、MCP search_code／index_repository）	お客様のデータは送信されません。埋め込みモデルをダウンロードします（約 65 MB）。埋め込み処理自体はローカルで実行されます。	FastEmbed と huggingface_hub を通じて huggingface.co	~/.karst/models に 1 回ダウンロードされます。KARST_OFFLINE=1 を指定するとブロックされます。
--no-llm を指定しない ask	質問と取得されたチャンクです。デフォルトでは上位 8 件で、それぞれ最大 2,000 文字に制限されます。--graph を指定した場合は、グラフ上の近傍ノードが最大 6 件追加されます。	Anthropic（api.anthropic.com）、OpenAI（api.openai.com）、またはローカルモデルサーバー	プロバイダーを設定している場合は、実行ごとに送信されます。どのプロバイダーも設定されていない場合は、エラーで停止し、何も送信されません。
review --staged／--base／--diff／--pr	変更されたファイルごとに、その差分の各ハンク、ハンクを含むチャンクを最大 3 件（それぞれ最大 1,500 文字）、類似チャンクをハンクごとに最大 3 件（それぞれ最大 800 文字。--no-neighbors を指定すると除外されます）。	ask と同じプロバイダーのルールが適用されます。review には --no-llm がないため、常に LLM が必要です。	実行ごとに送信されます。
review --pr N	PR 番号と --repo。PR の差分を読み取ります。	gh CLI を通じて GitHub にアクセスします。アカウントは gh へのログインに使用したものです。	--pr を使用したとき。
review --pr N --post-to-pr	指摘ごとにインラインコメントが 1 件ずつ付いた PR レビュー（重大度、メッセージ、修正案）。	gh api を通じて GitHub にアクセスします。お客様の gh アカウントが使用されます。PR 上の全員が閲覧できます。	このフラグを追加したとき。確認プロンプトは表示されません。
karst-mcp（stdio または --http）、すべてのツール	取得されたコードチャンクと影響分析の結果が MCP クライアント（Claude Desktop、Cursor、Claude Code、…）に返されます。karst 自体が外部に何かを送信することはありません。	MCP クライアント。通常、クライアントはツールの結果を自身のモデルプロバイダーに転送します。	ツール呼び出しごと。クライアントがその後どのような処理を行うかはクライアントによって決まり、karst には制御されません。
karst-mcp --http	外部には何も送信されません。ベアラートークンを提示するクライアントに、インデックス化されたコードを提供します。	デフォルトでは 127.0.0.1:8080 でリッスンします。KARST_MCP_TOKEN がないと起動せず、ツールが読み取れるのは KARST_MCP_ROOTS 配下のリポジトリのみです（デフォルトは作業ディレクトリ）。KARST_MCP_HOST=0.0.0.0（または --host）を指定すると、ネットワークからアクセスできるようになります。	実行中。

ask と review が使用する LLM：--llm（ask のみ）、または設定されている場合は KARST_LLM_PROVIDER。どちらも設定されていない場合、KARST_LLM_BASE_URL が設定されていればローカルサーバーを使用します。それも設定されていない場合、ANTHROPIC_API_KEY が設定されていれば Anthropic を使用し、そうでなければ OPENAI_API_KEY が設定されていれば OpenAI を使用します。別のツール用にシェルに設定済みの API キーがあるだけで、karst ask はコードチャンクをそのプロバイダーに送信します。 引用付きチャンクのみを取得し、LLM を呼び出さない場合は --no-llm を使用してください。ローカルモデルを使用する場合は --llm local／KARST_LLM_PROVIDER=local を指定してください。ローカルサーバーの URL はデフォルトで http://localhost:11434/v1（Ollama）です。KARST_LLM_BASE_URL をリモートホストに設定すると、プロンプトはそのホストに送信されます。Anthropic と OpenAI の SDK はオプションの追加機能（karst[anthropic]、karst[openai]、karst[llm]）です。通常の pip install karst ではどちらも呼び出せません。ローカルオプションでは openai 追加機能を使用します。 ベクトルストア（Qdrant）は ~/.karst/indexes/ 以下で埋め込みローカルファイルモードとして動作します。リモート Qdrant オプションはありません。埋め込みモデルがキャッシュされると、FastEmbed はリクエストを行わずにディスクから読み込みます。また、KARST_OFFLINE=1 を設定すると、モデルが見つからない場合にダウンロードせず、エラーになります。モデルのダウンロードには Hugging Face のクライアントライブラリが使用されます。このライブラリには独自の使用状況テレメトリー設定（HF_HUB_DISABLE_TELEMETRY=1）があります。この設定は karst ではなく、同ライブラリに属するものです。

ステータス

提供中：AST チャンキング（6 言語）、呼び出し／インポートグラフと影響分析、パック単位の検索、トークンとコストの計測、増分インデックス作成と埋め込みキャッシュ、インライン PR 投稿に対応した差分コードレビュー（review --pr --post-to-pr）、および stdio とリモート Streamable-HTTP の両方に対応する MCP サーバー（karst-mcp --http）。 次の予定：ホスト型インデックス作成、チームで共有するパックライブラリ、自律型 GitHub PR レビューボット、ブラウザーコネクター（claude.ai / ChatGPT）向け OAuth。

ライセンス

Apache-2.0。詳しくは LICENSE をご覧ください。