localagents

Claude Code의 잡일을 직접 보유한 하드웨어에서 실행되는 모델에 넘기세요.

localagents는 Claude Code에 run_agent 도구를 제공하는 MCP 서버입니다. 호출할 때마다 전체 헤드리스 Claude Code 세션이 시작됩니다. 동일한 도구, 동일한 CLAUDE.md, 동일한 작업 트리 — 단, API 트래픽은 Anthropic 대신 직접 실행하는 llama.cpp 또는 vLLM 서버로 전송됩니다. Claude가 지시문을 작성하고, 로컬 모델이 작업을 수행하며, Claude가 결과를 검토합니다. Anthropic 토큰 예산은 필요한 부분에만 사용됩니다.

단일 GPU의 27B Qwen은 "이 모듈에 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와 백엔드 사이의 심(shim). 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을 보유하여 레지스트리를 재정의할 수 있습니다.

단일 프로젝트로 제한하려면 해당 프로젝트의 .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 또는 glob), 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 항목을 넣습니다 — 스킬 목록, 토큰 예산 표시, 그리고 턴마다 하나 더. Qwen의 채팅 템플릿은 거부합니다: "System message must be at the beginning". 심은 각각을 인접한 사용자 메시지에 <system>…</system> 텍스트 블록으로 제자리에 접습니다. 대신 최상위 system 필드로 올리면 매 턴 프롬프트 시작이 변경되어 서버의 KV-캐시 접두사가 무효화되고 전체 ~35k 토큰 프롬프트가 매번 재평가됩니다(27B에서 턴당 21–47초). 제자리에 접으면 프롬프트가 추가 전용으로 유지됩니다: llama-server 로그에서 f_sim_best 0.88–0.99, 턴당 2.5–14초.

컨텍스트 오버플로. Claude Code는 인식하지 못하는 모델에 대해 200k 창을 가정합니다. 더 작은 슬롯에서는 llama.cpp의 exceed_context_size_error가 발생하고, 이를 이해하지 못해 작업이 중단됩니다. 다음 섹션을 참조하세요.

심이 하는 모든 것은 필요하지 않을 때 no-op이며, 모든 요청은 타이밍, 메시지 수, 바이트 크기, 보고된 사용량과 함께 기록됩니다.

컨텍스트 창

두 계층이 세션을 실제 창 안에 유지합니다:

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이므로 그렇지 않으면 0이 되기 때문입니다.

2. 요청이 여전히 오버플로되면 심은 백엔드 오류를 Anthropic의 prompt is too long: N tokens > M maximum으로 다시 작성하며, Claude Code는 압축하고 재시도하여 응답합니다.

64k에서는 작동하지만 심하게 반복됩니다: Claude Code의 ~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가 두 번째 에이전트가 지금 실행될지 대기할지 알 수 있습니다. /metrics가 켜져 있으면 각 작업은 처리된 프롬프트 토큰 대 캐시, 캐시 적중률, 프롬프트 및 생성 tok/s, 추측 디코딩 수용을 기록합니다 — 카운터는 서버 전체이므로 겹치는 작업이 델타를 공유합니다.

• vLLM: vllm serve <model> --served-model-name <alias> --enable-auto-tool-choice --tool-call-parser <parser>. 세션은 CLAUDE_CODE_ATTRIBUTION_HEADER=0으로 시작됩니다. 요청별 속성 해시가 접두사 캐싱을 무효화하기 때문입니다.

• 작업의 첫 턴은 콜드 슬롯에서 약 20k 토큰의 프롬프트 비용이 듭니다(시스템 프롬프트 + 도구 스키마), 27B에서 ~10초. 그 이후는 캐시 적중과 델타입니다.

개발

uv sync --dev
uv run pytest -q

레이아웃과 실제 서버에 대한 변경 사항 테스트 방법은 CONTRIBUTING.md를 참조하세요.

라이선스

MIT. LICENSE를 참조하세요.

Copyright © 2026 Chris Cebelenski