dschlueter/pi_coder_2
Watch
1
0
Fork
You've already forked pi_coder_2
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
pi_coder_2/BEDIENUNGSANLEITUNG.md
dschlueter e1796c0ccc docs: pi-Doku zusammengeführt, FUNKTIONSWEISE/CHANGELOG/LICENSE; mcp.json versioniert und verlinkt 
Hinweise zu pi und der Coder/Judge-Erweiterung (MCP-Server, Web-Tests, schneller
entwickeln, Fehlerbilder) aus strata-betrieb übernommen. Kapitel 2/3 und README
auf Strata als Standard gebracht. deploy-pi-config.sh verlinkt jetzt auch mcp.json.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 04:56:38 +02:00

36 KiB
Raw Blame History

Bedienungsanleitung: pi_coder

pi_coder ist ein Werkzeug, das ein lokales KI-Modell abwechselnd als Coder und Judge einsetzt, um Software automatisch zu schreiben, zu prüfen und zu verbessern — alles gesteuert über einfache Slash-Kommandos in der pi-Agent-Oberfläche.

Inhaltsverzeichnis

  1. Konzept: Coder und Judge
  2. Vorbereitung (Modell wählen, Einrichten, pi aktualisieren)
  3. Alternative: llama.cpp-Server (:8001)
  4. Neues Projekt anlegen
  5. Manueller Workflow: /coder → /judge → /fix → /shipit
  6. Automatischer Workflow: /optimize (inkl. Schneller entwickeln, Interactive-Modus)
  7. Kleine Änderungen: /patch und /quick_check
  8. Dokumentation generieren: /update_doku
  9. Versionsverwaltung: /version
  10. TASK.md verstehen und nutzen
  11. Werkzeuge für pi: MCP-Server
  12. Web-Anwendungen testen
  13. Typische Anwendungsfälle
  14. Fehlermeldungen und Lösungen

1. Konzept: Coder und Judge

pi_coder verwendet zwei Rollen — bedient von einem einzigen Modell, das je nach Aufgabe eine andere Persona annimmt:

Coder-Persona: Schreibt und repariert Code. Liest die Aufgabe aus TASK.md, implementiert sie, führt Tests aus und erstellt Git-Commits.

Judge-Persona: Überprüft den Code mit dem Blick eines skeptischen Senior-Entwicklers. Prüft Korrektheit, Robustheit, Randfälle, Sicherheit und Produktionsreife. Maßstab für das Urteil sind TASK.md und, falls vorhanden, SPEC.md:

  • PASS — alle Anforderungen erfüllt, Tests grün, kein Blocker und kein Major
  • PASS WITH CONCERNS — alle Anforderungen erfüllt, aber mindestens ein Major: ein konkretes Risiko im geforderten Einsatz, mit Reproduktion (wird wie FAIL behandelt, außer du verwendest --approve-concerns)
  • FAIL — eine Anforderung fehlt, Tests schlagen fehl oder ein reproduzierbarer Fehler im geforderten Verhalten

Härtung über die Anforderungen hinaus, Skalierung, Stil und Wünsche schreibt der Judge unter „Hinweise“. Sie ändern das Urteil nicht, und der Coder bearbeitet sie bei /fix nicht. Ein Major ohne Reproduktion gilt als Hinweis. Ohne diese Regeln urteilte der Judge mit Strata am 15.10.2026 in keiner Aufgabe PASS.

Judge und Freigabeprüfung berichten kurz: keine Tabelle bestandener Prüfungen, Blocker und Major vollständig mit Fundstelle, Minor, fehlende Tests und Hinweise höchstens 5 Punkte je Abschnitt. Grund: Lange Berichte kosten Rechenzeit und bleiben im Kontext jeder weiteren Runde (Messung im Repo strata-betrieb, FUNKTIONSWEISE).

Die Umschaltung zwischen den Rollen erfolgt über unterschiedliche System-Prompts, die die Extension automatisch vor jeder Inference einsetzt. Es läuft kein zweiter Server.

Der Grundgedanke: Coder und Judge haben keine „Höflichkeitsschranke" zueinander — der Judge kritisiert direkt und konkret, der Coder repariert ohne Widerspruch.

2. Vorbereitung

Modell wählen

Coder und Judge sind ein Modell. Standard ist strata/qwen3.8-flash-next-iq3_s, der lokale Strata-Server auf 127.0.0.1:9090. Seinen Betrieb (Start, GPU-Freigabe, Entladen nach 10 Minuten, Bilder) beschreibt ~/nvme2n1p7_home/strata-betrieb/BEDIENUNGSANLEITUNG.md. Ist das Modell entladen, lädt Strata es bei der ersten Anfrage; die Bereitschaftsprüfung der Extension wartet darauf bis zu 3 Minuten.

Ein anderes Modell aus models.json setzt die Umgebungsvariable PI_CODER_MODEL=<provider>/<id> beim Start von pi, z. B. der llama.cpp-Server aus Kapitel 3:

PI_CODER_MODEL=llama-cpp-single/coding_model pi

Freie Eingaben (ohne Slash-Befehl) nutzen pis eigenes Standardmodell aus ~/.pi/agent/settings.json. --provider/--model ändern es für einen Lauf, ohne die globalen Einstellungen anzufassen:

