localagents

Claude Code の雑務を、自分のハードウェアで動くモデルに任せる。

localagents は、Claude Code に run_agent ツールを提供する MCP サーバーです。呼び出しごとに完全なヘッドレス Claude Code セッションが起動します。ツールも CLAUDE.md も作業ツリーも同じですが、API トラフィックは Anthropic ではなく、自分で実行する llama.cpp または vLLM サーバーに向かいます。Claude が指示を書き、ローカルモデルが作業を行い、Claude が結果をレビューします。Anthropic のトークン予算は、それを必要とする部分にだけ使われます。

1 枚の GPU 上の 27B Qwen は「このモジュールに CLI を追加して、それに合わせたテストを書く」程度の作業は十分にこなせます。Opus は pytest の実行を見守るよりも、設計の会話に使う方が賢明です。2 つのローカルエージェントを並行して動かせば、固定されたインターフェースに対してパッケージの 2 つの半分をそれぞれ構築できます。

ステータス: 初期段階。 動作はしており、毎日使っていますが、インターフェースは変更される予定です。特に llama.cpp と vLLM を対象としています。Ollama は目標ではありません。

仕組み

Claude Code (your session)
   │  MCP: run_agent(task, model=...)
   ▼
localagents ── spawns ──▶ headless `claude` (Agent SDK)
   │                          │  ANTHROPIC_BASE_URL
   │                          ▼
   └──── in-process shim ◀────┘   normalises requests, logs them,
              │                   translates backend errors
              ▼
   llama-server / vllm   (/v1/messages, on your machine or your LAN)

これが単なる環境変数以上のものである理由は、次の 3 つです。

1. ライブでプローブされるレジストリ。 models.yaml にはサーバーの場所とモデル名のメニューがリストされています。各サーバーが現在実際に提供しているもの、実際のコンテキストウィンドウ、ビジーなスロット数は、呼び出しのたびに検出されます。モデルの起動と停止は手動で行います（サーバーが何かを起動することはありません）。Claude が実行されていないモデルを必要とする場合、名前を指定してあなたに尋ねます。

2. Claude Code とバックエンドの間のシム。 Claude Code はローカルのチャットテンプレートが拒否するものを送信し、ローカルサーバーは Claude Code が認識しない方法で失敗します。シムは両方向を修正し（詳細は後述）、ジョブごとに requests.jsonl を書き出すため、ワイヤー上で何が送信されたかを正確に確認できます。

3. Claude 自身のサブエージェントと同じ分離モデル。 デフォルトでは、ジョブは Agent ツールと同様にあなたのツリーで動作します。isolation: worktree を指定すると、local-agent/<job> ブランチ上に新しい git worktree が作成され、何か変更があった場合にのみ保持され、ジョブレコードに diffstat が含まれるため、Claude はそれを diff としてレビューできます。

Related MCP server: Ollama MCP Server

要件

• Python 3.12+ と uv

• Claude Code。Agent SDK には独自の claude バイナリがバンドルされているため、他にインストールするものはありません。

• Anthropic の /v1/messages を話すサーバー:

  • llama.cpp の llama-server — --jinja を付けて起動します。--slots --metrics を追加すると、ツール出力に占有率とキャッシュ統計が含まれます。

  • vLLM は --enable-auto-tool-choice --tool-call-parser <parser> を指定します。

• 実際に Claude Code を駆動できるモデル: 堅牢なネイティブツール呼び出しと、リクエストあたり 128k 以上のコンテキストウィンドウ。Qwen3.8-27B はうまく動作します。ウィンドウが小さいと動作しますが、常にコンパクト化が発生します。コンテキストウィンドウ を参照してください。

インストール

git clone https://github.com/ccebelenski/localagents.git && cd localagents
uv tool install -e .                  # `localagents` on PATH; editable, so repo edits apply
cp models.example.yaml models.yaml    # edit for your servers (gitignored)
claude mcp add --scope user local -- localagents --config "$PWD/models.yaml"

