pi_coder_2/README.md

> **Archiviert seit 16.10.2026.** Abgelöst durch **pi_coder v3** in `~/pi_coder_v3`
> (Forgejo `https://kitux.de/forgejo/dschlueter/pi_coder_v3`). Dieser Stand wird nicht mehr gepflegt; pi lädt die
> Erweiterung inzwischen aus `~/pi_coder_v3`.

# 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](BEDIENUNGSANLEITUNG.md#modell-wählen).

---

## Voraussetzungen

- [pi](https://pi.dev) 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

```bash
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](BEDIENUNGSANLEITUNG.md#2-vorbereitung).

---

## llama.cpp-Server (Alternative)

```bash
./start-coding-server.sh          # startet den Container coding_model, wartet bis HTTP bereit (bis 5 min)
GPU_DEVICE=2 ./start-coding-server.sh   # die zweite RTX 3090 statt GPU 1
./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 (RTX 3090). Überschreibbar: `GPU_DEVICE=2 ./start-coding-server.sh` (zweite RTX 3090). GPU 0 (T600, 4 GB) ist für das Modell zu klein. |

---

## GPU-Konfiguration und VRAM

### GPU-Belegung auf diesem Rechner

```
GPU 0  NVIDIA T600 (4 GB)    →  Display; Bild-Encoder von Strata (strata-vision, rund 1,1 GB)
GPU 1  RTX 3090 (24 GB)      →  Strata, erste Hälfte der Schichten (Standardmodell für Coder + Judge)
GPU 2  RTX 3090 (24 GB)      →  Strata, zweite Hälfte; ohne geladenes Strata: TTS/STT-Dienste (per UUID fest)
```

Strata belegt GPU 1 und 2 nur, solange das Modell geladen ist, und entlädt es nach 10 Minuten ohne Anfrage. Vor
jedem Laden stoppt `gpu-freigeben.sh` die TTS/STT-Dienste und den Container `coding_model` und entlädt die
Ollama-Modelle; nach dem Entladen startet `strata-wache` die Dienste wieder. Details:
`~/nvme2n1p7_home/strata-betrieb/BEDIENUNGSANLEITUNG.md`, „GPUs teilen“.

**Alternative llama.cpp-Server:** Ein Container `coding_model` (Port 8001) auf GPU 1 bedient beide Rollen
nacheinander; die Umschaltung erfolgt über den System-Prompt. Er läuft nur, solange Strata entladen oder gestoppt ist,
denn Strata braucht GPU 1 und 2 fast voll; lädt Strata, stoppt `gpu-freigeben.sh` den Container.

### 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. Auf der gewählten GPU darf sonst nichts nennenswert
VRAM belegen – vor allem kein geladenes Strata und keine Ollama-Modelle; auf GPU 2 liegen zusätzlich die
TTS/STT-Dienste. Prüfen mit:
```bash
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

```bash
# Die zweite RTX 3090 statt GPU 1:
GPU_DEVICE=2 ./start-coding-server.sh

# Beide RTX 3090 für einen Server (größerer Kontext oder größeres Modell) – start-coding-server.sh anpassen:
  --gpus '"device=1,2"' \
  --tensor-split 0.5,0.5 \
  --main-gpu 0 \
  -c 262144
```

`--main-gpu 0` meint die erste GPU, die der Container sieht, hier also GPU 1. Beide RTX 3090 sind nur frei, wenn
Strata gestoppt ist (`~/nvme2n1p7_home/strata-betrieb/scripts/strata.sh stop`). GPU 0 (T600, 4 GB) ist für das
27B-Modell zu klein und bleibt dem Display und dem Bild-Encoder von Strata vorbehalten.

---

## 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

```bash
./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](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](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](BEDIENUNGSANLEITUNG.md) – Einrichtung, Modellwahl, alle Befehle, MCP-Server, Web-Tests,
  schneller entwickeln, Fehlermeldungen
- [FUNKTIONSWEISE.md](FUNKTIONSWEISE.md) – Aufbau der Extension, Ablauf von `/optimize`, Designentscheidungen, Grenzen
- [CHANGELOG.md](CHANGELOG.md) – Änderungen und was beim Update zu tun ist
- [LICENSE](LICENSE) – MIT
- Strata-Server und Messwerte auf diesem PC: `~/nvme2n1p7_home/strata-betrieb`