fittok

fittok

LLM がコードベースに関する質問に、コンテキストを小さく絞り込んで回答できるよう、モデルにファイル全体を読ませるのではなく、質問に関連するソースコードだけを取得します。 入力が少なければ、トークン数もコストも抑えられ、回答も速くなります。

1 回のインストールで 3 通りの方法で使えます。MCP サーバー、CLI、Python ライブラリに加え、コンテキストを自動で注入するClaude Code プラグインも利用できます。

📖 コマンドリファレンス全文 → docs/HANDBOOK.md

mcp-name: io.github.likhithreddy/fittok

---

仕組み

codebase ──▶ graphify ──▶ slurp ──▶ readable slice ──▶ LLM answers
             (parse)      (select)   (trim to budget)

1. graphify — tree-sitter でリポジトリを解析し、関数／クラス／メソッドのナレッジグラフを作成します（Python、JS、JSX、TS、TSX、Java、Go、Rust）。複数の言語にまたがる呼び出し／インポート／参照のエッジに対応しています。

2. slurp — 4 つのシグナルを組み合わせたハイブリッド方式で、質問に対する各ノードのスコアを算出します。

   • セマンティック埋め込み（all-MiniLM-L6-v2） — 意味に基づくマッチング
   • Content-BM25（camelCase／snake_case の分割処理あり） — キーワードマッチング
   • Summary-BM25（ノード名＋ファイル＋呼び出し元＋呼び出し先） — 構造に基づくマッチング
   • PageRank — グラフの中心性／ハブの検出

   シグナルは**逆順位融合（RRF）**で統合されます。順位に基づくため、スコア調整の問題はありません。ノードは、ディレクトリをラウンドロビンで交互に選択する方式で選ばれます（複数の観点を含む質問で各側面を確実にカバーするため、同じコード領域から 2 つ目のノードを選ぶ前に、各コード領域から 1 つずつ選びます）。さらに、ノードごとのトークン上限（予算の 25％）により、大きなコンポーネントが小さな関数を押しのけるのを防ぎます。関連度のしきい値（セマンティック、BM25、Summary-BM25 のいずれか）がノイズを除外します。

3. 読みやすい出力 — 選択したノードの実際のソースコードに加えて、モデルが後続の呼び出しを正確に振り分けられるよう、コードベースマップ（docstring を含む目次。Karpathy の LLM Wiki／Google の OKF に着想を得ています）を返します。モデルはファイルを読む必要なく、出力から直接回答します。

編集に合わせて、ファイルウォッチャー（初回のクエリ時に自動起動）がグラフを増分更新します。変更されたファイルだけを再解析してマージし、変更された関数だけを再度埋め込みます。グラフと埋め込みはディスク上（~/.cache/fittok）にキャッシュされます。ウォッチャーを無効にするには FITTOK_AUTOWATCH=false を設定してください。この場合、編集後の次回のクエリ時に全体を再解析します。

---

最適な結果を得る方法（および既知の制限事項）

焦点を絞った質問をする

fittok は、4 つのシグナルを組み合わせたハイブリッド方式（セマンティック＋BM25＋構造＋PageRank。RRF で統合）とディレクトリをラウンドロビンで選択する多様性確保を使って、質問に対するコードの関連度を順位付けします。そのため、複数の観点を含む質問では、1 つの優勢な領域に集中せず、複数の領域（UI、サーバー、データベース）からコードが提示されます。焦点が明確で具体的な質問に対して最も正確です。できれば、質問ごとに懸念事項を 1 つに絞り、関数／コンポーネント／ルート名を指定してください。質問の分解（ツールの説明で、モデルに観点ごとに 1 回ずつ呼び出すよう指示します）とコードベースマップ（すべての応答の先頭に付けられる目次）により、複数の観点を含む質問にも対応します。

• ✅ "runSandboxQuery は SQL クエリをどのように実行し、分離しますか？" → 対象の関数とその分離処理のコードを提示します。
• ✅ "querydle クライアントはどのようにクエリを送信し、結果を表示しますか？" → UI コンポーネントを提示します。
• ✅ "UI からの送信、サンドボックスでの実行、データの分離まで、ライフサイクル全体を追跡してください。" → 質問の分解とラウンドロビン方式による多様性確保で複数の観点をカバーします。コードベースマップにより、見落としたファイルがあればモデルが適切に参照できます。

目安： 質問ごとに懸念事項を 1 つに絞ります（最大でも 2～3 つの観点まで）。「機能全体を説明して」と尋ねる場合は、1 つの巨大なクエリにまとめず、焦点を絞った質問をいくつかに分けてください。

既知の制限事項

