From 8bdf73b4ce054d8e0469ebfd886f2f2a6ffc6f4f Mon Sep 17 00:00:00 2001
From: dschlueter <dschlueter@kitux.de>
Date: Wed, 20 May 2026 20:03:34 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20CLAUDE.md=20=E2=80=94=20Architektur,=20?=
 =?UTF-8?q?Deploy-Workflow,=20GPU-Setup?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..fa0cd13
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,69 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Was ist dieses Repo?
+
+Eine **TypeScript-Extension** für den [`pi`-Coding-Agent](https://github.com/earendil-works/pi) (`@earendil-works/pi-coding-agent`). Sie implementiert einen automatisierten **Coder → Judge → Fix**-Loop mit zwei lokalen llama.cpp-Servern.
+
+Nach jeder Änderung an `pi-coder-judge-extension.ts` oder `models.json` muss deployed werden:
+
+```bash
+./install.sh     # kopiert nach ~/.pi/agent/extensions/ und ~/.pi/agent/
+# dann in pi agent: /reload
+```
+
+## Server-Lifecycle
+
+```bash
+./start-servers.sh   # beide Container parallel starten (empfohlen, ~1–3 min)
+./start-coder.sh     # nur Coder :8001
+./start-judge.sh     # nur Judge :8002
+./stop-servers.sh    # beide stoppen
+./status.sh          # Container- und HTTP-Status beider Server
+```
+
+Die Start-Skripte stoppen existierende Container automatisch vor dem Neustart.
+
+## Architektur der Extension
+
+`pi-coder-judge-extension.ts` ist die einzige Logikdatei. Sie registriert alle Commands, das `apply_patch`-Custom-Tool und zwei Event-Hooks beim pi-Agent.
+
+**Zwei LLM-Rollen:**
+
+| Rolle | Port | Container | Alias |
+|-------|------|-----------|-------|
+| Coder (Implementierung, Fixes, Doku) | 8001 | `qwen36-27b-coder` | `qwen3.5-coder` |
+| Judge (Review, ShipIt, QuickCheck)   | 8002 | `qwen36-27b-judge` | `qwen3.5-judge` |
+
+Beide nutzen dasselbe GGUF (`Qwen3.6-27B-Uncensored-HauhauCS-Aggressive-IQ4_XS.gguf`), aber unterschiedliche Serverparameter.
+
+**Zentraler Ablauf in `/optimize`:**
+1. `writeTaskMd()` → TASK.md anlegen
+2. Coder: `coderKickoff()` → implementiert + committet
+3. Loop (max. N Runden): Judge → `parseVerdict()` → PASS? → ShipIt. FAIL? → `parseBlockers()` → Fix → nächste Runde
+4. Loop-Erkennung: gleicher Blocker zweimal → Abbruch (`finalNotify()`)
+5. Optional: `runUpdateDoku()` bei `--with-doku`
+
+**`tool_call`-Hook (edit-Reordering):** Sortiert Multi-Edit-Aufrufe auf dieselbe Datei von hinten nach vorne. Verhindert den Fehler „edits[n] doesn't match" wenn mehrere Stellen einer Datei auf einmal geändert werden.
+
+**`apply_patch`-Tool:** Wendet unified diffs via `patch -p1` an — robuster als mehrfache `edit`-Aufrufe bei umfangreichen Änderungen.
+
+**Inkrementelle Dokumentation (`runUpdateDoku`):** Git-Tags (`docs-last-commented`, `docs-last-readme`, `docs-last-bedienungsanleitung`) markieren den letzten Dokumentationslauf. Nur Dateien, die sich seitdem geändert haben, werden neu verarbeitet.
+
+## Modell-Konfiguration (`models.json`)
+
+Fünf Provider: `ollama` (lokale Ollama-Instanz), `llama-cpp` (:8000), `llama-cpp-coder` (:8001), `llama-cpp-judge` (:8002), `openrouter`. Die beiden llama-cpp-\*-Provider werden von der Extension via `switchModel()` automatisch gewechselt — nie manuell setzen wenn die Extension läuft.
+
+Kritische Felder bei llama-cpp-Providern: `contextWindow` muss mit dem `-c`-Parameter im Start-Skript übereinstimmen (aktuell 262144). `maxTokens` begrenzt die Ausgabelänge pro Request.
+
+## Wichtige Invarianten
+
+- **`cancelRequested`** ist eine modulare Variable — sie wird von `/cancel` gesetzt und nach jedem Loop-Schritt in `/optimize` geprüft und zurückgesetzt.
+- **`sendAndWait()`** wartet erst auf `idle`, dann `deliverAs: "followUp"` — verhindert „Agent is already processing".
+- **`tickTaskMdStatus()`** nutzt Python3 für den String-Ersatz in TASK.md (kein Shell-Escaping-Problem).
+- Beide Start-Skripte warten bis zu 90×2 s auf HTTP-Erreichbarkeit und führen dann einen Smoke-Test-Completion durch.
+
+## GPU-Setup
+
+Hardware: 2× RTX 3090 (device=1,2), tensor-split 0.5,0.5. KV-Cache: `q4_0` (25 % des fp16-VRAM — nötig für 262k Kontext auf 2× 24 GB). Für andere GPU-Konfigurationen: README.md Abschnitt „Anpassung".