ユーザースコープにすると、すべてのプロジェクトが local サーバーを利用できます。これは、起動した Claude Code セッションの cwd を継承するため、run_agent はデフォルトでそのプロジェクトのツリーを対象とします。プロジェクトは独自の ./models.yaml を配置してレジストリを上書きできます。

1 つのプロジェクトに限定したい場合は、そのプロジェクトの .mcp.json にこれを記述します:

{"mcpServers": {"local": {"command": "localagents", "args": ["--config", "/path/to/models.yaml"]}}}

追加後、Claude Code を再起動（または /mcp → 再接続）してください。MCP サーバーは起動時に読み込まれます。

使用方法

Claude は他のツールと同様にこれを認識します。名前で指定すれば、適切に動作します:

ローカルエージェントを使って CLI に --json フラグを追加し、テストでカバーしてください。

Claude がその背後で行うこと: list_models で状況を確認し、run_agent(task=…) でジョブ ID を取得し、wait_job / job_status / job_log で完了するまで追跡し、files_touched（または worktree の diff）を読んで作業を確認します。Claude Code の 2 分間のツールタイムアウトを超えるジョブはバックグラウンドに移され、後で取得されます。あなたが何かをする必要はありません。

適切なモデルが実行されていない場合は、起動を求められます:

qwen3.8-27b はどこでも実行されていません。ユーザーに起動を依頼してください。 メモ: llama.cpp 上のデフォルトの中型コーダー。--reasoning on で実行

通常どおり起動し、「起きた」と言えば、Claude が再試行します。

ツール

ジョブレコードは ~/.local/state/localagents/jobs/<job>/ に保存されます: transcript.txt（エージェントが言ったことと行ったこと）、events.jsonl（すべての SDK メッセージ）、requests.jsonl（タイミング、サイズ、使用量を含むすべてのバックエンドリクエスト）、そしてリクエストダンプを有効にした場合は requests_full.jsonl も保存されます。

設定: models.yaml

models.example.yaml から始めてください。これは呼び出しのたびに再読み込みされるため、編集はすぐに反映されます。サーバーがこれを書き換えることはありません。register_* はサイドカー models.local.yaml に書き込み、それが上にマージされます。

endpoints:
  llamacpp:
    base_url: http://127.0.0.1:8080
    backend: llama.cpp
  gpu-server:
    base_url: http://gpu-server.lan:8000
    backend: vllm
    host: gpu-server

models:
  qwen3.8-27b:
    notes: default mid-size coder on llama.cpp; run with --reasoning on
  deepseek-v4-flash:
    host: gpu-server
    notes: vllm needs --enable-auto-tool-choice --tool-call-parser deepseek_v3

• endpoints は /v1/messages を提供する場所です。提供される内容はプローブされます。

• models は単なる名前です。名前は提供 ID に対してファジーマッチされます（qwen3.8-27b は unsloth/Qwen3.8-27B-GGUF:UD-Q4_K_XL を見つけます）。したがって、エントリには notes と、起動を依頼するときに中継するための host があれば十分です。served_name（正確な ID またはグロブ）、endpoint、context（フォールバックウィンドウ）、bring_up（起動コマンド）は、必要に応じて上書きとして存在します。起動コマンドはすぐに古くなります。名前とメモの方が長持ちすることが多いです。

• defaults は、デフォルトモデル、permission_mode（acceptEdits）、許可および不許可のツール（サブエージェントはサブエージェントを生成できない）、読み込む Claude 設定、max_turns、timeout_s、そしてエージェントが委任された存在であることと報告方法を伝えるシステムプロンプトのサフィックスをカバーします。

シムが行うこと

llama.cpp と vLLM はどちらも /v1/messages をネイティブに話すため、ANTHROPIC_BASE_URL をそれらに向けるとほぼ機能します。シムはギャップを埋めます:

