diff --git a/README.md b/README.md
new file mode 100644
index 0000000..907f656
--- /dev/null
+++ b/README.md
@@ -0,0 +1,104 @@
+# pi_coder — Automatisierter Coder/Judge-Workflow für pi agent
+
+Dieses Repository enthält die Konfiguration und Skripte für einen automatisierten
+Coding-Workflow mit zwei lokalen LLaMA-Modellen: ein Coder-Modell und ein Judge-Modell,
+gesteuert über [pi agent](https://github.com/earendil-works/pi).
+
+## Überblick
+
+```
+Nutzer gibt Auftrag
+        │
+        ▼
+  /coder  →  qwen3.5-coder (:8001)  →  Implementierung + git commit
+        │
+        ▼
+  /judge  →  qwen3.5-judge (:8002)  →  Review: PASS / FAIL + Blocker
+        │
+   FAIL? ▼
+  /fix    →  qwen3.5-coder (:8001)  →  Fixes + git commit
+        │
+   PASS? ▼
+  /shipit →  qwen3.5-judge (:8002)  →  Finale Freigabe: SHIP / NO-SHIP
+
+  /optimize = Coder→Judge→Fix-Schleife automatisch (bis PASS oder max. N Runden)
+```
+
+## Modelle
+
+| Rolle   | Modell                                          | Port | Container           |
+|---------|-------------------------------------------------|------|---------------------|
+| Coder   | Qwen3.6-27B-Uncensored-HauhauCS-Aggressive-IQ4_XS | 8001 | qwen36-27b-coder    |
+| Judge   | Qwen3.6-27B-Uncensored-HauhauCS-Aggressive-IQ4_XS | 8002 | qwen36-27b-judge    |
+
+Beide Modelle laufen als separate llama.cpp-Docker-Container auf GPU 1 und 2 (tensor-split 0.5/0.5).
+
+## Voraussetzungen
+
+- Docker mit NVIDIA-GPU-Support (`nvidia-container-toolkit`)
+- GPU 1 und GPU 2 verfügbar (`nvidia-smi`)
+- GGUF-Modell unter: `$HF_HOME/models/qwen3/Qwen3.6-27B-Uncensored-HauhauCS-Aggressive-IQ4_XS.gguf`
+  - Standard: `HF_HOME=/home/dschlueter/nvme2n1p7_home/huggingface`
+- [pi agent](https://github.com/earendil-works/pi) installiert (`~/.pi/`)
+
+## Setup
+
+```bash
+# 1. Extension und Modell-Config nach ~/.pi/agent/ deployen
+./install.sh
+
+# 2. /reload in pi agent ausführen
+```
+
+Nach Änderungen an `pi-coder-judge-extension.ts` oder `models.json`:
+```bash
+./install.sh   # kopiert nach ~/.pi/agent/
+# dann /reload in pi agent
+```
+
+## Server starten / stoppen / status
+
+```bash
+# Coder-Server starten (Port 8001)
+./start-coder.sh
+
+# Judge-Server starten (Port 8002)
+./start-judge.sh
+
+# Beide stoppen
+./stop-servers.sh
+
+# Status beider Server prüfen
+./status.sh
+```
+
+Umgebungsvariable für alternativen Modellpfad:
+```bash
+HF_HOME=/anderer/pfad ./start-coder.sh
+```
+
+## pi-Kommandos
+
+| Kommando | Beschreibung |
+|---|---|
+| `/coder <auftrag>` | TASK.md anlegen, Implementierung starten (Coder-Modell) |
+| `/judge [fokus]` | Code-Review gegen TASK.md + letzten Commit (Judge-Modell) |
+| `/fix [hinweis]` | Judge-Kritik beheben, committen (Coder-Modell) |
+| `/shipit` | Finale Freigabeprüfung (Judge-Modell) |
+| `/optimize <auftrag> [--rounds N] [--with-doku]` | Vollautomatische Schleife bis PASS |
+| `/patch <änderung>` | Gezielte Minimaländerung ohne vollständigen Review |
+| `/quick_check [was]` | Schnelle Prüfung der letzten Änderung (OK/PROBLEM) |
+| `/update_doku` | Code kommentieren + README.md + BEDIENUNGSANLEITUNG.md |
+| `/new_project <pfad>` | Neues Projektverzeichnis + git init anlegen |
+
+## Dateien
+
+| Datei | Zweck |
+|---|---|
+| `pi-coder-judge-extension.ts` | pi agent Extension (Kommandos, Tools, Hooks) |
+| `models.json` | Provider- und Modell-Konfiguration für pi agent |
+| `start-coder.sh` | Docker-Container für Coder-Modell (Port 8001) starten |
+| `start-judge.sh` | Docker-Container für Judge-Modell (Port 8002) starten |
+| `stop-servers.sh` | Beide Container stoppen |
+| `status.sh` | Laufstatus beider Server anzeigen |
+| `install.sh` | Extension + models.json nach `~/.pi/agent/` kopieren |
diff --git a/status.sh b/status.sh
new file mode 100755
index 0000000..9eacbf7
--- /dev/null
+++ b/status.sh
@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+
+check_server() {
+  local NAME="$1"
+  local PORT="$2"
+  local ALIAS="$3"
+
+  printf "%-28s" "$NAME (Port $PORT):"
+
+  # Docker-Status
+  if docker ps --format '{{.Names}}' | grep -q "^${NAME}\$"; then
+    printf " Container=\033[32mRUNNING\033[0m"
+  elif docker ps -a --format '{{.Names}}' | grep -q "^${NAME}\$"; then
+    printf " Container=\033[33mSTOPPED\033[0m"
+  else
+    printf " Container=\033[31mNOT FOUND\033[0m"
+    echo
+    return
+  fi
+
+  # HTTP-Erreichbarkeit
+  if curl -s --max-time 3 "http://localhost:${PORT}/health" >/dev/null 2>&1 || \
+     curl -s --max-time 3 "http://localhost:${PORT}/v1/models" >/dev/null 2>&1; then
+    printf "  HTTP=\033[32mOK\033[0m"
+  else
+    printf "  HTTP=\033[31mNOT READY\033[0m"
+  fi
+
+  echo
+}
+
+echo "=== LLaMA-Server Status ==="
+check_server "qwen36-27b-coder" 8001 "qwen3.5-coder"
+check_server "qwen36-27b-judge" 8002 "qwen3.5-judge"
diff --git a/stop-servers.sh b/stop-servers.sh
new file mode 100755
index 0000000..1d25229
--- /dev/null
+++ b/stop-servers.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+CODER="qwen36-27b-coder"
+JUDGE="qwen36-27b-judge"
+
+for NAME in "$CODER" "$JUDGE"; do
+  if docker ps -a --format '{{.Names}}' | grep -q "^${NAME}\$"; then
+    docker rm -f "$NAME" >/dev/null
+    echo "[*] Gestoppt: $NAME"
+  else
+    echo "[-] Nicht gefunden: $NAME"
+  fi
+done