localagents

Поручите черновую работу Claude Code модели, работающей на вашем собственном оборудовании.

localagents — это MCP-сервер, который предоставляет Claude Code инструмент run_agent. Каждый вызов запускает полноценную headless-сессию Claude Code — те же инструменты, тот же CLAUDE.md, то же рабочее дерево — за исключением того, что его API-трафик идёт на ваш сервер llama.cpp или vLLM, а не на Anthropic. Claude пишет бриф, локальная модель выполняет работу, Claude проверяет результат. Ваш бюджет токенов Anthropic тратится на те части, которые этого требуют.

Qwen 27B на одной GPU вполне способен на «добавь CLI для этого модуля и тесты к нему»; Opus лучше потратить на проектирование, чем на наблюдение за запуском pytest. Два локальных агента параллельно могут собрать две половины пакета по фиксированному интерфейсу.

Статус: ранний. Работает, я пользуюсь им ежедневно, интерфейс будет меняться. Ориентирован конкретно на 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)

Три вещи делают это чем-то большим, чем переменная окружения:

1. Реестр, который опрашивается в реальном времени. models.yaml перечисляет, где находятся серверы, и меню имён моделей. Что каждый сервер реально обслуживает сейчас, его фактическое контекстное окно и сколько слотов занято — обнаруживается при каждом вызове. Вы поднимаете и опускаете модели вручную — сервер ничего не запускает — и когда Claude нужна модель, которая не запущена, он просит вас назвать её по имени.

2. Прослойка между Claude Code и бэкендом. Claude Code отправляет то, что локальные chat-шаблоны отвергают, а локальные серверы падают так, как Claude Code не распознаёт. Прослойка исправляет оба направления (подробности ниже) и записывает requests.jsonl для каждой задачи, чтобы вы могли видеть, что именно ушло по сети.

3. Та же модель изоляции, что и у собственных субагентов Claude. По умолчанию задача работает в вашем дереве, как инструмент Agent. isolation: worktree даёт ей свежий git worktree на ветке local-agent/<job>, сохраняемый только если она что-то изменила, с 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, которая его запустила, поэтому run_agent по умолчанию использует дерево этого проекта. Проект может нести собственный ./models.yaml для переопределения реестра.

Если вы предпочитаете ограничить его одним проектом, поместите это в .mcp.json этого проекта:

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

Перезапустите Claude Code (или /mcp → reconnect) после добавления; MCP-серверы загружаются при запуске.

Использование

Claude подхватывает его как любой инструмент. Попросите по имени, и он сделает всё правильно:

Используй локального агента, чтобы добавить флаг --json в CLI и покрыть его тестами.

Что Claude делает за кулисами: list_models чтобы узнать, что запущено, run_agent(task=…) который возвращает id задачи, затем wait_job / job_status / job_log пока не завершится, затем читает files_touched (или diff worktree) и проверяет работу. Задачи, переживающие 2-минутный таймаут инструмента Claude Code, уходят в фон и подхватываются позже; вам ничего делать не нужно.

Если ничего подходящего не запущено, вас попросят запустить:

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_* пишут в sidecar 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 или glob), endpoint, context (запасное окно) и bring_up (команда запуска) существуют как переопределения, если они нужны. Команды запуска быстро устаревают; имя и заметка обычно живут дольше.

• defaults покрывают модель по умолчанию, permission_mode (acceptEdits), разрешённые и запрещённые инструменты (субагенты не могут порождать субагентов), какие настройки Claude загружать, max_turns, timeout_s и суффикс системного промпта, сообщающий агенту, что он делегат и как отчитываться.

Что делает прослойка

И llama.cpp, и vLLM говорят на /v1/messages нативно, поэтому указание ANTHROPIC_BASE_URL на них почти работает. Прослойка закрывает пробелы:

Системные сообщения в середине разговора. Claude Code помещает записи role: system внутри messages — список навыков, маркер бюджета токенов и ещё один за каждый ход. Chat-шаблон Qwen отказывается: "System message must be at the beginning". Прослойка сворачивает каждое из них в соседнее пользовательское сообщение как текстовый блок <system>…</system>, на месте. Подъём их в верхнеуровневое поле system вместо этого меняет начало промпта каждый ход, что инвалидирует префикс KV-кэша сервера и заставляет пересчитывать весь промпт ~35k токенов каждый раз (21–47 с на ход на 27B). Сворачивание на месте сохраняет промпт append-only: f_sim_best 0.88–0.99 в логе llama-server, 2.5–14 с на ход.

Переполнение контекста. Claude Code предполагает окно 200k для любой модели, которую не узнаёт; с меньшим слотом он сталкивается с exceed_context_size_error от llama.cpp, который не понимает, и задача умирает. См. следующий раздел.

Всё, что делает прослойка, — no-op, когда это не нужно, и каждый запрос логируется с таймингом, количеством сообщений, размером в байтах и заявленным использованием.

Контекстные окна

Два слоя удерживают сессию в реальном окне:

1. Зонд читает его — llama.cpp /props n_ctx (на слот: -c делённое на --parallel, когда unified KV выключен), 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 ~20k и схемы инструментов, плюс сводка компакта ~7k токенов (~55 с на 27B) и файлы, которые он повторно прикрепляет, снова заполняют окно через несколько ходов, и его защита от тряски завершает задачу. Дайте каждому слоту 128k или больше.

Заметки по бэкендам

• llama.cpp: llama-server -hf <gguf> --jinja -fa on --slots --metrics, плюс --reasoning on для думающих моделей и --parallel N для параллельных задач. С включённым /slots list_models показывает {total, busy, free}, так что Claude знает, запустится ли второй агент сейчас или встанет в очередь. С включённым /metrics каждая задача записывает обработанные токены промпта против кэшированных, коэффициент попадания в кэш, скорость генерации промпта и токенов, и приём спекулятивного декодирования — счётчики общие для сервера, поэтому перекрывающиеся задачи делят дельту.

• vLLM: vllm serve <model> --served-model-name <alias> --enable-auto-tool-choice --tool-call-parser <parser>. Сессия запускается с CLAUDE_CODE_ATTRIBUTION_HEADER=0, потому что хэш атрибуции на каждый запрос ломает префиксное кэширование.

• Первый ход задачи стоит около 20k токенов промпта на холодном слоте (системный промпт плюс схемы инструментов), ~10 с на 27B. Всё после этого — попадание в кэш плюс дельта.

Разработка

uv sync --dev
uv run pytest -q

См. CONTRIBUTING.md для структуры и как тестировать изменения против реального сервера.

Лицензия

MIT. См. LICENSE.

Copyright © 2026 Chris Cebelenski