pi --provider strata --model qwen3.8-flash-next-iq3_s

Bilder (Screenshots, read auf PNG/JPG, Browser-Screenshots) erreichen nur Modelle, die in models.json "input": ["text", "image"] haben. Strata ist so eingetragen. Bei anderen Modellen meldet pi „Current model does not support images“ und lässt das Bild weg.

Einrichten

Einmalig und nach Änderungen an models.json oder settings.json:

cd ~/pi_coder_v2
./deploy-pi-config.sh

Das Skript verlinkt pi-coding-extension.ts und mcp.json nach ~/.pi/agent/. Änderungen im Repo gelten damit ab dem nächsten pi-Start (oder /reload), auch noch nicht committete, und pi mcp add schreibt direkt ins Repo. models.json wird kopiert, aus settings.json nur die Liste packages übernommen. Eine abweichende alte Datei sichert das Skript vorher als .bak.

pi öffnen

pi im Projektordner starten, also dort, wo der Code liegt, nicht in ~/pi_coder_v2:

cd ~/MeinProjekt
pi

pi aktualisieren

pi update ersetzt pis Programmdateien. Ein pi, das dabei läuft, findet danach Teile seines eigenen Codes nicht mehr, und jede Modellanfrage scheitert (siehe Fehlermeldungen). Deshalb nur aktualisieren, wenn kein pi läuft, oder alle laufenden pi danach neu starten.

3. Alternative: llama.cpp-Server (:8001)

Nur nötig, wenn Coder und Judge statt Strata das Modell llama-cpp-single/coding_model nutzen sollen: Qwen3.6-27B IQ4_XS im Docker-Container coding_model auf einer GPU. Danach pi mit PI_CODER_MODEL=llama-cpp-single/coding_model starten (siehe Modell wählen).

GPU-Zuordnung

Der Server läuft standardmäßig auf GPU 1 (überschreibbar):

./start-coding-server.sh           # GPU 1 (Standard)
GPU_DEVICE=0 ./start-coding-server.sh   # GPU 0

Auf einem System mit mehreren GPUs empfiehlt es sich, GPU 0 (Display) freizuhalten und GPU 1 für den KI-Server zu verwenden.

Wichtig: Andere GPU-Prozesse (z. B. TTS-Dienste, Ollama) auf der verwendeten GPU können VRAM belegen und dazu führen, dass der Server nicht startet. Im Zweifel prüfen:

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

Server starten

cd ~/pi_coder_v2
./start-coding-server.sh

Erwartete Ausgabe:

[*] Verwende HF_HOME = /home/.../huggingface
[*] GPU device = 1
[✓] Single-Server (:8001) bereit

Dauer: bis zu 5 Minuten. Danach ist das Modell im VRAM und sofort antwortbereit.

Server stoppen

./stop-coding-server.sh

Status prüfen

./status-coding-server.sh

Alternativer Modellpfad

Falls die GGUF-Datei an einem anderen Ort liegt:

HF_HOME=/mnt/daten/huggingface ./start-coding-server.sh

4. Neues Projekt anlegen

Kommando

/new_project <pfad>

Beispiel

/new_project ~/Python_Programs/mein_tool

Was passiert:

  • Verzeichnis ~/Python_Programs/mein_tool wird angelegt
  • git init wird ausgeführt
  • .gitignore wird mit Standardeinträgen angelegt und committed

Wichtig: pi agent wechselt nicht automatisch in das neue Verzeichnis — die Session bleibt im aktuellen Verzeichnis. Nach dem Anlegen:

cd ~/Python_Programs/mein_tool
pi

Dann kannst du /coder oder /optimize mit dem neuen Projekt verwenden.

5. Manueller Workflow

Der manuelle Workflow gibt dir volle Kontrolle über jeden Schritt.

Schritt 1: /coder — Aufgabe übergeben

/coder <auftrag>

Der Coder:

  1. Legt TASK.md im aktuellen Verzeichnis an (oder hängt an bestehende an)
  2. Liest TASK.md und implementiert den Auftrag
  3. Führt Tests oder Build-Checks aus
  4. Erstellt einen Git-Commit

Beispiel:

/coder Schreibe ein Python-Kommandozeilenprogramm 'textcount'. Es soll eine Textdatei als Argument nehmen und folgendes ausgeben: Anzahl Zeichen, Wörter, Zeilen und die 5 häufigsten Wörter (ohne Stoppwörter).

Typische Ausgabe des Coders:

Implementierung abgeschlossen.
- src/textcount.py erstellt (Hauptprogramm)
- tests/test_textcount.py erstellt (Unit-Tests)
- requirements.txt angelegt (keine externen Abhängigkeiten)
- Alle 8 Tests bestanden
- Commit: feat: implement textcount CLI tool
Risiken: Stoppwortliste nur Deutsch/Englisch, keine Konfigurations-Option.

Schritt 2: /judge — Code überprüfen lassen

/judge

Optionaler Fokus:

/judge Besonderes Augenmerk auf Fehlerbehandlung und Edge Cases

