goralphy/CLAUDE.md

goralphy

Projekt

Autonomer Go Coding-Agent ähnlich wie Ralphy. Nutzt lokale LLMs via OpenAI-kompatibler API (Docker AI, Port 12434). Die lokalen LLMs sind klein und laufen auf einem Rechner mit 16GB RAM – daher ist die Planung und Task-Aufteilung in atomare Schritte besonders wichtig.

Das Projekt unterstützt mehrere spezialisierte Agenten die zusammenarbeiten:

• Planner-Agent: Zerlegt PRD.md in atomare, ausführbare Tasks
• Code-Agent: Führt Tasks aus, schreibt Code, dokumentiert
• Test-Agent: Führt Tests aus, analysiert Fehler, gibt Feedback an Code-Agent
• Research-Agent: Recherchiert Fragen basierend auf konfigurierbaren Quellen (GitHub, Google, Reddit, StackOverflow)

Jeder Agent dokumentiert Erkenntnisse in .agent-session.md damit Fortschritte nachvollziehbar sind und Agenten voneinander lernen können.

---

Aktueller Implementierungsstand

Fertig ✅

• main.go – Flag-Parsing, Modell-Auswahl via /v1/models API
• agent/loop.go – Worker-Loop mit Tool Calling + XML-Fallback Parser
• agent/tools.go – ToolExecutor: write_file, read_file, list_files (rekursiv), task_complete
• agent/logger.go – Verbose-Logging mit --verbose Flag
• agent/session.go – Session-Persistenz in .agent-session.md
• prd/parser.go – PRD.md Checkbox-Parser + MarkTaskComplete

In Arbeit 🔄

• agent/planner.go – Planner-Agent (Grundgerüst vorhanden, noch nicht in loop.go integriert)

Geplant 📋

• agent/code.go – Code-Agent
• agent/test.go – Test-Agent
• agent/research.go – Research-Agent

---

Architektur

Dateien

• main.go – Einstiegspunkt, Flag-Parsing, Modell-Auswahl
• agent/loop.go – Haupt-Loop, koordiniert alle Agenten
• agent/tools.go – Tool-Executor (Filesystem-Operationen)
• agent/logger.go – Strukturiertes Logging
• agent/session.go – Session-Persistenz
• agent/planner.go – Planner-Agent
• agent/code.go – Code-Agent (geplant)
• agent/test.go – Test-Agent (geplant)
• agent/research.go – Research-Agent (geplant)
• prd/parser.go – PRD.md Parser

---

Agent Interface

Jeder Agent implementiert dieses Interface:

type Agent interface {
    Run(task Task) (Result, error)
    Name() string
}

type Task struct {
    ID          int
    Title       string
    Description string
    OriginTask  string
}

type Result struct {
    Success  bool
    Output   string
    Findings string // wird in .agent-session.md dokumentiert
}

Jeder Agent bekommt:

• Einen *openai.Client für LLM-Calls
• Einen *ToolExecutor für Filesystem-Zugriff
• Einen *Logger für strukturiertes Logging
• Einen *Session für Persistenz

---

Wichtige Konventionen

• Go Modulname: llm-agent
• LLM Endpoint: http://127.0.0.1:12434/v1
• Default Modell: docker.io/ai/qwen3-coder:latest
• Arbeitsverzeichnis: ./output (per --workdir Flag)
• PRD-Datei: PRD.md (per --prd Flag)
• Session-Datei: {workdir}/.agent-session.md
• Pfade: immer relativ zum workdir, niemals absolut
• Kontext: frischer Kontext pro Task (kein Context-Bloat)
• Fehlerbehandlung: maxRetries=3 mit exponential Backoff

---

Bekannte Probleme & Workarounds

