pi_coder_2 — Automatisierter Coder/Judge-Workflow für pi agent

Dieses Repository enthält die Konfiguration und Skripte für einen automatisierten Coding-Workflow mit einem lokalen LLaMA-Modell, das abwechselnd als Coder und Judge agiert — gesteuert über Pi Agent. Er dreht solange Optimierungsschleifen, bis das Programm Produktionsreife hat.

---

Überblick

Nutzer gibt Auftrag
        │
        ▼
  /coder  →  coding_model (:8001, Coder-Persona)  →  Implementierung + git commit
        │
        ▼
  /judge  →  coding_model (:8001, Judge-Persona)  →  Review: PASS / FAIL + Blocker
        │
   FAIL? ▼
  /fix    →  coding_model (:8001, Coder-Persona)  →  Fixes + git commit
        │
   PASS WITH CONCERNS? ▼
        │  (ohne --approve-concerns: wie FAIL → weiterer Fix-Zyklus)
        │
   PASS? ▼
  /shipit →  coding_model (:8001, Judge-Persona)  →  Finale Freigabe: SHIP / NO-SHIP
               (nur bei "PASS WITH CONCERNS" --approve-concerns; klares PASS → direkt SHIP)

  /optimize = Coder→Judge→Fix-Schleife automatisch (bis PASS oder max. N Runden)
  --interactive: pausiert nach PASS für menschlichen Checkpoint + optionale Zusatzaufträge

Ein einzelner llama.cpp-Docker-Container bedient beide Rollen. Die Rollenumschaltung (Coder ↔ Judge) erfolgt über unterschiedliche System-Prompts, die der before_agent_start-Hook der Extension vor jeder Inference injiziert. pi agent wechselt keine Server mehr — nur die Persona im System-Prompt ändert sich.

---

Modelle

Rolle	Modell	Port	Container	Alias	GPU
Coder + Judge	Qwen3.6-27B-Uncensored-HauhauCS-Aggressive-IQ4_XS	8001	coding_model	coding_model	device=1

Coder- und Judge-Rollen werden durch verschiedene System-Prompts realisiert — dasselbe Modell, derselbe Container, unterschiedliche Persona.

---

Voraussetzungen

• Docker mit NVIDIA-GPU-Support:

  # NVIDIA Container Toolkit installieren (falls nicht vorhanden)
  distribution=$(. /etc/os-release; echo $ID$VERSION_ID)
  curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
  curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list \
    | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
  sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
  sudo systemctl restart docker
  

• NVIDIA-GPU: empfohlen RTX 3090 (24 GB VRAM). Standard: GPU 1. Überschreibbar mit GPU_DEVICE=0 ./start-coding-server.sh. Bei 3 GPUs: GPU 0 für Display reservieren.
• GGUF-Modell vorhanden unter: $HF_HOME/models/qwen3/Qwen3.6-27B-Uncensored-HauhauCS-Aggressive-IQ4_XS.gguf
  • Standard-Pfad: HF_HOME=/home/dschlueter/nvme2n1p7_home/huggingface
  • Überschreibbar: HF_HOME=/anderer/pfad ./start-coding-server.sh
• pi agent installiert (~/.pi/)

---

Installation

# 1. Repository klonen
git clone https://kitux.de/forgejo/dschlueter/pi_coder.git ~/pi_coder
cd ~/pi_coder

# 2. Extension, Modell-Config und settings.json nach ~/.pi/agent/ deployen
./deploy-pi-config.sh

# 3. pi agent neu laden (in der pi-Oberfläche)
# /reload

# 4. Server starten
./start-coding-server.sh

Das Install-Skript sichert eine vorhandene ~/.pi/agent/settings.json als .bak und kopiert dann settings.json aus dem Repo. Damit ist der korrekte Default-Provider (llama-cpp-single/coding_model) automatisch konfiguriert.

Nach späteren Änderungen an pi-coding-extension.ts oder models.json:

./deploy-pi-config.sh   # kopiert nach ~/.pi/agent/
# dann /reload in pi agent

---

Server starten / stoppen / status

# Server starten (empfohlen — dauert 1–3 Minuten)
./start-coding-server.sh

# Server auf anderer GPU starten
GPU_DEVICE=0 ./start-coding-server.sh

# Stoppen
./stop-coding-server.sh

# Status prüfen
./status-coding-server.sh

start-coding-server.sh startet den Container und wartet bis HTTP-ready (max. 5 Minuten — die neue llama.cpp-Version prüft beim Start, ob Modell + KV-Cache in den VRAM passen, was zusätzliche Zeit kostet).

