lean-ctx

LeanCTX — AI システム向けコンテキストゲートウェイ

AI が参照できる情報を制御します。LeanCTX Engine は、既存のエージェント向けに、ローカルでのコンテキスト選択、対応するアクセス制御とコンテンツ制御、観測されたコンテキスト操作の証拠を提供します。選択 → 制御 → 学習 → 証明。ここでの「学習」は、ローカルでのタスクとナレッジの継続性を意味し、モデルのトレーニングではありません。復元は、ソースまたはアーカイブが利用可能であること、およびアクセス権限に依存します。LeanCTX SDK は、アプリケーション向けの独立した統合インターフェースです。

lean-ctx は、キャッシュされた読み取り、圧縮されたシェル出力、焦点を絞った検索、正確なソースへの復元により、コンテキストがユーザーに届く前に整えます。細かな点よりも、次の 2 つのルールを優先してください。

1. 出力を小さくするより、往復回数を減らすことが重要です。 質問に答える 1 回の呼び出しは、小さな呼び出しを 3 回行うより低コストです。数百トークン節約するだけのために、呼び出しを増やしてはいけません。
2. ポーリングで待機してはいけません。 sleep とステータス確認をループさせないでください（以下を参照）。

意図 → ツール

目的	呼び出し
仕組みを理解する（場所が不明）	ctx_compose(task) — ランク付けされたファイルとソースを 1 回の呼び出しで取得します。検索 → 読み取り → 読み取りの代わりに、まずこれを使ってください
シンボルの正確な定義を見つける	ctx_search(action="symbol", name=…)
意味からコードを見つける	ctx_search(action="semantic", query=…)
テキスト／正規表現パターンを見つける	ctx_search(pattern=…, path=…)
X を呼び出すもの／X が呼び出すものを調べる	`ctx_callgraph(action="callers"
編集するファイルを読む	ctx_read(path, mode="anchored") → ホスト標準の編集ツールで編集するか、ctx_call(name="ctx_patch", arguments={…}) を呼び出します
コンテキストのみを目的にファイルを読む	`ctx_read(path, mode="signatures"
編集後にファイルを再確認する	ctx_read(path, mode="diff")
コマンドを実行する（ビルド、テスト、git など）	ctx_shell(command) — 出力は圧縮されます
ファイル一覧／ディレクトリ構成を確認する	ctx_glob(pattern) / ctx_tree(path, depth)
セッションをまたいで記憶する	`ctx_session(action="finding"

ctx_shell（cat、sed -n、grep、rg）を使って読み取りや検索を行わないでください。これらは読み取りキャッシュとシンボルインデックスを迂回します。ctx_read / ctx_search を使ってください。

遅延読み込みツール（ToolSearch）

ホストに lean-ctx ツールが名前だけで表示される場合（Claude Code の ToolSearch）、タスクに必要なツールを 1 回の呼び出しで読み込んでください。例： select:mcp__lean-ctx__ctx_compose,mcp__lean-ctx__ctx_search,mcp__lean-ctx__ctx_read 読み込み済みだからという理由で、すべての作業を ctx_shell に頼らないでください。ここに記載されているツールがツール一覧にない場合（デフォルトプロファイルにはコア機能のみが表示されます）でも、呼び出すことができます：ctx_call(name="ctx_knowledge", arguments={…})。 ctx_call(name="ctx_discover_tools", arguments={"query": "…"}) を呼び出すと、すべてのツールが一覧表示されます。

長時間実行コマンド

• 完了時に通知されるホスト独自のバックグラウンド実行機能を優先してください （Claude Code：run_in_background を指定した Bash、または Monitor）。開始したら、ほかの作業を続けるか、ターンを終了してください。完了すると通知されます。
• ctx_shell(run_in_background=true) のジョブは、単独では通知しません。結果が実際に必要なときに限り、ジョブを確認してください。sleep をループさせてはいけません。

出力の切り詰め

圧縮またはアーカイブされた出力の末尾には、復元ハンドルが付いています。必要な部分だけ取得してください：ctx_expand(id, search=… | head=N | json_path=…)、または正確なバイト列が必要な場合は ctx_read(path, raw=true) を使います。コマンドを再実行しないでください。

MCP なしの場合（CLI）

lean-ctx read <file> -m signatures    # or map | diff | lines:N-M
lean-ctx grep <pattern> [path]
lean-ctx -c "<command>"               # only where the shell is not already wrapped
lean-ctx raw "<command>"              # exact, uncompressed output

セットアップ

which lean-ctx || curl -fsSL https://raw.githubusercontent.com/yvgude/lean-ctx/main/skills/lean-ctx/scripts/install.sh | bash
lean-ctx setup        # editor wiring, hooks, rules, this skill
lean-ctx doctor       # verify

ドキュメント：https://leanctx.com/docs