Der Judge:

  1. Liest TASK.md und prüft ob alle Anforderungen umgesetzt sind
  2. Analysiert git show HEAD
  3. Führt Tests aus
  4. Gibt ein strukturiertes Urteil aus

Beispiel-Ausgabe PASS WITH CONCERNS:

Urteil: PASS WITH CONCERNS

Blocker: keine

Major:
- Nicht-existente Datei: Traceback statt Meldung und Exit-Code 2 (TASK.md verlangt Exit 2).
  Reproduktion: python3 textcount.py fehlt.txt; echo $?  → Traceback, Exit 1

Minor:
- Fehlermeldung nennt den Dateinamen nicht

Fehlende Tests:
- Test für leere Datei fehlt
- Test für Datei mit nur Leerzeichen fehlt

Hinweise (ändern das Urteil nicht):
- Bei sehr großen Dateien (>1 GB) wird alles in den RAM geladen
- Keine --version Flag

Konkrete Fix-Aufträge:
1. FileNotFoundError abfangen, Meldung mit Dateiname, exit(2)
2. Test für leere Eingabedatei

Beispiel-Ausgabe FAIL:

Urteil: FAIL

Blocker:
- textcount.py importiert 'collections.Counter' aber das ist nicht installiert
  (Counter ist stdlib, aber der Import-Fehler tritt bei Python < 3.9 auf)
- ./textcount.py existiert nicht — tests/test_textcount.py schlägt komplett fehl

Major: ...

Schritt 3: /fix — Kritik beheben

/fix

Optionaler Hinweis:

/fix Den Major-Punkt mit der Stoppwortliste kannst du weglassen, das ist kein Produktionsprojekt

Der Coder arbeitet die Judge-Kritik ab (Blocker zuerst, dann Major, dann Minor) und erstellt einen neuen Commit.

Schritt 4: /shipit — Finale Freigabe

/shipit

Der Judge gibt ein finales Urteil:

  • SHIP — bereit für Produktion
  • NO-SHIP — noch Probleme offen

Beispiel:

Urteil: SHIP

Letzte Blocker: keine

Restrisiken:
- Kein Streaming für sehr große Dateien (dokumentiert in README)

Empfohlene Sofortmaßnahmen: keine

6. Automatischer Workflow: /optimize

/optimize führt den gesamten Coder→Judge→Fix-Zyklus automatisch durch.

Syntax

/optimize <auftrag> [--rounds N] [--with-doku] [--continue] [--interactive]
          [--no-tests] [--approve-concerns] [--test-cmd "cmd"] [--test-timeout N]
  • --rounds N — maximale Anzahl Runden (Standard: 2)
  • --with-doku — nach SHIP automatisch /update_doku ausführen
  • --continue — überspringt die Implementierungsphase und startet direkt mit dem Judge→Fix-Zyklus ab dem aktuellen Code-Stand. Nützlich wenn man bereits manuell /coder, /judge und /fix durchgeführt hat und den Rest automatisieren möchte.
  • --interactive — pausiert nach erstem PASS für einen menschlichen Checkpoint. Details: siehe Interactive-Modus weiter unten.
  • --no-tests — überspringt die automatische Test-Erkennung. Sinnvoll wenn keine Test-Suite vorhanden ist oder Tests über externe Infrastruktur laufen.
  • --approve-concerns — behandelt „PASS WITH CONCERNS" wie „PASS": kein ShipIt-Call, direktes SHIP. Standardmäßig löst PASS WITH CONCERNS immer einen Coder-Fix aus.
  • --test-cmd "befehl" — überschreibt die automatische Test-Erkennung mit einem eigenen Befehl (z.B. --test-cmd "pytest tests/ -x").
  • --test-timeout N — maximale Laufzeit pro Test-Befehl in Sekunden (Standard: 120).

PASS WITH CONCERNS — wichtig

Ohne --approve-concerns gilt PASS WITH CONCERNS wie FAIL — der Coder bekommt einen Fix-Auftrag und der Loop geht weiter. Erst sauberes PASS beendet die Schleife. Mit --approve-concerns gilt PASS WITH CONCERNS als bestanden.

Beispiel: einfacher Auftrag

/optimize Schreibe ein Rust-Programm 'genpw' das sichere Passwörter generiert. Optionen: --length N (Standard 16), --count N (Standard 1), --no-symbols, --no-numbers.

Was im Hintergrund passiert:

Phase 1: Coder implementiert...
Phase 2: Runde 1/2: Judge — TASK.md + letzter Commit + Tests...
  → Urteil: FAIL (2 Blocker)
Phase 3: Runde 1/2: Coder fixt...
Phase 4: Runde 2/2: Judge — TASK.md + letzter Commit + Tests...
  → Urteil: PASS
✓ PASS nach Runde 2 → SHIP
[Dialog: Version → v0.1.0 (empfohlen)]

Bei PASS WITH CONCERNS (ohne --approve-concerns):

  → Urteil: PASS WITH CONCERNS (Major: fehlendes --help)
Phase 3: Runde 2/2: Coder fixt Concerns...
Phase 4: Runde 3/3: Judge...
  → Urteil: PASS
✓ PASS → SHIP

