local-llm-worker

---

5,000行のテストログや3ページ分のドキュメントを読むのにかかるトークン数は、最先端モデルにアーキテクチャの難題を解かせる場合と同じです。localizeは、大量の読み取り作業を、お使いのGPU（またはCPU）に任せるMCPサーバー兼Claude Codeプラグインです。

• offload：ローカルモデルがノイズの多いコマンドを実行するか、大きなファイルを読み取ります。Claudeが受け取るのは回答だけです。
• research：ローカルモデルがWebを検索し、ページ全体を読み取って、出典付きの回答を返します。Claudeはページを一切見ません。
• delegate（オプトイン）：ローカルモデルが隔離されたgit worktree内で1つのファイルを書き、Claudeが先に作成したテストに合格するまで再試行します。Claudeが受け取るのはコードではなく、一行の判定結果です。

> offload  npm test 2>&1   "Which test fails, and why?"
`fixed coupon never goes below zero` (test/cart.test.js:404): applyCoupon(5, {type:'fixed',
value:10}) returns -5, expected 0.
— qwen3-coder:30b-a3b-q4_K_M · 19,132 input tokens read locally

理由

	Claudeが実行	Claudeが委任
50 KBのテストログから1つの失敗を見つける	約19,000トークン分のログをコンテキストに読み込む	約130トークンの回答
3ページ分のドキュメントから回答する	ページ全体、またはその要約	ページ全体をもとにした、出典付きの段落と出典一覧
テストで仕様を確定できるヘルパーを作成する	コードの出力トークンを消費し、さらにコードを読み直す	テストを作成し、PASSを確認する
複数の独立したヘルパー	順次編集	各自のworktreeで並行して委任

• **あらゆるモデル、あらゆるハードウェアに対応。**モデルの固定やGPUの前提はありません。CPUのみでも動作しますが、速度は遅くなります。
• **デフォルトで並行実行。**1回のターン内で複数回呼び出す場合も、複数のサブエージェントから呼び出す場合も同時に実行されます。同時実行数の上限は設定値であり、固定ロックではありません。
• **コンテキストに合わせて自動調整。**テキストごとにモデルのコンテキストウィンドウに合わせて内容のサイズを調整します（数値の多いログは、文章より多くのトークンを必要とします）。切り捨てられた内容はすべて報告されます。
• **依存関係ゼロ。**Node ≥ 18のみで動作します。gitからのインストールにnpm installは不要です。
• エージェントから設定可能。configureを1回呼び出すと、設定、バックエンドとそのモデルを確認でき、任意の設定を変更できます。変更は再起動なしで次の呼び出しから反映されます。

インストール

**前提条件：**Node ≥ 18、git、実行中のローカルモデルサーバー（例：ollama pull qwen3-coder:30b）。

Claude Codeプラグイン

/plugin marketplace add JoblessJoe/localize
/plugin install localize@localize

あとは「このマシンでlocalizeを設定して」と尋ねるだけです。Claudeがバックエンドを検出してモデルを選び、どのツールを自動で使用するか（auto_use）を尋ねます。デフォルトではoffloadとresearchが対象です。delegateはオプトインです。どのツールも、使用するよう依頼すればいつでも使えます。

Claudeに毎回使わせる

セッション開始時のリマインダーで、選択したツールをClaudeが使うよう促せます。確実に使わせるには、これをCLAUDE.mdに追加してください。セットアップ時に追加することもできます。

## Local LLM (localize)
- Run test suites, builds and other noisy commands through `offload` (`command`), and read logs or files over ~300 lines through it, instead of reading the output yourself.
- Use `research` for web lookups instead of WebSearch/WebFetch.

これを設定してからは、ノイズの多いテスト失敗を含むテストスイートを試すたびに、Claudeはoffloadを実行しました。このセッションのコストは、出力を自分で読んだ場合より40％低くなりました。

任意のMCPクライアントで使う

Claude Desktop、Cursor、Windsurfなど：

{
  "mcpServers": {
    "localize": {
      "command": "node",
      "args": ["/path/to/localize/src/index.js"],
      "env": { "LLW_MODEL": "qwen3-coder:30b" }
    }
  }
}

プラグインを使わずにClaude Codeで使用する場合： claude mcp add localize -- node /path/to/localize/src/index.js

delegate の仕組み