• GitHub Copilot Chat は大きな MCP 出力を切り捨てます（最も大きな問題です）。 Copilot は約 7 KB を超える MCP ツールの結果を content.json ファイルにキャッシュしますが、その際、Markdown 全体が改行をエスケープした 1 本の物理的な JSON 行にまとめられます。そして Read ツールは、各行を約 2,000 文字で切り捨てます。そのため、約 7 KB を超える出力は、全体のサイズに関係なく実質的に約 2,000 文字で切り詰められ、モデルはコードの大部分を参照できず、ソースファイルを直接読むようになります。これは Copilot の配信レイヤーの問題であり、fittok の問題ではありません。すべての MCP サーバーで同じ制限が発生します。 デフォルトでは（0.10.0 以降）、fittok は関連するコードをすべて上限なしで返します。これはインラインで配信するクライアントには適切ですが、Copilot では切り捨てられます。回避策は 2 つあります。
  • Copilot 向けに出力を制限し、インラインで配信できるようにします（約 7 KB のしきい値未満）。MCP サーバーの環境変数に FITTOK_MAX_BUDGET=1200 を設定します。

    { "servers": { "fittok": { "command": "uvx", "args": ["fittok"], "env": { "FITTOK_MAX_BUDGET": "1200" } } } }
    

  • 複数ファイルにまたがる質問には Claude Code または CLI を使用します。 MCP の出力は切り捨てられずにインラインで配信されます。これにより、fittok の完全な（上限なしの）結果と、再読み込みを防ぐ設計の効果を最大限に活かせます。
• 抽象的なクエリでは語彙の差が問題になります。 クエリにコード内に存在しない語（例：「isolation」→ REVOKE／DENY）が使われている場合、セマンティック検索でも BM25 でもその差を埋められません。コードベースのマップ（ファイル名と docstring）やラウンドロビンによる多様性が役立ちます。関数名やファイル名を指定すれば、モデルはその場所にたどり着けます。
• 増分更新によるエッジの欠落： ファイルを編集すると、完全に再解析するまで、変更されていないファイルからそのファイルへの呼び出し／インポートのエッジが失われることがあります。fittok は再起動時または reset_graph の実行時に自動で復旧します。
• トークン数は概算です： cl100k_base を使って数えているため、実際の使用量は Claude のトークナイザーとの差が約 10～20％生じます（FITTOK_MAX_BUDGET の上限を設定した場合にのみ影響します）。
• 非常に大規模なリポジトリ： PageRank はまだベクトル化されていないため、ノード数が数千程度までは問題ありませんが、それを超えると遅くなります。

---

インストール

fittok は MCP サーバー、CLI、Python ライブラリとして提供されています。埋め込みに torch を使用するため、Python ランタイムが必要です。以下から ランタイムを 1 つ選び、使用するクライアントのセクションに従ってください。

以下の設定例はすべて、fittok を uvx fittok として起動します。Python または pipx を選んだ場合は、それぞれ python -m fittok または pipx run fittok に置き換えてください。

前提条件 — ランタイムを 1 つ選択してください

A. uv — 推奨（マシンに Python は不要）

curl -LsSf https://astral.sh/uv/install.sh | sh   # Linux / macOS
winget install astral-sh.uv                        # Windows
brew install uv                                    # macOS (Homebrew)

起動コマンド：uvx fittok — uv が独自の Python とすべての依存関係を分離環境に用意します。 単一の静的バイナリなので、MDM／Intune／winget を使って組織全体に展開できます。

B. Python 3.10 以降（すでにマシンにインストール済み）

python -m pip install fittok      # Linux / macOS
py    -m pip install fittok       # Windows

起動コマンド：python -m fittok（Windows：py -m fittok）。

管理対象の Linux 環境では PEP 668 （「externally-managed-environment」）により pip install が拒否される場合があります。その場合はオプション A を使用してください。

C. pipx — 分離環境で実行し、グローバルにはインストールしない

brew install pipx                               # macOS
pip install --user pipx && pipx ensurepath      # Linux / Windows

起動コマンド：pipx run fittok。

MCP サーバー — Claude Code

claude mcp add fittok -s user -- uvx fittok

Claude Code を再起動し、/mcp を実行して fittok が接続済みであることを確認してから、通常どおりコードベースについて質問してください。

MCP サーバー — VS Code／GitHub Copilot Chat

code --add-mcp '{"name":"fittok","command":"uvx","args":["fittok"]}'

または、ワークスペースの .vscode/mcp.json か、ユーザー設定の mcp.json に貼り付けます。

{ "servers": { "fittok": { "type": "stdio", "command": "uvx", "args": ["fittok"] } } }

次に、Copilot Chat で Agent モードを選択し、fittok のツールを有効にします（Configure Tools）。