Bei klarem PASS entfällt die ShipIt-Runde — es wird direkt SHIP ausgelöst.

Während des Ablaufs zeigt die Statuszeile die aktuelle Phase — mit laufendem Timer:

◉ Coder implementiert: Login-Flow mit JWT [01:23]
◉○ Runde 1/2: Judge — TASK.md + letzter Commit + Tests [00:47]
●◉ Runde 1/2: Coder fixt — fehlendes Null-Check [01:05]
●● ✓ PASS nach Runde 2/2 — SHIP
🚀 SHIP – produktionsreif

Steht der Timer still, hängt der Prozess — dann /cancel verwenden.

Beispiel: mehr Runden

/optimize Implementiere einen vollständigen REST-API-Client für die GitHub API in Python mit Rate-Limiting, Retry-Logic und Caching --rounds 5

Beispiel: mit automatischer Dokumentation

/optimize Schreibe ein Go-Tool 'logfilter' das Logdateien nach Regex-Muster filtert --with-doku

Nach SHIP werden automatisch ausgeführt:

  1. Code-Kommentare einfügen
  2. README.md schreiben
  3. BEDIENUNGSANLEITUNG.md schreiben
  4. LICENCE.md anlegen (falls noch nicht vorhanden)

Vom manuellen Workflow in den automatischen wechseln

Du hast bereits /coder, /judge und /fix manuell durchgeführt und möchtest den Rest automatisch ablaufen lassen:

/optimize --continue

/optimize --continue --rounds 5

/optimize --continue --with-doku

Die Implementierungsphase wird übersprungen — der Judge prüft sofort den aktuellen Stand und der Fix-Zyklus läuft automatisch bis PASS oder max. N Runden.

Schneller entwickeln

Eine lange Sitzung an einem Tauri-Projekt mit Strata dauerte 12 Stunden, davon rund 9 Stunden Warten auf den nächsten Befehl (Messung: ~/nvme2n1p7_home/strata-betrieb/FUNKTIONSWEISE.md, „Messwerte“). Was schneller macht, nach Wirkung:

  1. Eine Schleife statt einzelner Befehle. Für einen weiteren Auftrag am selben Projekt /optimize --continue "Zusatzauftrag …" --rounds 5 --test-cmd "…" statt /judge, /fix und /shipit von Hand. Die Schleife geht ohne Pause von Prüfung zu Reparatur.
  2. Neue pi-Sitzung je Auftrag (pi neu starten). Der Kontext beginnt klein; in der gemessenen Sitzung lag der Prompt im Median bei 126 000 Tokens. Was pi wissen muss, steht in TASK.md und in Git.
  3. Teure Builds erst zur Freigabe. Im Auftrag z. B.: „In den Fix-Runden nur cargo test und npm run build; npx tauri build erst bei der Freigabe.“
  4. Kurze Berichte sind Standard (siehe Konzept).
  5. Ein schnelleres Cloud-Modell (PI_CODER_MODEL=openrouter/…) ist die letzte Stufe: kostet Geld, und der Code geht nach außen.

Loop-Erkennung

Wenn zweimal hintereinander dieselbe Beanstandung auftritt, bricht /optimize ab:

⚠ Schleife: Gleicher Blocker zweimal – manuelle Intervention nötig

Verglichen wird der Blocker-Abschnitt des Judges. Steht dort nur „Keine“, werden stattdessen die Major-Punkte verglichen; fehlen beide Abschnitte, der ganze Judge-Text. Zwei Runden mit „Blocker: Keine“, aber verschiedenen Major-Punkten sind also keine Schleife.

In diesem Fall: /judge manuell ausführen, Blocker lesen, mit /fix manuell eingreifen.

Max. Runden ohne PASS

⚠ 2 Runden durchlaufen ohne PASS. Bitte manuell prüfen.

Dann: /judge und /fix manuell für gezielte Eingriffe. Mit --rounds N kann die Grenze hochgesetzt werden, z.B. --rounds 5 für komplexe Aufgaben.

Interactive-Modus

Mit --interactive pausiert /optimize nach dem ersten PASS und wartet auf menschliches Feedback — bevor das abschließende SHIP ausgelöst wird.

/optimize Implementiere Feature X --interactive

Typischer Ablauf:

Phase 1: Coder implementiert...
Phase 2: Judge prüft...
  → Urteil: PASS
⏸ PASS erreicht. Weitere Features? /continue "Zusatzauftrag" — oder /continue zum Shippern.

Jetzt hast du drei Optionen:

Option A: Direkt shippern

/continue

→ ShipIt wird gestartet, Version-Dialog erscheint.

Option B: Zusatzauftrag hinzufügen

/continue "Füge außerdem eine --verbose Option hinzu"

→ Coder implementiert den Zusatz, dann läuft der Judge-Loop erneut an. → Nach erneutem PASS erscheint der Checkpoint wieder — du kannst beliebig viele Iterationen anhängen, bevor du mit /continue zum SHIP gehst.

Option C: Abbrechen

/cancel

→ Loop wird abgebrochen, kein SHIP.

Timeout: Wenn du 30 Minuten lang nichts eingibst, bricht /optimize automatisch ab.

