Llama Hot Swap

mcp-llama-swap

実行中の Claude Code セッション内で llama.cpp のモデルをホットスワップできます。コンテキストは失われません。コマンドは 1 つです。

推論モデルで計画し、コーディングモデルで実装します。同じセッション、同じコンテキストで、手作業は一切不要です。

macOS（launchctl）と Linux（systemd）に対応しています。

その理由

ローカル LLM を使う場合、高性能な推論モデルと高速なコーディングモデルのどちらかを選ぶ必要があります。1 台のマシンで両方を読み込むことはできません。モデルを手動で切り替えると、会話のコンテキストと流れが失われます。

mcp-llama-swap は、システムのサービスマネージャー（macOS では launchctl、Linux では systemd）を介して llama-server のモデルを切り替えるツールを Claude Code に提供することで、この問題を解決します。クライアント側の会話履歴はすべて保持されます。

クイックスタート

インストール

# Option A: Run directly with uvx (no install needed)
uvx mcp-llama-swap

# Option B: Install from PyPI
pip install mcp-llama-swap

Claude Code の設定

~/.claude.json に追加します：

{
  "mcpServers": {
    "llama-swap": {
      "command": "uvx",
      "args": ["mcp-llama-swap"],
      "env": {
        "LLAMA_SWAP_CONFIG": "/path/to/config.json"
      }
    }
  }
}

モデルの設定

config.json を作成します（macOS）：

{
  "plists_dir": "~/.llama-plists",
  "health_url": "http://localhost:8000/health",
  "health_timeout": 30,
  "models": {
    "planner": "qwen35-thinking.plist",
    "coder": "qwen3-coder.plist",
    "fast": "glm-flash.plist"
  }
}

Linux の場合：

{
  "services_dir": "~/.llama-services",
  "health_url": "http://localhost:8000/health",
  "health_timeout": 30,
  "models": {
    "planner": "llama-server-planner.service",
    "coder": "llama-server-coder.service"
  }
}

使用方法

Claude Code 内で：

You: list models
You: swap to planner
You: <discuss architecture, define interfaces>
You: swap to coder and implement the plan

これで完了です。モデルを切り替えてもコンテキストは保持されます。

新しいモデル設定を直接生成することもできます：

You: create a model config named "reasoning" for /models/qwen3-30b.gguf with 8192 context

仕組み

Claude Code CLI
    |
    | Anthropic Messages API
    v
LiteLLM Proxy (:4000)         <-- translates Anthropic -> OpenAI format
    |
    | OpenAI Chat Completions API
    v
llama-server (:8000)          <-- model weights swapped via service manager
    ^
    |
mcp-llama-swap                <-- this project (launchctl or systemd)

Claude Code は Anthropic 形式を使用します。LiteLLM は llama-server 用に OpenAI 形式へ変換します。この MCP サーバーは、launchctl（macOS）または systemd（Linux）を介して、どのモデルサービスを読み込むかを管理します。

Claude Code はクライアント側でメッセージ履歴をすべて保持し、リクエストごとに再送信するため、モデルを切り替えても会話のコンテキストは維持されます。

モデルの設定

マッピングモード（推奨）

モデルにエイリアスを定義します。マッピングされたモデルのみが利用できます。ディレクトリ内にあるその他のサービス設定は無視されます。

macOS：

{
  "plists_dir": "~/.llama-plists",
  "health_url": "http://localhost:8000/health",
  "health_timeout": 30,
  "models": {
    "planner": "qwen35-35b-a3b-thinking.plist",
    "coder": "qwen3-coder.plist",
    "fast": "glm-4-7-flash.plist"
  }
}

Linux：

{
  "services_dir": "~/.llama-services",
  "health_url": "http://localhost:8000/health",
  "health_timeout": 30,
  "models": {
    "planner": "llama-server-planner.service",
    "coder": "llama-server-coder.service"
  }
}

エイリアスを使って切り替えます：「coder に切り替えて」「planner に切り替えて」。

ディレクトリモード

"models": {} を設定すると、すべてのサービス設定が自動検出されます。ファイル名（拡張子を除く）がエイリアスになります。

macOS：

{
  "plists_dir": "~/.llama-plists",
  "models": {}
}

Linux：

{
  "services_dir": "~/.llama-services",
  "models": {}
}

MCP ツール

ツール	説明
list_models	設定済みのすべてのモデルと、読み込み状況および現在のモードを一覧表示します
get_current_model	現在読み込まれているモデルのエイリアスを返します
swap_model	現在のモデルをアンロードし、指定したモデルを読み込んで、ヘルスチェックを待ちます
create_model_config	モデル用の新しい launchd plist（macOS）または systemd unit（Linux）を生成します

MCP リソース

リソース	説明
llama-swap://config	現在の設定を JSON 形式で表示します
llama-swap://status	現在のモデルの状態、ヘルス、プラットフォーム情報を表示します

MCP プロンプト

プロンプト	説明
swap-workflow	計画してから実装する、ガイド付きワークフローテンプレート

セットアップガイド

前提条件

• macOS と launchctl、または Linux と systemd
• llama-server（llama.cpp）がインストールされていること
• サービスファイル（launchd plist または systemd unit）としてのモデル設定
• Python 3.10+
• LiteLLM プロキシを参照するように設定された Claude Code CLI

1. mcp-llama-swap をインストールする

pip install mcp-llama-swap