Wenn der Server bereits läuft und du start-coding-server.sh aufrufst, wird der laufende Container zuerst per docker rm -f gestoppt und dann neu gestartet — ein laufender Inference-Request wird dabei abgebrochen.

---

llama.cpp-Serverparameter im Detail

Parameter des Single-Servers (Port 8001)

Parameter	Wert	Bedeutung
--jinja	—	Verwendet das im GGUF eingebettete Jinja-Chat-Template (Qwen-Format). Notwendig für korrekte <|im_start|>-Tokens.
--reasoning on	—	Aktiviert das interne Thinking-Budget des Modells (Qwen3-spezifisch).
--no-context-shift	—	Kontextfenster wird nicht verschoben wenn es voll ist — stattdessen Fehler. Verhindert stille Datenverluste.
--repeat-penalty 1.05	—	Leichte Penalty für Wiederholungen.
--top-k 20	—	Nur die 20 wahrscheinlichsten nächsten Tokens.
--min-p 0.01	—	Tokens mit Wahrscheinlichkeit < 1 % des wahrscheinlichsten Tokens werden ausgeschlossen.
-ngl 999	—	Alle Layer auf die GPU laden.
-fa on	—	Flash Attention.
--kv-unified	—	Einheitlicher KV-Cache über alle Schichten.
--cache-type-k q4_0	—	KV-Cache Keys 4-Bit quantisiert. Nötig für 256K Kontext auf einer 24-GB-GPU.
--cache-type-v q4_0	—	KV-Cache Values ebenfalls 4-Bit quantisiert.
--cont-batching	—	Continuous Batching.
-c 262144	256K	Großes Kontextfenster für langen Gesprächsverlauf im Optimize-Loop.
-n 16384	16K	Maximale Ausgabelänge.
--temp 0.2	—	Deterministisch — Coder-Rolle. Der Judge-System-Prompt gleicht die etwas höhere Temperatur aus.
--parallel 2	—	2 Slots, damit pi agent Folgeanfragen schnell hintereinander stellen kann.
--gpus '"device=1"'	—	Standard: GPU 1. Überschreibbar: GPU_DEVICE=0 ./start-coding-server.sh.

---

GPU-Konfiguration und VRAM

Aktuelles Setup (1 GPU, 1 Server)

Ein einzelner Container bedient beide Rollen sequenziell:

GPU 0  NVIDIA T600       →  Display / Monitor (nicht für KI genutzt)
GPU 1  RTX 3090 (24 GB)  →  coding_model  (Port 8001, Coder + Judge)

Da Coder und Judge nicht gleichzeitig inferieren, gibt es keinen VRAM-Konflikt. Die Umschaltung zwischen den Rollen erfolgt ausschließlich über den System-Prompt — der Container läuft ohne Unterbrechung durch.

VRAM-Abschätzung für das 27B IQ4_XS-Modell

Komponente	Größe (ca.)
Modell-Gewichte (IQ4_XS, 27B)	~14 GB
KV-Cache bei 262 144 Tokens (q4_0)	~8–10 GB
KV-Cache bei 131 072 Tokens (q4_0)	~4–5 GB
KV-Cache bei 65 536 Tokens (q4_0)	~2–3 GB
Summe (262k Kontext)	~22–24 GB

Bei einer 24-GB-GPU ist 262k Kontext knapp kalkuliert. Keine anderen Prozesse dürfen nennenswert VRAM belegen (z. B. TTS-Dienste, Ollama). Prüfen mit:

nvidia-smi --query-gpu=index,memory.used,memory.free --format=csv

Falls der VRAM nicht reicht: Kontext in start-coding-server.sh auf 131072 oder 65536 reduzieren.

Anpassung für andere GPU-Konfigurationen

# Andere GPU verwenden:
GPU_DEVICE=0 ./start-coding-server.sh

# 2 GPUs für einen Server (sehr großer Kontext):
# start-coding-server.sh anpassen:
  --gpus '"device=0,1"' \
  --tensor-split 0.5,0.5 \
  --main-gpu 0 \
  -c 262144

---

Parameter-Tuning-Guide

Temperatur (--temp)

Wert	Eignung
0.0–0.1	Maximale Reproduzierbarkeit.
0.1–0.3	Guter Kompromiss für Coding. Aktuell gesetzt: 0.2.
0.4–0.6	Kreativere Lösungen.
0.7–1.0	Für Coding meist zu viel Rauschen.

Kontextgröße (-c)

Kontext	KV-Cache (q4_0)	Empfehlung
32 768	~1,9 GB	1 × 16-GB-GPU
65 536	~3,7 GB	1 × 24-GB-GPU (konservativ)
131 072	~7,5 GB	1 × 24-GB-GPU
262 144	~8–10 GB	1 × 24-GB-GPU (q4_0) — aktuell gesetzt