Wann ist --interactive sinnvoll?

  • Wenn der Auftrag aus mehreren voneinander abhängigen Features besteht
  • Wenn du nach jeder fertigen Stufe entscheiden möchtest, ob du weitermachst
  • Wenn du sicherstellen willst, dass nichts unbeabsichtigt committed wird

7. Kleine Änderungen: /patch und /quick_check

Für minimale Korrekturen — kein voller Review-Zyklus, keine TASK.md-Änderungen.

/patch — kleine Änderung umsetzen

/patch <beschreibung der änderung>

Der Coder ändert ausschließlich das Beschriebene, prüft ob es noch kompiliert/startet und erstellt einen Commit.

Beispiele:

/patch Mindestpasswortlänge von 4 auf 8 Zeichen erhöhen

/patch Fehlermeldung bei ungültigem Argument von stderr auf stdout umleiten

/patch Versionsnummer in Cargo.toml von 0.1.0 auf 0.2.0 erhöhen

/patch Die Funktion parse_args() soll bei fehlendem --input-Argument eine sinnvolle Hilfsnachricht ausgeben statt zu paniken

/quick_check — Änderung schnell prüfen lassen

/quick_check [was geprüft werden soll]

Der Judge schaut sich git show HEAD an und gibt nur OK oder PROBLEM zurück.

Beispiele:

/quick_check

/quick_check Prüfe ob die Mindestlängen-Änderung korrekt umgesetzt ist und keine Randfälle fehlen

Typische Ausgaben:

Urteil: OK

Die Änderung in src/main.rs Zeile 47 ist korrekt. Mindestlänge wird jetzt
sowohl bei --length als auch im Standardfall geprüft.

Urteil: PROBLEM

src/lib.rs Zeile 23: Der neue Mindestwert von 8 wird nur bei --length geprüft,
nicht beim Standardwert (16). Wenn jemand --length 6 übergibt, schlägt die
Validierung korrekt fehl, aber der Standardfall ist nicht abgedeckt.
Fix: Validierung in die Funktion generate_password() verschieben statt in parse_args().

Typischer /patch + /quick_check Workflow

/patch Timeout bei HTTP-Requests von 30 auf 10 Sekunden setzen

(Coder ändert, committet)

/quick_check Prüfe ob der Timeout auch bei Retry-Versuchen korrekt gilt

(Judge gibt OK oder zeigt konkretes Problem)

8. Dokumentation generieren: /update_doku

Nach Abschluss der Entwicklung (nach /shipit oder /optimize) erstellt /update_doku vier Dinge automatisch:

  1. Code-Kommentare — erklärt das WARUM in den Quelldateien (Deutsch)
  2. README.md — Entwicklerperspektive: Installation, Build, Verwendung
  3. BEDIENUNGSANLEITUNG.md — Endnutzerperspektive: einfach, ohne Jargon
  4. LICENCE.md — proprietäre Lizenz mit aktuellem Jahr und Inhaber aus git config user.name (wird nur angelegt wenn noch keine LICENCE.md vorhanden ist — existierende Lizenzen werden nie überschrieben)
/update_doku

Inkrementelles Update

/update_doku merkt sich via Git-Tags welche Dateien seit dem letzten Lauf geändert wurden. Nur geänderte Quelldateien werden neu kommentiert — unveränderte bleiben unangetastet.

Code-Kommentare: keine Änderungen seit letztem Lauf – übersprungen.
README.md: 2 Datei(en) geändert – wird geprüft
BEDIENUNGSANLEITUNG.md: 2 Datei(en) geändert – wird geprüft
LICENCE.md: bereits vorhanden – übersprungen.

Zusammen mit /optimize

/optimize Implementiere Feature X --with-doku

Führt nach SHIP automatisch /update_doku aus.

9. Versionsverwaltung: /version

pi_coder verwaltet Versionsnummern im SemVer-Format (vMAJOR.MINOR.PATCH) automatisch — basierend auf den Commit-Messages des generierten Codes.

Wie Commit-Messages die Version bestimmen

Der Coder verwendet standardmäßig das Conventional-Commits-Format:

Commit-Prefix Beispiel Bump-Typ
feat!: oder BREAKING CHANGE feat!: API komplett überarbeitet major (v1.0.0 → v2.0.0)
feat: feat: CSV-Export hinzugefügt minor (v1.0.0 → v1.1.0)
fix:, chore:, andere fix: Crash bei leerer Datei patch (v1.0.0 → v1.0.1)

Automatisch nach SHIP

Nach einem erfolgreichen SHIP-Verdikt in /optimize oder /shipit erscheint automatisch ein Dialog:

┌─ Version ──────────────────────────────────────────────┐
│ Aktuelle Version: v1.2.3. Commits seit letztem Tag:    │
│ minor-Bump erkannt.                                     │
│                                                         │
│  patch → v1.2.4                                         │
│  minor → v1.3.0  (empfohlen)                           │
│  major → v2.0.0                                         │
│  Überspringen                                           │
└─────────────────────────────────────────────────────────┘

Du kannst den empfohlenen Wert bestätigen oder manuell einen anderen wählen.

Manuell aufrufen

/version

