docs: add README with tüit intro, concept, usage and setup guide
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user