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