Nützlich wenn du den Tag nachträglich setzen möchtest oder nach manuellen Commits.

Was passiert nach der Auswahl

  1. Die Versionsnummer wird in die Projekt-Manifest-Datei geschrieben (falls vorhanden):
    • package.json → npm version --no-git-tag-version X.Y.Z
    • Cargo.toml → version = "X.Y.Z" in [package]
    • pyproject.toml → version = "X.Y.Z" in [project]
    • VERSION → Dateiinhalt vX.Y.Z
  2. Commit: chore: bump version to vX.Y.Z
  3. Git-Tag: vX.Y.Z wird gesetzt

Wenn keine der genannten Dateien vorhanden ist, wird nur der Git-Tag gesetzt.

Erstes Mal — kein Tag vorhanden

┌─ Version ──────────────────────────────────────────────┐
│ Noch kein Versions-Tag vorhanden.                       │
│                                                         │
│  patch → v0.0.1                                         │
│  minor → v0.1.0  (empfohlen)                           │
│  major → v1.0.0                                         │
│  Überspringen                                           │
└─────────────────────────────────────────────────────────┘

Empfehlung: v0.1.0 für ein frisches, funktionierendes Projekt; v1.0.0 wenn es sofort produktionsreif ist.

10. TASK.md verstehen und nutzen

TASK.md ist die persistente Aufgabenbeschreibung im Projektverzeichnis. Sie wird von allen Kommandos als Referenz gelesen.

Erstellt von /coder und /optimize

Beim ersten /coder-Aufruf:

# Aufgabe

Schreibe ein Python-Kommandozeilenprogramm 'textcount'...

## Erstellt
2026-05-19T14:30:00.000Z

## Status
- [ ] Implementierung
- [x] Review bestanden (PASS)
- [ ] Produktionsreif (SHIP)

Zusatzauftrag hinzufügen

Wenn du später /coder mit einer neuen Aufgabe aufrufst, wird TASK.md erweitert statt überschrieben:

/coder Füge zusätzlich eine --csv-Option hinzu, die das Ergebnis als CSV ausgibt

# Aufgabe

[...ursprüngliche Aufgabe...]

---

## Zusatzauftrag

2026-05-19T15:45:00.000Z

Füge zusätzlich eine --csv-Option hinzu...

## Status
- [ ] Implementierung
- [ ] Review bestanden (PASS)
- [ ] Produktionsreif (SHIP)

Status-Checkboxen

Die Checkboxen werden automatisch abgehakt:

  • [x] Implementierung — nach erfolgreichem /coder oder Phase 1 von /optimize
  • [x] Review bestanden (PASS) — nach PASS durch /judge oder in /optimize
  • [x] Produktionsreif (SHIP) — nach SHIP durch /shipit oder /update_doku

11. Werkzeuge für pi: MCP-Server

Eingetragen in mcp.json dieses Repos, nach ~/.pi/agent/mcp.json verlinkt (pi mcp list zeigt den Zustand). Sie gelten in jeder pi-Sitzung, auch in der Coder/Judge-Schleife:

Server Version Zweck
playwright @playwright/mcp@0.0.83 Web-Apps in einem headless Chrome bedienen (siehe Kapitel 12)
context7 @upstash/context7-mcp@4.1.1 aktuelle Doku von Bibliotheken nachschlagen (resolve-library-id, query-docs), damit das Modell keine veralteten APIs erfindet; Anfragen gehen an context7.com

codemode: pi beschreibt MCP-Werkzeuge dem Modell nicht einzeln. Das Modell schreibt ein kurzes JavaScript, das sie aufruft (tools.mcp__context7__query_docs(...)). Beide Server zusammen kosten so nur rund 870 Prompt-Tokens.

Context7 benutzen: im Auftrag den Server und die Bibliothek mit Version nennen, ein Thema je Frage, z. B.:

Schlage mit context7 in der aktuellen Doku von Tauri 2 nach: Wie sende ich aus einem Rust-Command
Fortschritts-Events an das Frontend? Kurzes Beispiel für beide Seiten, nenne die Bibliotheks-ID.

In /optimize-Aufträgen hilft der Satz „Schlage unklare APIs mit context7 nach, bevor du sie benutzt.“

API-Key: mcp.json enthält nur den Verweis "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}". Der Key selbst gehört in die Umgebung, z. B. export CONTEXT7_API_KEY=… in ~/.bashrc. Fehlt die Variable, startet pi den Server nicht (pi mcp list: context7: failed, „Failed to resolve … env "CONTEXT7_API_KEY"“). Steht der export in ~/.bashrc nach der Abfrage auf interaktive Shells, gilt das für Skripte, Cron und Dienste. Prüfen, ob der Key beim Server ankommt (zeigt nur die Länge): tr '\0' '\n' < /proc/$(pgrep -f context7-mcp | head -1)/environ | grep '^CONTEXT7_API_KEY=' | cut -d= -f2- | wc -c. Den Einrichtungsassistenten npx ctx7 setup nicht benutzen: Er schreibt den Key im Klartext in die Konfiguration.