MCP サーバー — GitHub Copilot CLI

copilot mcp add fittok -- uvx fittok
copilot mcp get fittok          # verify status + tools

MCP サーバー — Cursor／Windsurf／その他の MCP クライアント

{ "mcpServers": { "fittok": { "command": "uvx", "args": ["fittok"] } } }

自動トリガー（任意、すべての MCP クライアント）

fittok の名前を挙げなくても、すべてのコードベースに関する質問で fittok を呼び出し、 fittok がすでに返したファイルをクライアントが再読み込みして 節約分を無駄にしないようにするには、クライアントの指示ファイルに次の1行を追加します。

「コードベースに関する質問では、まず fittok を呼び出し、その出力をもとに回答してください — fittok がすでにコードを返したファイルを再読み込みしないでください。」

前半は fittok を起動し、後半はクライアントがその後に同じファイルを開くのを防ぎます。 この2つは互いを補強します。1つは 方針（fittok を使う）を定め、 もう1つは 二重読み込み を防ぎます。より強力で明示的な指示にするには、次を使用します。

コードベースに関する質問（「X はどのように動作しますか」「Y はどこにありますか」など）では：

1. まず fittok MCP ツールを1回呼び出します。
2. その optimized_context を直接もとに回答します — これはその質問に対する実際の信頼できる情報源です。
3. fittok がすでにコードを返したファイルを読み込んだり、grep したりしないでください。 そうすると、fittok が節約するために存在しているトークンを無駄にします。

最も強い効果を得るには、ユーザー共通の指示に追加して、1つのリポジトリだけでなく すべてのリポジトリに適用されるようにします。

