213 lines
7.6 KiB
Markdown
213 lines
7.6 KiB
Markdown
# 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.
|