Weitere Server nur bei Bedarf, z. B. Serena (Code-Navigation über Language Server, lohnt bei großen Projekten) oder ein Forgejo-Server (Issues, Pull Requests). Unnötig sind Dateisystem-, Git- oder Fetch-Server: Das können bash, read und research_web schon. Versionen fest wählen, nur eine Version, die mindestens zwei Wochen alt ist.

12. Web-Anwendungen testen

pi testet Web-Apps über den MCP-Server playwright in einem headless Chrome (der installierte, --browser chrome), nie über Klicks auf dem Desktop. Die Seite kommt als Text (Accessibility-Baum) beim Modell an; dafür reicht jedes Textmodell. Für die Optik kann pi Screenshots machen; die sieht nur ein bildfähiges Modell (siehe Modell wählen).

pi --provider strata --model qwen3.8-flash-next-iq3_s
# dann z. B.: Teste http://127.0.0.1:5173/ mit den Browser-Werkzeugen: fülle das Formular aus, sende es ab
#             und nenne das Ergebnis wörtlich. Mach danach einen Screenshot und prüfe das Layout.

Für Projekte ist eine Playwright-Testsuite verlässlicher: reproduzierbar, auch in CI. Im Auftrag an /optimize: „Schreibe Playwright-E2E-Tests (@playwright/test, headless, channel: 'chrome', webServer startet die App).“ und --test-cmd "npm test && npx playwright test" --test-timeout 900. channel: 'chrome' nutzt den installierten Chrome, npx playwright install ist dann nicht nötig.

Inhalte prüft man über Snapshot oder Testsuite; Screenshots kosten Zeit und sind ungenauer. Messwerte mit Strata und die Einrichtung anderer Agenten (Hermes, OpenCode): ~/nvme2n1p7_home/strata-betrieb/BEDIENUNGSANLEITUNG.md, „Web-Anwendungen testen“.

13. Typische Anwendungsfälle

Neues Rust-Programm von Null

# 1. Verzeichnis anlegen
/new_project ~/Rust_Programs/mein_tool

# 2. Terminal: in Verzeichnis wechseln und pi neu starten
# cd ~/Rust_Programs/mein_tool && pi

# 3. In pi: vollautomatisch implementieren + dokumentieren
/optimize Schreibe ein Rust-CLI-Tool 'csvfilter' das CSV-Dateien zeilenweise filtert. Optionen: --column NAME, --value WERT, --regex. Ausgabe auf stdout. --with-doku

Bestehendes Projekt verbessern

# In pi, im Projektverzeichnis:
/coder Refaktoriere die Datenbankschicht: ersetze das raw-SQL durch sqlx mit typsicheren Queries. Alle Tests müssen danach noch laufen.
/judge
/fix
/shipit

Schnelle Bugfixes

/patch Die Funktion split_csv() schlägt bei Feldern mit eingebetteten Kommas fehl (RFC 4180 nicht implementiert)
/quick_check

Repo ohne Test-Suite oder mit externer CI

# Test-Erkennung überspringen — Judge bewertet nur den Code
/optimize "Implementiere Feature X" --no-tests

# Externe Test-Suite explizit angeben
/optimize "Implementiere Feature X" --test-cmd "make integration-test"

Schneller Loop ohne ShipIt-Runde

# Für Projekte wo "PASS WITH CONCERNS" ausreicht:
/optimize "Kleines Refactoring" --approve-concerns

# Kombination: kein Test, PASS WITH CONCERNS akzeptieren, 1 Runde
/optimize "Typo-Fix in Fehlermeldungen" --rounds 1 --no-tests --approve-concerns

Versionsnummer nach der Entwicklung setzen

# Nach SHIP: Dialog erscheint automatisch
/optimize Neues Feature X --rounds 2
# → SHIP → Dialog → "minor → v1.1.0" wählen → Tag gesetzt

# Oder manuell:
/version

Kommentarlosen Legacy-Code dokumentieren

# Nur Kommentare und Dokumentation, kein Code ändern:
/update_doku

Schrittweise mit manuellem Review

/coder Implementiere OAuth2-Login mit GitHub
# → Code lesen, verstehen
/judge Besonderes Augenmerk auf Token-Speicherung und CSRF-Schutz
# → Judge-Bericht lesen
/fix Ignoriere den Minor-Punkt mit der Logging-Verbosität, das ist Absicht
/shipit

Experiment: mehrere Runden explizit

/optimize Schreibe einen vollständigen Markdown-Parser mit AST in Python --rounds 5

Schrittweise Features hinzufügen mit --interactive

# Erst Grundgerüst implementieren und PASS abwarten:
/optimize Schreibe ein CLI-Tool 'filewatch' das Dateiänderungen überwacht --interactive

# Nach PASS erscheint: ⏸ PASS – warte auf /continue…

# Option A: Genug, direkt shippern:
/continue

# Option B: Weiteres Feature anhängen:
/continue "Füge außerdem einen --filter GLOB-Parameter hinzu"
# → Coder implementiert, Judge prüft erneut, PASS → Checkpoint wieder aktiv

# Nochmal erweitern:
/continue "Füge --output-log DATEI hinzu um Änderungen zu protokollieren"

# Fertig → shippern:
/continue

14. Fehlermeldungen und Lösungen

