autoresearch/README.md

autoresearch

Autonome Forschungsschleife für Claude Code — inspiriert von 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

# 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

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

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:

{
  "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

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