From 09a0a07fdb093ab9898193fb3e7c70b36a189fd8 Mon Sep 17 00:00:00 2001 From: "thomas.kopp" Date: Sat, 4 Apr 2026 16:19:03 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20add=20README=20with=20t=C3=BCit=20intro?= =?UTF-8?q?,=20concept,=20usage=20and=20setup=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- README.md | 212 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..d7c5477 --- /dev/null +++ b/README.md @@ -0,0 +1,212 @@ +# autoresearch + +Autonome Forschungsschleife für Claude Code — inspiriert von [karpathy/autoresearch](https://github.com/karpathy/autoresearch). + +--- + +## Über tüit + +Die **tüit GmbH** ist ein IT-Dienstleister aus Deutschland. Wir betreuen mittelständische Unternehmen in den Bereichen IT-Infrastruktur, Support und Automatisierung. Unsere internen Tools entstehen dort, wo kommerzielle Lösungen zu schwerfällig oder zu teuer sind — pragmatisch, sicher, wartbar. + +--- + +## Was ist autoresearch? + +autoresearch lässt Claude Code nachts selbstständig arbeiten: Es analysiert Code und Konfigurationen, macht gezielte Verbesserungen, misst ob sie tatsächlich besser sind — und behält sie nur dann. + +**Die Idee** stammt aus der ML-Forschung: Andrej Karpathy beschreibt, wie ein KI-Agent über Nacht ~100 Trainingsexperimente durchführt, indem er immer wieder denselben Code modifiziert, 5 Minuten trainiert, die Metrik vergleicht und bei Verbesserung die Änderung behält. Dieses Prinzip übertragen wir auf Claude Code: + +- Statt ML-Training: Code-Qualität, Konfigurationen, Prompts und Skills verbessern +- Statt val_bpb: automatisierte Tests, Benchmarks und dein Urteil als Metrik +- Statt einer GPU: Claude Code läuft in mehreren tmux-Fenstern parallel + +Das Ergebnis: Du wachst morgens auf und Claude hat eigenständig Verbesserungen an deinen Projekten und deinem Claude Code Setup durchgeführt — dokumentiert, versioniert, rückgängig machbar. + +### Kernkonzepte + +| Konzept | Beschreibung | +|---------|-------------| +| **Experiment** | Eine isolierte Änderung in einem Git-Worktree | +| **Metrik** | Testergebnis, Build-Zeit oder subjektive Einschätzung | +| **Stuck-Detection** | Wenn 3x dieselben Dateien angefasst werden → Pause + Rückfrage | +| **Token-Awareness** | Startet nur wenn API-Budget noch ausreicht | +| **ralph-loop** | Claude Code Plugin das Claude in einer Iteration-Schleife hält | + +--- + +## Einsatz + +### Voraussetzungen + +- Linux/macOS mit tmux (`tmux -V` → mind. 3.x) +- Claude Code CLI installiert (`claude --version`) +- Python 3.10+ mit `pyyaml` und `rich` (`pip install pyyaml rich`) +- Git mit Worktree-Support (`git --version` → mind. 2.5) +- Claude Code Plugin `ralph-loop` aktiviert +- Anthropic API Key in der Umgebung (`ANTHROPIC_API_KEY`) + +### Installation + +```bash +# 1. Repo klonen +git clone git@git.tueit.de:tueit_GmbH/autoresearch.git ~/work/autoresearch + +# 2. Konfiguration anlegen +cp ~/.claude/autoresearch.yaml ~/.claude/autoresearch.yaml.bak 2>/dev/null || true +cat > ~/.claude/autoresearch.yaml << 'EOF' +projects: + - path: ~/.claude + benchmarks: [] + time_limit_minutes: 5 + + - path: ~/work/mein-projekt + benchmarks: + - "go test ./..." + time_limit_minutes: 10 + +token_threshold: + context_remaining_pct: 60 + api_budget_usd: 5.00 +EOF + +# 3. Skills installieren (falls nicht per Plugin geladen) +mkdir -p ~/.claude/skills/autoresearch +mkdir -p ~/.claude/skills/autoresearch-loop +cp ~/work/autoresearch/skills/autoresearch/skill.md ~/.claude/skills/autoresearch/skill.md +cp ~/work/autoresearch/skills/autoresearch-loop/skill.md ~/.claude/skills/autoresearch-loop/skill.md + +# 4. SessionStart-Hook in ~/.claude/settings.json eintragen +# Füge folgendes in den "hooks"-Block ein: +# "SessionStart": [{"hooks": [{"type": "command", "command": "~/work/autoresearch/bin/session-start-hook.sh", "async": true}]}] +``` + +### Manuell starten + +```bash +# Session starten +~/work/autoresearch/bin/start.sh + +# Einsteigen und zuschauen +tmux attach -t autoresearch + +# Navigation: +# Ctrl+b 0 → Overview (Log + Metriken) +# Ctrl+b 1 → Erstes Projekt +# Ctrl+b 2 → Zweites Projekt ... +# Ctrl+b d → Detach (Session läuft weiter) + +# Status abfragen +~/work/autoresearch/bin/start.sh status + +# Stoppen +~/work/autoresearch/bin/start.sh stop +``` + +### Automatischer Start + +Wenn der SessionStart-Hook konfiguriert ist, startet autoresearch automatisch bei jedem neuen Claude Code Session-Start — sofern das API-Budget über dem konfigurierten Schwellwert liegt. + +### Konfiguration (`~/.claude/autoresearch.yaml`) + +```yaml +projects: + - path: ~/work/mein-projekt # Projektverzeichnis (absolut oder ~) + benchmarks: # Shell-Befehle zur Qualitätsmessung + - "go test ./..." + - "go build ./..." + time_limit_minutes: 10 # Zeitlimit pro Experiment + +token_threshold: + context_remaining_pct: 60 # Nur starten wenn >60% Kontext frei + api_budget_usd: 5.00 # Nur starten wenn >$5 API-Budget übrig +``` + +**Projekte ohne Benchmarks** (`benchmarks: []`) werden von Claude rein subjektiv bewertet — sinnvoll für Skills, Prompts und CLAUDE.md-Dateien. + +### Experiment-Log + +Alle Experimente werden in `~/.claude/autoresearch/log.jsonl` geloggt: + +```json +{ + "ts": "2026-04-04T22:00:00Z", + "project": "kundendoku", + "exp": "0042", + "description": "Simplify SQL query in handler.go — removes N+1 pattern", + "metric_before": null, + "metric_after": null, + "kept": true, + "files_changed": ["internal/handler.go"], + "stuck": false, + "error": null +} +``` + +Live-Ansicht: tmux Window 0 (Overview) zeigt das Log fortlaufend mit Farbkodierung (grün = behalten, rot = verworfen). + +--- + +## Nachbau / Entwicklung + +### Projektstruktur + +``` +autoresearch/ +├── bin/ +│ ├── start.sh # tmux Orchestrator +│ ├── config.py # YAML-Konfiguration laden +│ ├── check_budget.py # Anthropic API Budget prüfen +│ ├── log_append.py # Experiment-Log schreiben/lesen +│ ├── log_view.py # Rich Log-Viewer (--follow) +│ ├── metrics.py # Metriken-Panel +│ ├── stuck_check.py # Stuck-Detection +│ └── session-start-hook.sh # Claude Code Hook +├── tests/ +│ ├── test_config.py +│ ├── test_check_budget.py +│ ├── test_log.py +│ └── test_stuck.py +└── docs/plans/ # Design- und Implementierungsdokumente +``` + +Skills (in `~/.claude/skills/`, nicht im Repo): +- `autoresearch/skill.md` — `/autoresearch` Skill (start/stop/status) +- `autoresearch-loop/skill.md` — Loop-Payload (wird von ralph-loop wiederholt) + +### Lokale Entwicklung + +```bash +# Abhängigkeiten +pip install pyyaml rich pytest + +# Tests ausführen +cd ~/work/autoresearch +python3 -m pytest tests/ -v + +# Einzelne Komponente testen +python3 bin/metrics.py # Metriken-Panel (leer) +python3 bin/log_view.py # Log-Viewer (leer) +python3 bin/check_budget.py 5.0 # Budget-Check (ok/low) +python3 bin/stuck_check.py mein-projekt # Stuck-Check +bash -n bin/start.sh # Bash-Syntax prüfen +``` + +### Neues Projekt hinzufügen + +1. Eintrag in `~/.claude/autoresearch.yaml` ergänzen +2. Sicherstellen dass das Projektverzeichnis ein Git-Repo ist (für Worktrees) +3. `~/work/autoresearch/bin/start.sh stop && ~/work/autoresearch/bin/start.sh` — Session neu starten + +### Architektur-Entscheidungen + +**Warum tmux statt Web-UI?** +tmux ist auf jedem Linux-Server verfügbar, braucht keine Portfreigabe und erlaubt direktes Eingreifen in laufende Prozesse. Der Overhead ist minimal. + +**Warum Git-Worktrees statt Branches?** +Worktrees erlauben parallele Entwicklung in separaten Verzeichnissen ohne Checkout-Wechsel. Jedes Experiment ist vollständig isoliert und kann ohne Seiteneffekte verworfen werden. + +**Warum ralph-loop statt bash while-loop?** +Ralph-loop läuft in einer interaktiven Claude Code Session — du siehst Claudes Gedanken, Werkzeugaufrufe und Entscheidungen in Echtzeit und kannst bei Bedarf eingreifen. + +**Warum fail-open beim Budget-Check?** +Ein Netzwerkfehler zur Anthropic API soll die Forschungsschleife nicht blockieren. Im schlimmsten Fall laufen ein paar Iterationen mehr als geplant.