flowchart LR
    A[Claude writes the test<br/>+ spec + invariants] --> B[delegate]
    B --> C[fresh git worktree<br/>+ your uncommitted changes]
    C --> D[local LLM writes<br/>target file]
    D --> E{run test}
    E -- fail --> F[parse failures<br/>test source stays hidden]
    F --> D
    E -- pass --> G[copy file into checkout<br/>unless it changed meanwhile]
    G --> H[Claude gets a one-line verdict]

• 分離。 呼び出しごとに独自の git worktree が割り当てられ、未コミットの変更も反映されます。また、node_modules ／.venv はシンボリックリンクされるため、並列呼び出しが互いに干渉することはありません。
• スコープをロック。 対象ファイルはリポジトリ内の1つだけに限定され、指定した test_files は対象になりません。
• 有用なフィードバック。 再試行時には、スタックトレースの末尾ではなく、解析済みの失敗したアサーション（TAP、pytest、jest、vitest、go、cargo）が渡されます。
• 安全な適用。 その間にあなたまたは別の委任先が対象ファイルを変更した場合、何も上書きされません。
• 失敗を正直に報告。 N回の試行後、最後の失敗と保持された worktree が返されます。トランスポートエラーはモデルの FAIL としてではなく、エラーとして報告されます。
• 自動クリーンアップ。 各委任先は、クラッシュしたサーバーが残した llw-* worktree と、24時間を超えて保持されている worktree を削除します。10 MBを超える未追跡ファイルは worktree にコピーされず、スキップされたファイル数が判定結果に示されます。

同梱のスキルでは、Claude が合格する仕様を書く方法を学べます。テストごとに不変条件を1つにすること、context に正確な API サーフェスを含めること、例ではなくプロパティを使うこと、認証や金銭に関わるコードを委任しないことなどです。

結果

Ollama 上で qwen3-coder:30b-a3b-q4_K_M を使い、24 GB GPU（Tesla P40）1台で実行した結果です。

タスク	ローカルで読み取り	Claude に届いた内容
offload：50 KBのテストログから失敗したテストを見つける	約19,100トークン	約130トークン
offload：90 KBのログから ERROR 行を1つ見つける	約30,400トークン	引用された該当行
research：「最新の Node.js LTS とそのサポート終了時期は？」（3ページ）	7,025トークン	出典付きの回答、約250トークン

複数の呼び出しは並列実行されます。1回のターンで3つ実行した場合、所要時間は最も遅い呼び出しと同じでした。

どのモデルを選ぶべきですか？

6種類のタスクで delegate を120回実行した再現可能なベンチマーク（bench/）に基づいています。

モデル	適した用途	1回あたりの速度
qwen3-coder:30b-a3b	最適な標準モデル：パーサー、純粋関数、Python	15～55秒
devstral-small-2:24b	既存ファイルの編集、パーサー	2～9分
granite4.1:8b	控えめなハードウェアで動作する、小規模で仕様が明確な関数	25～90秒

再試行は重要です。失敗時のフィードバックにより、qwen3-coder の合格率は1回目から3回目までに50％上昇しました。offload と research は、これらのどのモデルでもうまく動作します。すべての実行はログに記録されるため（統計を参照）、独自の環境で性能を測定できます。

設定

エージェントは configure を使用してください。人間は JSON を編集できます。設定レイヤーは次の順に適用され、後の設定が優先されます。

1. 組み込みのデフォルト値
2. ユーザー：~/.config/localize/config.json（$XDG_CONFIG_HOME を尊重します）
3. プロジェクト：<git root>/.localize.json
4. 環境変数：LLW_<KEY>。例：LLW_BASE_URL、LLW_MODEL。整数は数字のみ、ブール値は true／false／1／0／yes／no、link_dirs はカンマ区切りのリストまたは JSON 配列、 headers は JSON オブジェクトです。無効な値は無視され、configure の warnings に表示されます。

JSON が無効な設定ファイルは、ファイル名を示すエラーになります。

