localagents

Erledige Claude Codes lästige Arbeit mit einem Modell, das auf deiner eigenen Hardware läuft.

localagents ist ein MCP-Server, der Claude Code ein run_agent-Tool gibt. Jeder Aufruf startet eine vollständige headless Claude-Code-Sitzung – gleiche Tools, gleiche CLAUDE.md, gleicher Arbeitsbaum – nur dass der API-Verkehr zu einem llama.cpp- oder vLLM-Server geht, den du betreibst, statt zu Anthropic. Claude schreibt die Aufgabenbeschreibung, das lokale Modell erledigt die Arbeit, Claude prüft das Ergebnis. Dein Anthropic-Token-Budget fließt in die Teile, die es brauchen.

Ein 27B-Qwen auf einer GPU ist durchaus in der Lage, „Füge diesem Modul eine CLI hinzu und passende Tests“; Opus ist besser für das Designgespräch aufgehoben als für das Beobachten von pytest. Zwei lokale Agenten parallel können die beiden Hälften eines Pakets gegen eine festgelegte Schnittstelle bauen.

Status: früh. Es funktioniert, ich nutze es täglich, und die Schnittstelle wird sich ändern. Es zielt speziell auf llama.cpp und vLLM; Ollama ist kein Ziel.

So funktioniert es

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)

Drei Dinge machen das zu mehr als einer Umgebungsvariable:

1. Eine Registry, die live abgefragt wird. models.yaml listet auf, wo Server sind, und ein Menü von Modellnamen. Was jeder Server gerade tatsächlich ausliefert, sein echtes Kontextfenster und wie viele Slots belegt sind, wird bei jedem Aufruf ermittelt. Du bringst Modelle von Hand hoch und runter – der Server startet nie etwas – und wenn Claude ein Modell braucht, das nicht läuft, fragt es dich namentlich danach.

2. Ein Shim zwischen Claude Code und dem Backend. Claude Code sendet Dinge, die lokale Chat-Templates ablehnen, und lokale Server scheitern auf Weisen, die Claude Code nicht erkennt. Der Shim behebt beide Richtungen (Details unten) und schreibt pro Job eine requests.jsonl, damit du genau sehen kannst, was über die Leitung ging.

3. Dasselbe Isolationsmodell wie bei Claudes eigenen Subagenten. Standardmäßig arbeitet ein Job in deinem Baum, wie das Agent-Tool. isolation: worktree gibt ihm einen frischen Git-Worktree auf einem local-agent/<job>-Branch, der nur behalten wird, wenn er etwas geändert hat, mit einem Diffstat im Job-Datensatz, damit Claude es als Diff überprüfen kann.

Related MCP server: Ollama MCP Server

Anforderungen

• Python 3.12+ und uv

• Claude Code. Das Agent SDK bündelt sein eigenes claude-Binary, also ist nichts weiter zu installieren.

• Ein Server, der Anthropics /v1/messages spricht:

  • llama.cpp llama-server – starte ihn mit --jinja; füge --slots --metrics hinzu, um Belegung und Cache-Statistiken in der Tool-Ausgabe zu erhalten.

  • vLLM mit --enable-auto-tool-choice --tool-call-parser <parser>.

• Ein Modell, das Claude Code tatsächlich steuern kann: solides natives Tool-Calling und ein Kontextfenster von 128k oder mehr pro Anfrage. Qwen3.8-27B funktioniert gut. Kleinere Fenster funktionieren, aber kompaktieren ständig; siehe Kontextfenster.

Installation

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"

Benutzerweite Gültigkeit bedeutet, dass jedes Projekt den local-Server bekommt. Er erbt das aktuelle Arbeitsverzeichnis der Claude-Code-Sitzung, die ihn gestartet hat, also verwendet run_agent standardmäßig den Baum dieses Projekts. Ein Projekt kann eine eigene ./models.yaml mitbringen, um die Registry zu überschreiben.

Wenn du es lieber auf ein Projekt beschränken möchtest, füge dies in die .mcp.json dieses Projekts ein:

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

Starte Claude Code neu (oder /mcp → reconnect), nachdem du es hinzugefügt hast; MCP-Server werden beim Start geladen.

Verwendung

Claude nimmt es wie jedes Tool auf. Frag danach beim Namen, und es wird das Richtige tun:

Verwende den lokalen Agenten, um dem CLI ein --json-Flag hinzuzufügen und es in den Tests abzudecken.

Was Claude dahinter tut: list_models, um zu sehen, was läuft, run_agent(task=…), das eine Job-ID zurückgibt, dann wait_job / job_status / job_log, bis es fertig ist, dann liest es files_touched (oder den Worktree-Diff) und prüft die Arbeit. Jobs, die das 2-Minuten-Tool-Timeout von Claude Code überleben, werden im Hintergrund weitergeführt und später wieder aufgenommen; du musst nichts tun.

Wenn nichts Passendes läuft, wirst du gebeten, eines zu starten:

qwen3.8-27b läuft nirgendwo. Bitte den Benutzer, es hochzufahren. Hinweise: Standard-Mittelklasse-Coder auf llama.cpp; mit --reasoning on ausführen

Starte es wie gewohnt, sag „es läuft“, und Claude versucht es erneut.

Tools

Job-Datensätze liegen in ~/.local/state/localagents/jobs/<job>/: transcript.txt (was der Agent gesagt und getan hat), events.jsonl (jede SDK-Nachricht), requests.jsonl (jede Backend-Anfrage mit Zeit, Größe und Nutzung) und requests_full.jsonl, wenn du das Request-Dumping aktivierst.

Konfiguration: models.yaml