2. LiteLLM プロキシをインストールして起動する

pip install litellm

litellm_config.yaml を作成します：

model_list:
  - model_name: "*"
    litellm_params:
      model: "openai/*"
      api_base: "http://localhost:8000/v1"
      api_key: "sk-none"

litellm_settings:
  drop_params: true
  request_timeout: 300

起動します：

litellm --config litellm_config.yaml --port 4000

macOS では、付属の ai.litellm.proxy.plist.template を使って、永続的な launchd サービスとして実行できます（setup.sh を参照）。

3. Claude Code が LiteLLM を参照するように設定する

~/.zshrc（macOS）または ~/.bashrc（Linux）に追加します：

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="sk-none"
export ANTHROPIC_MODEL="local"

4. Claude Code に MCP サーバーを追加する

~/.claude.json に追加します：

{
  "mcpServers": {
    "llama-swap": {
      "command": "uvx",
      "args": ["mcp-llama-swap"],
      "env": {
        "LLAMA_SWAP_CONFIG": "/absolute/path/to/config.json"
      }
    }
  }
}

5. config.json を作成する

config.example.json（macOS）または config.example.linux.json（Linux）をコピーし、モデルのエイリアスとサービスのファイル名を編集します。

6. モデルサービスの設定ファイルを作成する

サービスの設定ファイルは手動で作成することも、Claude Code 内で create_model_config MCP ツールを使用して作成することもできます。

You: create a model config named "coder" for /path/to/model.gguf with 8192 context

これにより、サービスディレクトリに適切な launchd plist（macOS）または systemd ユニットファイル（Linux）が生成されます。

自動セットアップ（macOS）

macOS で一括セットアップする場合は、このリポジトリをクローンして、次のコマンドを実行します。

git clone https://github.com/oussama-kh/mcp-llama-swap.git ~/mcp-llama-swap
cd ~/mcp-llama-swap
chmod +x setup.sh
./setup.sh

このスクリプトは仮想環境を作成し、依存関係をインストールして、LiteLLM の launchd サービスを設定し、追加する正確な設定内容を表示します。

設定リファレンス

config.json のフィールド：

フィールド	デフォルト	説明
services_dir	~/.llama-plists（macOS）/ ~/.llama-services（Linux）	モデルサービスの設定ファイルを格納するディレクトリ
plists_dir	—	macOS における services_dir の別名（後方互換性のため）
units_dir	—	Linux における services_dir の別名
health_url	http://localhost:8000/health	llama-server のヘルスチェックエンドポイント
health_timeout	30	読み込み後、ヘルスチェックを待つ秒数
models	{}	エイリアスとファイル名の対応表。空の場合はディレクトリモード
platform	auto	サービスマネージャー：auto、launchctl、または systemd
launchctl_mode	legacy	macOS のみ：legacy（load/unload）または modern（bootstrap/bootout）

LLAMA_SWAP_CONFIG 環境変数で設定ファイルのパスを上書きできます。

プラットフォームの詳細

macOS（launchctl）

モデルは plist ファイルを使った launchd サービスとして管理されます。launchctl には 2 つのモードがあります。

• Legacy（デフォルト）：launchctl load/unload/list を使用します。すべての macOS バージョンで動作します。
• Modern：launchctl bootstrap/bootout/print を使用します。新しい macOS で公式にサポートされている API です。設定ファイルで "launchctl_mode": "modern" を指定すると有効になります。

Linux（systemd）

モデルは systemd ユーザーサービスとして管理されます。services_dir 内のユニットファイルは ~/.config/systemd/user/ にシンボリックリンクされ、systemctl --user start/stop で管理されます。

トラブルシューティング

LiteLLM が正しく翻訳しない場合： /tmp/litellm.stderr.log を確認します。llama-server が実行中であることを確認します：curl http://localhost:8000/health。

モデルの切り替えがタイムアウトする場合： config.json の health_timeout を大きくします。大きなモデルでは、重みをメモリに読み込むのに 30 秒以上かかる場合があります。

Claude Code が MCP サーバーを見つけられない場合： LLAMA_SWAP_CONFIG のパスが絶対パスであることを確認します。直接テストします：python -m mcp_llama_swap。

マッピングされたモデルが見つからない場合： models 内のサービスファイル名が、サービスディレクトリ内の実際のファイル名と一致している必要があります。

systemd サービスが起動しない場合： journalctl --user -u llama-server-<name> でエラーを確認します。llama-server が PATH に含まれていることを確認します。

launchctl の modern モードで問題が発生する場合： bootstrap/bootout コマンドが失敗する場合は、設定ファイルで "launchctl_mode": "legacy" に切り替えます。

開発

# Install with test dependencies
pip install -e ".[test]"

# Run tests
pytest -v

ユースケース

このプロジェクトでは、ローカルのハードウェアだけで完結する、2 フェーズの AI コーディングワークフローを実現します。

1. 計画フェーズ： 推論モデル（例：思考機能を備えた Qwen3.5-35B-A3B）を読み込みます。アーキテクチャについて検討し、インターフェースを定義し、要件を分割します。
2. 実装フェーズ： コーディングモデル（例：Qwen3-Coder-30B）に切り替えます。計画フェーズの会話コンテキストをすべて引き継ぎ、計画をファイルごとに実行します。

クラウド API は不要です。データがマシンの外に出ることもありません。フェーズ間でコンテキストが失われることもありません。

ライセンス

Apache-2.0