KV-Cache-Quantisierung

--cache-type-k/v	VRAM	Qualität
f16	100 % (Basis)	Referenz
q8_0	~50 %	Kaum merklich schlechter
q4_0	~25 %	Merklicher Qualitätsverlust bei langen Kontexten — aber nötig für 256K Kontext auf 24 GB. Aktuell gesetzt.

---

Tests ausführen

./run-tests.sh

Keine npm-Installation nötig — nutzt den integrierten node:test-Runner und --experimental-strip-types für TypeScript. Testet Parsing-Logik, Konfigurationskonsistenz und Extension-Guards gegen Regressionen.

---

Dateien

Datei / Verzeichnis	Zweck
pi-coding-extension.ts	pi agent Extension (Kommandos, Tools, Hooks, Rollen-Logik)
models.json	Provider- und Modell-Konfiguration für pi agent
settings.json	pi-agent-Settings (Default-Modell, aktivierte Modelle) — wird von Install-Skript deployt
run-tests.sh	Tests ausführen
tests/	Testdateien (pure-logic, config, extension-guards, scripts)
start-coding-server.sh	Single-Server starten (Port 8001, Coder + Judge)
stop-coding-server.sh	Container stoppen
status-coding-server.sh	Laufstatus anzeigen
deploy-pi-config.sh	Extension + models.json + settings.json nach ~/.pi/agent/ deployen
examples/	Demo-Projekte (Python, Rust, Go, C, Bash, HTML/JS) für Live-Demos
examples/restore-all.sh	Examples nach Demo-Lauf in Ausgangszustand zurücksetzen

---

pi-Kommandos (Kurzübersicht)

Kommando	Persona	Beschreibung
/coder <auftrag>	Coder	TASK.md anlegen, Implementierung starten
/judge [fokus]	Judge	Code-Review gegen TASK.md + letzten Commit
/fix [hinweis]	Coder	Judge-Kritik beheben, committen
/shipit	Judge	Finale Freigabeprüfung
/optimize <auftrag> [--rounds N] [--with-doku] [--continue] [--interactive]	beide	Vollautomatische Schleife bis PASS (Standard: 2 Runden)
/optimize ... [--no-tests] [--approve-concerns] [--test-cmd "cmd"] [--test-timeout N]	beide	Test-Erkennung überspringen / PASS WITH CONCERNS akzeptieren
/patch <änderung>	Coder	Gezielte Minimaländerung ohne Review
/quick_check [was]	Judge	Schnelle Prüfung der letzten Änderung
/version	—	Versionsnummer erhöhen (SemVer + Git-Tag)
/update_doku	Coder	Code kommentieren + README + Bedienungsanleitung + LICENCE.md
/plan <auftrag>	Coder	Implementierungsplan in PLAN.md (kein Code)
/continue	Coder	Unterbrochenen Prozess fortsetzen
/cancel	—	Laufenden Loop nach aktuellem Schritt abbrechen
/new_project <pfad>	—	Neues Projektverzeichnis + git init

Ausführliche Beschreibung aller Kommandos mit Beispielen: siehe BEDIENUNGSANLEITUNG.md.

---

PASS WITH CONCERNS — Verhalten

Im /optimize-Loop gilt PASS WITH CONCERNS nicht als bestanden — der Coder erhält einen weiteren Fix-Auftrag, genau wie bei FAIL. Erst sauberes PASS beendet die Schleife.

Opt-out: --approve-concerns lässt PASS WITH CONCERNS als bestanden gelten.

---

Live-Aktivitätsstatus

Während der Ausführung zeigt pi_coder in der Statuszeile, was gerade passiert — inklusive eines laufenden [MM:SS]-Timers während jeder LLM-Inference-Phase:

Situation	Anzeige
Coder implementiert	◉ Coder implementiert: Login-Flow mit JWT [01:23]
edit-Tool aktiv	Editiere src/main.py…
git commit	Git-Commit…
Judge (Runde 1)	◉○ Runde 1/2: Judge — TASK.md + letzter Commit + Tests [00:47]
Judge (Runde 2)	●◉ Runde 2/2: Judge — TASK.md + letzter Commit + Tests [02:15]
Tests laufen	●○ Runde 1/2: Tests laufen (pytest, max. 120s)…
Fix-Phase	●◉ Runde 2/2: Coder fixt — fehlendes Null-Check [01:05]
ShipIt	●●◉ ShipIt — finale Freigabe [00:33]
Interactive-Pause	⏸ PASS – warte auf /continue…

Der Timer beweist, dass die LLM tatsächlich arbeitet. Steht er still, hängt der Prozess.