キー	デフォルト値	意味
base_url	http://localhost:11434	バックエンドのルートです。末尾の /v1 は取り除かれます。
api	auto	auto · ollama · openai。auto は /api/version を確認します。
api_key	""	Authorization: Bearer として送信されます。(set) と表示され、値が出力されることはありません。プラグインのユーザーは、代わりにプラグインの設定で指定できます。その場合、OS のキーチェーンに保存されます。
headers	{}	ゲートウェイ用の追加 HTTP ヘッダーです。例：{"X-Api-Key": "..."}。値は (set) と表示されます。
model	""	両方のツールで使用するデフォルトモデルです。
offload_model	""	offload のモデルを上書きします（例：長いコンテキスト用）。
delegate_model	""	delegate のモデルを上書きします（例：コーダー用）。
research_model	""	research のモデルを上書きします（例：長いコンテキスト用）。
search_url	""	research 用の SearXNG インスタンスです（JSON 出力を有効にする必要があります）。
research_sources	3	research が検索ごとに読み込むページ数です（最大 10）。
page_timeout_ms	30000	ページのダウンロードおよび検索ごとのタイムアウトです。
allow_private_urls	false	research がループバック、リンクローカル、またはプライベートアドレスのページを読み込めるようにします（search_url 自体は常に許可されます）。
num_ctx	32768	コンテキストウィンドウです（Ollama）。
max_tokens	8192	回答ごとの出力上限です。両方の API に送信されます（Ollama では num_predict）。途中で切れた回答は切断されたと報告され、テストされません。
keep_alive	""	Ollama のみ：モデルの読み込みを維持する時間です。例："30m" または -1（無期限）。"" の場合はサーバーのデフォルト（5 分）が使われます。
concurrency	4	サーバープロセスごとの、同時に処理中となる LLM リクエストの最大数です。
timeout_ms	600000	LLM リクエストごとのタイムアウトです。スロットの取得時点から計測されます。
test_timeout_ms	600000	テスト／コマンドの実行ごとのタイムアウトです。
max_attempts	3	delegate のラウンド数です（上限 10）。
link_dirs	node_modules, .venv, venv, vendor	各ワークツリーにシンボリックリンクされます。
log_path	~/.localize/runs.jsonl	実行ログです。"" で無効になります。
auto_use	offload, research	短いセッション開始時のリマインダーを通じて、Claude が自動的に使用するツールです。delegate はオプトインです。ツールはどれも、依頼すれば引き続き使用できます。[] でリマインダーを無効にできます。

// configure — no args: effective config, value sources, backend, model list
// configure — change settings (null removes a key):
{ "set": { "model": "qwen3-coder:30b", "num_ctx": 65536 }, "scope": "user" }

モデルが設定されていない場合、バックエンドにモデルが 1 つだけあればそれを使用し、そうでなければモデル一覧を表示して失敗します。推測は行いません。推測したモデルが埋め込みモデルである可能性があるためです。

バックエンド

バックエンド	base_url	API
Ollama	http://localhost:11434	ネイティブの /api/chat。OpenAI エンドポイントは num_ctx を無視し、長いプロンプトを警告なく切り詰めます。
llama.cpp llama-server	http://localhost:8080	/v1/chat/completions
LM Studio	http://localhost:1234	/v1/chat/completions
vLLM	http://localhost:8000	/v1/chat/completions
LocalAI など	お使いのエンドポイント	/v1/chat/completions

Ollama（GPU）および llama.cpp llama-server（CPU のみ）で、エンドツーエンドの動作を検証済みです。推論モデルの <think> ブロックは取り除かれます。バックエンドが送信されたプロンプトの一部しか読み込めなかった場合、その旨が結果に表示されます。

ツールリファレンス

offload：ローカルで読み取り、簡潔に回答

引数
task	必須。 質問です。
files	git ルートからの相対パスです。ルート内に収める必要があります。
command	標準出力と標準エラーを読み取り対象とするシェルコマンドです（例：npm test 2>&1）。
model	上書きします。

回答に収まりきらない読み取り対象は途中で切り詰められます（先頭と末尾は保持され、テキストに応じたサイズになります）。切り詰められたことは報告されます。

research：ウェブをローカルで検索・閲覧し、出典付きで回答

引数
question	必須。 調査する質問です。
query	質問とは異なる検索クエリを使う場合の検索語です。
urls	検索の代わりに閲覧するページです（search_url は不要です）。
max_sources	検索時に閲覧するページ数（1～10）です。
model	上書きします。

ループバック、リンクローカル、またはプライベートアドレスに解決されるページ URL は、すべてのリダイレクト先でも拒否されます。ただし、allow_private_urls が true の場合を除きます。ページを並列に取得し、ページの取得に失敗した場合（404、PDF、JavaScript のみ）には、検索結果をさらにたどります。各ページは読みやすいテキストに変換され、<main>／<article> が優先され、ナビゲーション、フッター、スクリプトは削除されます。その後、ページの内容は num_ctx の予算内に収められます。検索には SearXNG インスタンスが必要です。 docker run -d -p 8888:8080 searxng/searxng を実行し、settings.yml の search.formats に json を追加してから、search_url を http://localhost:8888 に設定します。

