pi_coder_2/README.md

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 Modell (Standard: Strata), 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  →  Strata (:9090, Coder-Persona)  →  Implementierung + git commit
        │
        ▼
  /judge  →  Strata (:9090, Judge-Persona)  →  Review: PASS / FAIL + Blocker
        │
   FAIL? ▼
  /fix    →  Strata (:9090, Coder-Persona)  →  Fixes + git commit
        │
   PASS WITH CONCERNS? ▼
        │  (ohne --approve-concerns: wie FAIL → weiterer Fix-Zyklus)
        │
   PASS? ▼
  /shipit →  Strata (:9090, 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 (<provider>/<id>)	Port	Betrieb	GPU
Coder + Judge (Standard)	strata/qwen3.8-flash-next-iq3_s	9090	Strata-Server, ~/nvme2n1p7_home/strata-betrieb	1 und 2
Coder + Judge (Alternative)	llama-cpp-single/coding_model (Qwen3.6-27B IQ4_XS)	8001	Container coding_model, start-coding-server.sh	1

Coder- und Judge-Rollen werden durch verschiedene System-Prompts realisiert — dasselbe Modell, unterschiedliche Persona. Freie Eingaben in pi nutzen weiter pis eigenes Standardmodell.

Strata lädt sein Modell bei der ersten Anfrage selbst, gibt vorher die GPUs frei und entlädt es nach 10 Minuten ohne Anfrage (eingerichtet in strata-betrieb). Ein anderes Modell für beide Rollen setzt PI_CODER_MODEL=<provider>/<id>, siehe BEDIENUNGSANLEITUNG.md.

---

Voraussetzungen

• pi installiert (~/.pi/).
• Ein Modell für Coder und Judge:
  • Standard: der lokale Strata-Server auf 127.0.0.1:9090 (Betrieb: ~/nvme2n1p7_home/strata-betrieb).
  • Alternative: der llama.cpp-Server in Docker auf Port 8001 (unten). Dafür Docker mit NVIDIA Container Toolkit, eine GPU mit 24 GB (Standard GPU 1, GPU_DEVICE=…) und das GGUF-Modell unter $HF_HOME/models/qwen3/Qwen3.6-27B-Uncensored-HauhauCS-Aggressive-IQ4_XS.gguf (Standard HF_HOME=/home/dschlueter/nvme2n1p7_home/huggingface).

---

Installation

git clone https://kitux.de/forgejo/dschlueter/pi_coder_2.git ~/pi_coder_v2
cd ~/pi_coder_v2
./deploy-pi-config.sh   # verlinkt Extension und mcp.json, kopiert models.json, übernimmt settings.json (nur packages)

Danach pi im Projektordner starten. Was das Skript genau tut und wie man das Modell wählt: BEDIENUNGSANLEITUNG.md, Kapitel 2.

---

llama.cpp-Server (Alternative)

./start-coding-server.sh          # startet den Container coding_model, wartet bis HTTP bereit (bis 5 min)
GPU_DEVICE=0 ./start-coding-server.sh
./stop-coding-server.sh
./status-coding-server.sh

Ein erneuter Start entfernt einen laufenden Container zuerst (docker rm -f); eine laufende Anfrage bricht dabei ab. Coder und Judge nutzen ihn mit PI_CODER_MODEL=llama-cpp-single/coding_model pi.

---

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-Settings; deploy-pi-config.sh übernimmt daraus nur die Liste packages
mcp.json	MCP-Server für pi (Playwright, Context7), nach ~/.pi/agent/mcp.json verlinkt
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 und mcp.json nach ~/.pi/agent/ verlinken, models.json kopieren, packages aus settings.json übernehmen

---

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: 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.

Wann der Judge welches Urteil gibt (Urteilsregeln, Abschnitt „Hinweise“): siehe BEDIENUNGSANLEITUNG.md, Judge-Persona.

---

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.

---

Documentation

• BEDIENUNGSANLEITUNG.md – Einrichtung, Modellwahl, alle Befehle, MCP-Server, Web-Tests, schneller entwickeln, Fehlermeldungen
• FUNKTIONSWEISE.md – Aufbau der Extension, Ablauf von /optimize, Designentscheidungen, Grenzen
• CHANGELOG.md – Änderungen und was beim Update zu tun ist
• LICENSE – MIT
• Strata-Server und Messwerte auf diesem PC: ~/nvme2n1p7_home/strata-betrieb