クライアント	指示ファイル
Claude Code	CLAUDE.md（リポジトリ）または ~/.claude/CLAUDE.md（ユーザー共通）
GitHub Copilot	.github/copilot-instructions.md または Copilot のユーザー指示
Cursor	.cursor/rules/*.mdc（または .cursorrules）
Windsurf	.windsurfrules

fittok はこのルールもすべての応答に組み込むため（コードの上に「これをもとに回答し、再読み込みしない」という行を追加します）、上記のスニペットがなくても機能します — スニペットを追加すると、すべての質問でクライアントのデフォルト動作になります。

CLI

cd /path/to/your/repo

uvx fittok index                                      # optional pre-warm (~15s, cached)
uvx fittok query "how does auth work"                 # LLM answers from relevant code
uvx fittok query "how does auth work" --budget 1500   # cap the slice at 1500 tokens
uvx fittok query "how does auth work" --code          # raw relevant code, no LLM
uvx fittok graph                                      # interactive browser graph
uvx fittok graph --query "auth"                       # graph with relevant nodes highlighted

query は関連するコードの一部を LLM に送信し、回答をストリーミングします。 シェルでキーを1つ設定すれば、そのまま動作します。

export ANTHROPIC_API_KEY="sk-ant-..."   # → claude-haiku-4-5  (recommended)
export OPENAI_API_KEY="sk-..."          # → gpt-4o-mini  (fallback)

Claude Code のユーザーはすでに ANTHROPIC_API_KEY を設定しているため、追加の手順は不要です。 どちらのキーも設定されていない場合、fittok は --code にフォールバックし、セットアップのヒントを表示します。

graph には pyvis が必要です：uv pip install "fittok[ui]"。

Python ライブラリ

uv add fittok            # in a uv project   (or:  uv pip install fittok  in a venv)

from fittok import optimize

result = optimize("/path/to/repo", "how does authentication work", token_budget=1500)
print(result["optimized_context"])   # the relevant code slice
print(result["savings"])             # token reduction stats

アップグレード

uvx は環境をキャッシュするため、新しい fittok のリリースは自動的には適用されません — サーバーを再起動しても、キャッシュされたバージョンが再利用されます。次の1つのコマンドでアップグレードできます（MCP サーバーを再登録する必要はありません）。

uvx --refresh fittok        # re-resolve from PyPI → latest version

その後、MCP サーバーを再起動し（VS Code でウィンドウを再読み込みするか、Copilot CLI を再起動して）、新しいバージョンを起動します。他のランタイムの場合：

• pip： python -m pip install --upgrade fittok
• pipx： pipx upgrade fittok

---

tree-sitter を使い、LSP を使わない理由

fittok は、LSP（Language Server Protocol。型やファイル間参照、定義へのジャンプなどのセマンティック解析）ではなく、tree-sitter（高速な構文 AST 解析）を使用します。これは意図的なトレードオフです。

	tree-sitter（fittok）	LSP（例：Serena MCP）
返されるもの	実際のソースコード — モデルが直接回答できます	シンボルのメタデータ（名前、参照、型）— モデルはそれでもファイルを読み込む必要があります
セットアップ	設定不要。どのディレクトリでも動作します	言語サーバーのインストールとプロジェクト設定（tsconfig、pyproject など）が必要です
言語	初期状態で 8 言語（Python、JS/TS/TSX、Java、Go、Rust）	インストールした LSP サーバーの数だけです
起動時間	約 15 秒（解析＋埋め込み）	数分（言語ごとにプロジェクト全体をインデックス化）
メモリ	約 100 MB（グラフ＋埋め込み）	言語サーバーごとに 500 MB 以上
質問あたりのモデル呼び出し回数	1～5 回（1 回の検索で取得）	5～20 回以上（シンボルを反復的にたどる）
トークンコスト	約 2,500 トークン（コードを直接提供）	約 15,000 トークン以上（メタデータ＋ファイルの読み込み）

fittok の独自の強みは、トークンを節約できることです。 1 回の呼び出しで実際のコードを返すため、モデルがファイルを読み込む必要がありません。LSP ベースのツールが返すのはメタデータ（シンボル名、参照一覧）です。正確ではありますが、モデルは実装を確認するために、やはりファイルを開く必要があります。やり取りが増え、トークンも多くなります。

トレードオフ： tree-sitter は、ファイル間参照を LSP ほど正確には解決できません（.tsx ファイル内の fetch("/api/run") 呼び出しが、ルートハンドラーに完璧に結び付くとは限りません）。fittok は、4 つのシグナルによる検索（セマンティック＋コンテンツの BM25＋構造要約の BM25＋PageRank を RRF で統合）と、ディレクトリのラウンドロビンによる多様性確保で補い、実用上の不足をカバーします。

競合ではなく、相互補完です： Serena のような LSP ベースのツールは、シンボル単位のナビゲーション（「runSandboxQuery の呼び出し元をすべて見つける」）に優れています。fittok は、セマンティック検索（「SQL の実行はどのように行われますか？」）に優れています。両方をインストールすれば、モデルがタスクに応じて適切なツールを選びます。

---

トークンの節約 — 正直な数値

実際の Next.js/TS リポジトリ（関数約 5,000 個）では、fittok はモデルがファイルから読み込む 15,000～20,000 トークン以上の代わりに、約 1,500～3,500 トークンの範囲を返します。入力を 約 80～90% 削減でき、その数値は savings フッターに決定的な値として表示されます。

Opus 4.8 では、幅広い質問で、fittok を使わない場合は合計 約 84,000 トークン、使った場合は 約 27,000 トークンでした。これは、fittok が 58,000 トークンの Explore サブエージェントを 1 回のツール呼び出しに置き換えたためです。

正確に測定する方法：

• 🪙 saved X% フッターか、API 請求額（合計トークン数）を使用してください。
• Claude Code の /context に表示される Messages の数値で判断しないでください。この数値にはサブエージェントのトークンが含まれず、fittok が影響しないモデルの推論に大きく左右されます。

---

設定

変数	デフォルト	説明
ANTHROPIC_API_KEY	—	claude-haiku-4-5 による LLM の回答を有効にします
OPENAI_API_KEY	—	gpt-4o-mini による LLM のフォールバック
FITTOK_SHOW_SAVINGS	true	MCP の回答に 🪙 saved X% フッターを表示します。無効にするには false を設定します
FITTOK_MAX_BUDGET	0（無制限）	コードのトークン上限です。0 = 関連するコードをすべて完全な形で返します（デフォルト — Claude Code / CLI で完全な結果を返します）。MCP の出力が約 7 KB を超えると切り詰める GitHub Copilot では 1200 を設定してください（既知の制限を参照）。
FITTOK_AUTOWATCH	true	ファイルウォッチャーを自動起動し、グラフを差分更新します（変更されたファイルのみを再解析します）。編集時に全ファイルを再解析する動作に戻すには false を設定します
FITTOK_EMBED_MODEL	all-MiniLM-L6-v2	埋め込みモデル
FITTOK_DEVICE	auto	auto / cuda / mps / cpu
FITTOK_CACHE_DIR	~/.cache/fittok	キャッシュの保存場所

詳細なリファレンス：docs/HANDBOOK.md

---

要件

Python ≥ 3.10。初回実行時に約 90 MB の埋め込みモデルがダウンロードされます。グラフの可視化（fittok graph）はデフォルトで含まれています。オプションの追加機能：

• uv pip install "fittok[ui]" — Gradio ウェブダッシュボード（launch_ui ツール）
• uv pip install "fittok[gpu]" — GPU で高速化された埋め込み処理用の torch/CUDA

ライセンス

MIT