Problem	Workaround
Modell nutzt XML-Format statt JSON Tool Calling	XML-Fallback Parser in loop.go (parseXMLToolCalls)
Kleine Modelle (3B) halten sich nicht an Formate	Mindestens 7B Modell empfohlen
go run zeigt auf /tmp	os.Getwd() statt os.Executable()
LLM schreibt absoluten Pfad	sanitizePath() extrahiert relativen Teil
TASK_COMPLETE ohne Arbeit in Turn 0	Guard in runTask() – prüft ob Tool-Call stattfand
API Timeout bei großen Modellen	context.WithTimeout auf 5 Minuten

---

Commands

# Bauen
go build -o llm-agent .

# Starten
go run main.go --workdir output --prd PRD.md
go run main.go --workdir output --prd PRD.md --verbose
go run main.go --workdir output --prd PRD.md --verbose --model docker.io/ai/qwen3-coder:latest

# Tests
go test ./...
go test -v ./agent/...
go test -cover ./agent/...

---

Vorgehensweise für Claude Code

1. Verfeinere Agent-Interface und Basis-Architektur
2. Integriere planner.go in loop.go
3. Implementiere code.go (Code-Agent)
4. Teste Code-Agent mit einfachen Tasks
5. Implementiere test.go (Test-Agent)
6. Verbinde Code-Agent und Test-Agent in Feedback-Loop
7. Implementiere research.go (Research-Agent)

---

Spätere Erweiterungen

• Vektor-Datenbank: Speicherung von Agenten-Erkenntnissen und Code-Snippets für Wiederverwendbarkeit und Lernen zwischen Sessions
• Git-Integration: Automatische Commits pro Task, Steuerung via Pull Requests, Zusammenarbeit mehrerer Agenten auf separaten Branches
• Discord-Integration: Echtzeit-Monitoring und Interaktion mit Agenten über Discord Chat
• Streaming: LLM-Antworten Wort für Wort ausgeben statt auf einmal warten

---

Session-Format (.agent-session.md)

# Agent Session

Started: 2026-03-04 20:00:00
Model: docker.io/ai/qwen3-coder:latest
PRD: output/PRD.md

## Plan

###  Erstelle go.mod[1]
Origin: Projektstruktur anlegen
Description: Erstelle go.mod mit Modulname llm-agent...

## Tasks

### ✅ Erstelle go.mod
Status: complete
Started: 2026-03-04 20:00:01
Completed: 2026-03-04 20:00:45

### ❌ Erstelle main.go
Status: failed
Attempts: 3
Error: maximale Turns (10) erreicht ohne task_complete

### ⏳ Erstelle README.md
Status: pending

---

Tool-Übersicht

Tool-Übersicht

Tool	Parameter	Beschreibung
write_file	path, content	Datei schreiben, Verzeichnisse werden automatisch erstellt
read_file	path	Dateiinhalt lesen
list_files	path, recursive?	Verzeichnis auflisten, optional rekursiv
delete_file	path	Datei löschen
move_file	from, to	Datei verschieben oder umbenennen
run_command	command, args[], workdir?	Beliebigen Shell-Befehl ausführen (z.B. go build, go test)
run_tests	path?, flags[]?	go test ./... ausführen, gibt Ergebnis und Fehler zurück
git_command	args[]	Beliebigen git-Befehl ausführen (z.B. ["commit", "-m", "msg"])
git_status	–	git status – zeigt geänderte Dateien
git_diff	path?	git diff – zeigt Änderungen
git_commit	message, files[]?	Dateien stagen und committen
git_log	limit?	Letzte Commits anzeigen
web_search	query, sources[]?	Websuche, optionale Quellen: github, stackoverflow, reddit, google
fetch_url	url	Inhalt einer URL abrufen und als Text zurückgeben
task_complete	summary?	Task als erledigt markieren, optionale Zusammenfassung
task_failed	reason	Task explizit als fehlgeschlagen markieren mit Begründung

---

Sicherheitsregeln

Tool	Einschränkung
write_file, delete_file, move_file	Nur innerhalb workdir
run_command	Konfigurierbare Whitelist erlaubter Befehle
git_command	Nur im Projekt-Root, kein git push ohne Bestätigung
web_search, fetch_url	Optional deaktivierbar per Flag --no-network

---

Implementierung