69 lines
3.7 KiB
Markdown
69 lines
3.7 KiB
Markdown
# 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".
|