delegate：テストに合格するまで単一のファイルを作成

引数
spec	必須。 ファイルに実行させる内容です。
target_file	必須。 作成または変更する単一のファイルです。
test_command	必須。 プラットフォームのシェル（Windows では sh -c または cmd.exe /d /s /c）でワークツリー内で実行します。終了コード 0 は合格を示します。タイムアウト時には、プロセスツリー全体が強制終了されます。
properties	各ゲートテストにつき 1 つの不変条件です。
context	ファイルで使用できる正確な API サーフェスです。
test_files	対象ファイルをこれらのファイルにすることはできません。
max_attempts, model	上書きします。
show_code	コードも返します（デフォルトは false で、これが節約につながります）。
apply	合格したファイルをチェックアウトにコピーします（デフォルトは true）。

configure：設定を確認・変更

引数を指定しないとレポートを返します。{ "set": {...}, "scope": "user" | "project" } は検証して書き込みます。 不明なキーがある場合は、有効なキーの一覧とともに拒否されます。

統計

実行ごとに、log_path に 1 行が追加されます。

{"ts":"2026-10-04T17:51:28.476Z","tool":"delegate","model":"qwen3-coder:30b-a3b-q4_K_M","api":"ollama","ok":true,"attempts":1,"in_tok":201,"out_tok":195,"ms":57909}

jq -s 'group_by(.tool) | map({tool: .[0].tool, runs: length, ok: (map(select(.ok)) | length), out_tok: (map(.out_tok) | add)})' ~/.localize/runs.jsonl

FAQ

Claude は生成されたコードを見ることがありますか？ Claude が要求した場合（show_code: true）またはファイルを読み込んだ場合に限ります。重要なものをマージする前に、必ずレビューしてください。テストの合格はゲートであり、コードレビューではありません。

何を委任すべきではありませんか？ 認証、金銭、権限、セキュリティ、そして仕様に唯一の正解がないものです。スキルも Claude にこのことを伝えます。

ローカルモデルがテストを不正に通過することはありますか？ テストのソースを見ることはありません。書き込めるのは対象ファイル 1 つだけで、そのファイルを指定した test_files に含めることはできません。

長時間の delegate または research 呼び出しが途中で打ち切られます。 サーバーはクライアントが要求した場合（progressToken）に 15 秒ごとに MCP 進行状況通知を送信しますが、それが役立つかどうかはクライアントによります。

クライアント	ツール呼び出しの制限	設定項目
Claude Code	デフォルトでは実用上の実行時間制限はありません（約 28 時間）。stdio 呼び出しは応答も進行状況通知もない状態が 30 分続くと中断されますが、ハートビートによってこれを防げます	MCP_TOOL_TIMEOUT（ミリ秒、ハードリミット。進行状況通知によって延長されません）、CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT（ミリ秒、0 で無効化）、または .mcp.json の "timeout"
Claude Desktop	ローカルサーバーでは約 60 秒。進行状況通知によってリセットされません	既知の設定項目はありません。Claude Code から長時間のジョブを実行するか、max_attempts と research_sources を小さくしてください
Cursor	約 60 秒。進行状況通知によってリセットされないとの報告があります	既知の設定項目はありません

コードはどこかに送信されますか？ 設定した base_url にのみ送信されます。デフォルトは localhost です。research は検索クエリを独自の SearXNG に送信し、公開ページをダウンロードします。ファイルが送信されることはありません。

開発

npm test   # 88 tests, fake backend + fake web, no LLM or network needed

src/index.js は stdio JSON-RPC サーバーです。src/worker.js には設定、バックエンドクライアント、ツール、失敗抽出機能が含まれています。

リリースは自動で行われます。main へのプッシュごとにテストを実行し、出現箇所すべてのパッチバージョンを更新します（ローカルでは npm run bump で同じ処理を実行できます。さらに minor、major、または x.y.z を指定できます）。その後、タグを付けて GitHub Release を作成します。

ロードマップ

• SearXNG に加えて、検索バックエンド（Brave、Tavily）を追加
• 複数ファイルの委任
• タスクごとのモデルルーティング
• 60 秒のツール制限があるクライアント（Claude Desktop、Cursor）向けの非同期ジョブ API

ライセンス

MIT © Johannes Tebbert

JoblessJoe のロゴ（.claude-plugin/icon.png）はこのライセンスの対象外です。すべての権利を保有します。