Beginne mit models.example.yaml. Sie wird bei jedem Aufruf neu gelesen, Änderungen wirken also sofort, und der Server überschreibt sie nie – register_* schreibt in eine Sidecar-Datei models.local.yaml, die darüber gemerged wird.

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 sind Orte, die /v1/messages bedienen. Was sie ausliefern, wird abgefragt.

• models sind nur Namen. Ein Name wird unscharf gegen ausgelieferte IDs gematcht (qwen3.8-27b findet unsloth/Qwen3.8-27B-GGUF:UD-Q4_K_XL), also braucht ein Eintrag nichts weiter als notes und vielleicht einen host, um beim Auffordern zum Starten weiterzuleiten. served_name (exakte ID oder Glob), endpoint, context (Fallback-Fenster) und bring_up (ein Startbefehl) existieren als Overrides, falls du sie willst. Startbefehle veralten schnell; ein Name und eine Notiz altern meist besser.

• defaults decken das Standardmodell, permission_mode (acceptEdits), erlaubte und verbotene Tools (Subagenten können keine Subagenten spawnen), welche Claude-Einstellungen geladen werden, max_turns, timeout_s und ein System-Prompt-Suffix ab, das dem Agenten sagt, dass er ein Delegierter ist und wie er berichten soll.

Was der Shim tut

Sowohl llama.cpp als auch vLLM sprechen nativ /v1/messages, also funktioniert es fast, ANTHROPIC_BASE_URL auf sie zu richten. Der Shim schließt die Lücken:

Systemnachrichten mitten im Gespräch. Claude Code platziert role: system-Einträge innerhalb von messages – die Skills-Liste, ein Token-Budget-Marker und einen pro Runde. Qwens Chat-Template lehnt das ab: „System message must be at the beginning“. Der Shim faltet jeden in die angrenzende Benutzernachricht als <system>…</system>-Textblock, an Ort und Stelle. Sie stattdessen in das Top-Level-system-Feld zu heben, ändert den Anfang des Prompts jede Runde, was den KV-Cache-Präfix des Servers ungültig macht und den gesamten ~35k-Token-Prompt jedes Mal neu auswertet (21–47 s pro Runde auf einer 27B). Das Falten an Ort und Stelle hält den Prompt append-only: f_sim_best 0,88–0,99 in llama-servers Log, 2,5–14 s pro Runde.

Kontextüberlauf. Claude Code nimmt für jedes Modell, das es nicht erkennt, ein 200k-Fenster an; mit einem kleineren Slot stößt es auf llama.cpps exceed_context_size_error, den es nicht versteht, und der Job stirbt. Siehe nächster Abschnitt.

Alles, was der Shim tut, ist ein No-op, wenn es nicht gebraucht wird, und jede Anfrage wird mit Zeit, Nachrichtenzahl, Bytegröße und gemeldeter Nutzung protokolliert.

Kontextfenster

Zwei Schichten halten eine Sitzung innerhalb des echten Fensters:

1. Die Abfrage liest es – llama.cpp /props n_ctx (pro Slot: -c geteilt durch --parallel, wenn Unified KV aus ist), vLLM max_model_len – und die Sitzung bekommt CLAUDE_CODE_MAX_CONTEXT_TOKENS. Claude Codes eigenes Auto-Compact feuert dann am richtigen Punkt. Unter 128k wird auch das Ausgabebudget auf n_ctx/8 geschrumpft, weil die Compact-Schwelle window − max_output ist und sonst bei null läge.

2. Wenn eine Anfrage trotzdem überläuft, schreibt der Shim den Fehler des Backends in Anthropics prompt is too long: N tokens > M maximum um, worauf Claude Code mit Kompaktieren und erneutem Versuch antwortet.

Bei 64k funktioniert das, aber es thrasht: Claude Codes ~20k fester Prompt und Tool-Schemas, plus eine ~7k-Token-Kompaktierungszusammenfassung (~55 s auf einer 27B) und die Dateien, die es wieder anhängt, füllen das Fenster innerhalb weniger Runden, und sein Thrash-Guard beendet den Job. Gib jedem Slot 128k oder mehr.

Backend-Hinweise

• llama.cpp: llama-server -hf <gguf> --jinja -fa on --slots --metrics, plus --reasoning on für Denkmodelle und --parallel N für parallele Jobs. Mit /slots an zeigt list_models {total, busy, free}, damit Claude weiß, ob ein zweiter Agent jetzt läuft oder in der Warteschlange steht. Mit /metrics an zeichnet jeder Job verarbeitete vs. gecachte Prompt-Tokens, Cache-Trefferquote, Prompt- und Generierungs-tok/s und Spekulative-Decode-Akzeptanz auf – die Zähler sind serverweit, also teilen sich überlappende Jobs das Delta.

• vLLM: vllm serve <model> --served-model-name <alias> --enable-auto-tool-choice --tool-call-parser <parser>. Die Sitzung wird mit CLAUDE_CODE_ATTRIBUTION_HEADER=0 gestartet, weil der Pro-Anfrage-Attributions-Hash das Prefix-Caching zunichte macht.

• Die erste Runde eines Jobs kostet etwa 20k Tokens Prompt auf einem kalten Slot (System-Prompt plus Tool-Schemas), ~10 s auf einer 27B. Alles danach ist ein Cache-Treffer plus das Delta.

Entwicklung

uv sync --dev
uv run pytest -q

Siehe CONTRIBUTING.md für die Struktur und wie du Änderungen gegen einen echten Server testest.

Lizenz

MIT. Siehe LICENSE.

Copyright © 2026 Chris Cebelenski