会話途中のシステムメッセージ。 Claude Code は messages 内に role: system エントリを配置します — スキル一覧、トークン予算マーカー、そしてターンごとに 1 つ追加されます。Qwen のチャットテンプレートはこれを拒否します: "System message must be at the beginning"。シムはそれぞれを隣接するユーザーメッセージに <system>…</system> テキストブロックとして その場で 折り込みます。代わりにトップレベルの system フィールドに持ち上げると、毎ターン prompt の先頭が変わり、サーバーの KV-cache プレフィックスが無効になり、毎回全体の ~35k トークンの prompt が再評価されます（27B で 1 ターンあたり 21–47 秒）。その場で折り込むと prompt は追加専用のままになります: llama-server のログで f_sim_best 0.88–0.99、1 ターンあたり 2.5–14 秒。

コンテキストオーバーフロー。 Claude Code は認識しないモデルには 200k のウィンドウを想定します。スロットが小さいと、llama.cpp の exceed_context_size_error に遭遇しますが、これは理解できず、ジョブは終了します。次のセクションを参照してください。

シムが行うすべてのことは、不要な場合は何もしません。また、すべてのリクエストは、タイミング、メッセージ数、バイトサイズ、報告された使用量とともにログに記録されます。

コンテキストウィンドウ

セッションを実際のウィンドウ内に保つための 2 つの層があります:

1. プローブがそれを読み取ります — llama.cpp の /props の n_ctx（スロットごと: 統合 KV がオフの場合は -c を --parallel で割った値）、vLLM の max_model_len — そしてセッションは CLAUDE_CODE_MAX_CONTEXT_TOKENS を取得します。Claude Code 自身の自動コンパクト化が適切な時点で発動します。128k 未満では、出力予算も n_ctx/8 に縮小されます。コンパクト化のしきい値は window − max_output であり、そうしないとゼロになるためです。

2. それでもリクエストがオーバーフローする場合、シムはバックエンドのエラーを Anthropic の prompt is too long: N tokens > M maximum に書き換えます。Claude Code はこれに応答してコンパクト化し、再試行します。

64k でも機能しますが、スラッシングが発生します: Claude Code の固定 prompt とツールスキーマの約 ~20k、さらに約 ~7k トークンのコンパクト化サマリー（27B で約 55 秒）、再添付されるファイルにより、数ターンでウィンドウが再び埋まり、スラッシングガードがジョブを終了します。各スロットには 128k 以上を割り当ててください。

バックエンドのメモ

• llama.cpp: llama-server -hf <gguf> --jinja -fa on --slots --metrics に加えて、思考モデルには --reasoning on、並行ジョブには --parallel N を指定します。/slots を有効にすると、list_models は {total, busy, free} を表示するため、Claude は 2 番目のエージェントが今すぐ実行されるか、キューに入るかを知ることができます。/metrics を有効にすると、各ジョブは処理された prompt トークンとキャッシュされたトークン、キャッシュヒット率、prompt と生成の tok/s、投機的デコードの受入率を記録します。カウンターはサーバー全体で共有されるため、重複するジョブはデルタを共有します。

• vLLM: vllm serve <model> --served-model-name <alias> --enable-auto-tool-choice --tool-call-parser <parser>。セッションは CLAUDE_CODE_ATTRIBUTION_HEADER=0 で開始されます。リクエストごとの帰属ハッシュがプレフィックスキャッシュを無効にするためです。

• ジョブの最初のターンは、コールドスロットで約 20k トークンの prompt（システムプロンプトとツールスキーマ）を消費し、27B で約 10 秒かかります。それ以降はキャッシュヒットとデルタのみです。

開発

uv sync --dev
uv run pytest -q

レイアウトと、実際のサーバーに対する変更のテスト方法については、CONTRIBUTING.md を参照してください。

ライセンス

MIT。LICENSE を参照してください。

Copyright © 2026 Chris Cebelenski