"Urteil unklar: … Judge-Urteil nicht erkennbar"

Ursache: In der Judge-Antwort steht keine Zeile „Urteil: PASS | PASS WITH CONCERNS | FAIL“. Markdown dazwischen wird erkannt (## Urteil: **PASS**, **Urteil:** FAIL); fehlt das Wort ganz, gilt die Runde als nicht bestanden.

Lösung: Antwort im Chat lesen, dann /judge erneut oder /fix mit der Kritik.

"Modell-Datei nicht gefunden"

[!] Modell-Datei nicht gefunden: /home/.../models/qwen3/Qwen3.6-27B-Uncensored-...gguf

Ursache: Die GGUF-Datei liegt nicht am erwarteten Ort.

Lösung:

# Pfad prüfen:
ls $HF_HOME/models/qwen3/

# Oder mit explizitem Pfad starten:
HF_HOME=/korrekter/pfad ./start-coding-server.sh

Server startet nicht / HTTP nicht erreichbar

[!] HTTP-Server wurde nicht rechtzeitig erreichbar.

Ursachen und Lösungen:

  1. Zu wenig VRAM — Container bricht beim Laden ab:

    docker logs coding_model | tail -50
# Suche nach: "CUDA out of memory" oder "failed to allocate"

    → Kontext reduzieren: -c 65536 statt -c 262144 in start-coding-server.sh

  2. GPU nicht verfügbar:

    nvidia-smi   # GPU sichtbar?
# GPU 1 testen:
docker run --gpus '"device=1"' --rm nvidia/cuda:12.0-base nvidia-smi
# Andere GPU testen:
GPU_DEVICE=0 ./start-coding-server.sh

  3. Port 8001 bereits belegt:

    ss -tlnp | grep 8001
docker ps -a   # alter Container noch vorhanden?
./stop-coding-server.sh
./start-coding-server.sh

"Cannot find module … chunks" nach pi update

Cannot find module '…/pi-coding-agent/dist/bundle/chunks/openai-completions-….js'

Ursache: pi wurde aktualisiert (pi update), während diese pi-Sitzung lief. Jede Modellanfrage scheitert sofort; /optimize läuft dann mit leeren Antworten durch, ohne zu arbeiten.

Lösung: pi beenden und neu starten, dann den Befehl wiederholen (bei /optimize mit --continue).

pi -p hängt in Skripten

Ursache: pi -p "…" liest zusätzlich stdin, wenn das kein Terminal ist, und wartet auf dessen Ende.

Lösung: pi … -p "…" </dev/null.

"Current model does not support images"

Ursache: Das gewählte Modell ist in models.json nicht als bildfähig eingetragen; pi lässt das Bild weg.

Lösung: Ein bildfähiges Modell wählen, z. B. Strata (siehe Modell wählen).

"Agent is already processing a prompt"

Ursache: Ein Kommando wurde aufgerufen während pi agent noch auf eine Antwort wartet.

Lösung: Warten bis die aktuelle Antwort fertig ist, dann das Kommando wiederholen. Bei /optimize passiert das automatisch — der interne Mechanismus wartet auf idle.

"edits[n] ... oldText must match exactly"

Ursache: Der interne pi-agent-Edit-Mechanismus hat beim Anwenden mehrerer Änderungen an derselben Datei versagt.

Was pi_coder dagegen tut: Ein tool_call-Hook in der Extension sortiert Mehrfach-Edits automatisch von hinten nach vorne (Bottom-up-Reordering), sodass frühere Edits spätere Positionen nicht verschieben. Zusätzlich steht das apply_patch-Tool bereit, das GNU patch -p1 mit Fuzzy-Matching nutzt.

Falls es trotzdem auftritt: Das Modell manuell anweisen:

Lies die Datei neu ein und wende die Änderungen als unified diff mit apply_patch an.

"N Runden ohne PASS" / Loop-Erkennung schlägt an

⚠ Derselbe Blocker tritt erneut auf – Schleife abgebrochen.

Ursache: Der Coder kann einen bestimmten Blocker oder Concern nicht beheben — z.B. weil die Aufgabe einen Widerspruch enthält oder ein externes System fehlt.

Lösung: Manuell eingreifen:

/judge  ← Judge-Bericht lesen

Dann den Blocker analysieren und entweder:

  • /fix Ignoriere Blocker X, das ist nicht Teil dieser Aufgabe
  • Den Code selbst anpassen und dann /fix aufrufen
  • Die Aufgabe in TASK.md präzisieren
  • Bei komplexen Aufgaben mit mehr Runden wiederholen: /optimize --continue --rounds 5

Falls der Judge wiederholt Concerns findet, die du akzeptierst:

/optimize --continue --approve-concerns

Server läuft, aber pi wechselt nicht das Modell

Ursache: models.json oder settings.json wurde nach einer Änderung nicht neu deployt.

Lösung:

cd ~/pi_coder_v2
./deploy-pi-config.sh
# Dann /reload in pi agent

"Neues Projekt" wechselt nicht das Verzeichnis

Das ist gewollt — pi-Sessions sind an ihr Startverzeichnis gebunden. Nach /new_project <pfad> im Terminal:

cd <pfad>
pi