How-To: Von Null zum KI-Agent-Harness

🔧

Windows, macOS & Linux

Alle Systeme unterstützt

Jede Sektion einzeln machbar

📚

Grundlegendes Terminal-Wissen

CD, LS, Ausführen von Befehlen

Teil I — Grundlagen

Arbeitsplatz einrichten

Python, Git und Terminal installieren — für Windows, macOS und Linux. Jeder Schritt erklärt, jeder Fehler gelöst.

Anfänger 20 Min

Was du am Ende hast

Ein vollständig eingerichtetes Entwicklungssystem mit Python 3.8+, Git für Versionskontrolle und einem Terminal, das alle Befehle des Projekts ausführen kann.

Schritt 1: Python installieren

💡

Gute Nachricht

Claw Code benötigt keine externen Abhängigkeiten — alles läuft mit der Python-Standardbibliothek.

Python Version prüfen

Öffne dein Terminal und gib ein:
python3 --version (macOS/Linux) oder python --version (Windows)

Python installieren (falls nötig)

Windows: Lade Python von python.org herunter
macOS: brew install python3 oder Installer von python.org
Linux: sudo apt install python3 (Ubuntu/Debian)

Installation verifizieren

Führe erneut python3 --version aus. Du solltest Python 3.8 oder höher sehen.

Schritt 2: Git installieren

bash

$ git --version
git version 2.34.1

# Falls nicht installiert:
# Windows: https://git-scm.com/download/win
# macOS: brew install git
# Linux: sudo apt install git

Schritt 3: Projekt herunterladen

bash

# Navigiere zu deinem Projekt-Ordner
$ cd ~/Documents

# Klone das Repository
$ git clone https://github.com/instructkr/claw-code.git
Cloning into 'claw-code'...

# Wechsle in das Projektverzeichnis
$ cd claw-code

# Verifiziere die Struktur
$ ls
src/ tests/ assets/ README.md ANLEITUNG.md

✅

Sektion 1 abgeschlossen!

Dein System ist bereit. Du hast Python, Git und das Claw-Code-Repository installiert.

⚠️

Häufige Fehler

"python3: command not found" → Verwende python statt python3 auf Windows
"Permission denied" → Führe das Terminal als Administrator aus
"git: command not found" → Git ist nicht im PATH — neu starten oder PATH aktualisieren

Teil I — Grundlagen

Repository klonen & erste Befehle

Die Verzeichnisstruktur verstehen und die ersten drei essenziellen Befehle ausführen.

Anfänger 15 Min

Projektstruktur verstehen

Ordner/Datei	Zweck
`src/`	Hauptquellcode — alle Python-Module
`src/main.py`	CLI-Einstiegspunkt mit 24 Befehlen
`src/commands.py`	~150 Befehls-Metadaten
`src/tools.py`	~100 Tool-Metadaten
`src/runtime.py`	Prompt-Routing & Sessions
`tests/`	49 Testfälle
`ANLEITUNG.md`	Vollständige Befehlsreferenz

Die ersten drei Befehle

Portierungsübersicht anzeigen

Zeigt eine Zusammenfassung des gesamten Python-Arbeitsbereichs.

bash

$ python3 -m src.main summary

# Claw Code — Portierungsübersicht

## Python-Arbeitsbereich
- **Dateien:** 25 Python-Dateien
- **Subsysteme:** 30+ Module
- **Befehle:** ~150 gespiegelt
- **Tools:** ~100 gespiegelt

Dateistruktur anzeigen

Listet alle Python-Dateien gruppiert nach Modulen auf.

$ python3 -m src.main manifest

== Python-Port-Manifest ==
src/main.py
src/models.py
src/commands.py
src/tools.py
... (weitere Dateien)

Subsysteme auflisten

Zeigt die Top-Level-Module des Projekts.

$ python3 -m src.main subsystems --limit 10

Subsystems (10 von 30+):
- assistant
- bridge
- commands
- context
- ...

⚠️

Wichtig

Alle Befehle müssen aus dem Projekt-Root-Verzeichnis ausgeführt werden (wo sich der src/-Ordner befindet). Bei Fehlern prüfe mit pwd, ob du im richtigen Ordner bist.

Teil I — Grundlagen

Die Drei-Schichten-Architektur

Spiegelungsschicht, Orchestrierung, Infrastruktur — wie die Schichten zusammenspielen und welche Dateien wo liegen.

Anfänger Kernkonzept 25 Min

Architektur-Überblick

Claw Code folgt einem klaren Drei-Schichten-Modell. Diese Trennung ermöglicht es, das System modular zu verstehen und zu erweitern.

Schicht	Dateien	Zweck
Spiegelung	`commands.py`, `tools.py`, `reference_data/`	JSON-Snapshots als unveränderliche Referenz
Orchestrierung	`runtime.py`, `query_engine.py`	Prompt-Routing, Sessions, Turn-Loops
Infrastruktur	`setup.py`, `context.py`, `session_store.py`	Umgebung, Persistenz, Logging

Schicht 1: Spiegelungsschicht

Diese Schicht lädt die archivierten JSON-Snapshots und stellt sie als typisierte Python-Objekte bereit:

commands.py — Lädt ~150 Befehle aus reference_data/commands_snapshot.json
tools.py — Lädt ~100 Tools aus reference_data/tools_snapshot.json
LRU-Cache für schnellen Zugriff
Unveränderliche Datenstrukturen (Frozen Dataclasses)

Schicht 2: Orchestrierungsschicht

Hier passiert die "Intelligenz" des Systems:

runtime.py — PortRuntime.route_prompt() tokenisiert Prompts und findet passende Befehle/Tools
query_engine.py — QueryEnginePort verwaltet Session-Zustände und Nachrichtenströme
Token-basiertes Scoring für Matching
Multi-Turn-Schleifen mit Budget-Kontrolle

Schicht 3: Infrastrukturschicht

Alles was das System am Laufen hält:

setup.py — Umgebungserkennung, Prefetch-Operationen
context.py — Workspace-Kontext (Pfade, Dateianzahl)
session_store.py — Persistenz in .port_sessions/
Trust-Gating für sichere Initialisierung

python

# Schau dir die Bootstrap-Phasen an
$ python3 -m src.main bootstrap-graph

Bootstrap-Phasen:
1. Prefetch
2. Trust Gate
3. CLI Parser
4. Setup
5. Deferred Init
6. Mode Routing
7. Query Submit

Teil II — Kern-Features

Befehle & Tools erkunden

Den Katalog der ~150 Befehle und ~100 Tools durchsuchen, filtern und im Detail anzeigen.

Kern 20 Min

Befehle auflisten

bash

# Alle Befehle anzeigen
$ python3 -m src.main commands

# Nur die ersten 10
$ python3 -m src.main commands --limit 10

# Nach "git" suchen
$ python3 -m src.main commands --query "git"

# Plugin-Befehle ausblenden
$ python3 -m src.main commands --no-plugin-commands

Tools auflisten

# Alle Tools anzeigen
$ python3 -m src.main tools

# Nach "file" suchen
$ python3 -m src.main tools --query "file"

# Bestimmtes Tool blockieren
$ python3 -m src.main tools --deny-tool Bash

# Alle MCP-Tools ausblenden
$ python3 -m src.main tools --no-mcp

Einzelne Einträge anzeigen

Befehl-Details anzeigen

python3 -m src.main show-command "commit" — Zeigt Name, Verantwortlichkeit und Quellhinweis eines Befehls.

Tool-Details anzeigen

python3 -m src.main show-tool "Read" — Zeigt detaillierte Informationen zu einem Tool.

💡

Pro-Tipp

Verwende --simple-mode bei Tools für eine kompakte Ansicht, wenn du nur Namen und Kurzbeschreibungen brauchst.

Teil II — Kern-Features

Prompt-Routing verstehen

Wie der Token-Scoring-Algorithmus einen Prompt an die richtigen Befehle und Tools weiterleitet.

Kern 30 Min

Der Routing-Algorithmus

Das Herzstück des Systems ist PortRuntime.route_prompt(). Es wandelt natürliche Sprache in ausführbare Befehle und Tools um.

Phase	Beschreibung
1. Tokenisierung	Prompt wird normalisiert: `/` und `-` → Leerzeichen, lowercase, Deduplizierung
2. Scoring	Für jeden Befehl/Tool: Wie viele Tokens matchen in Name, Source-Hint, Responsibility?
3. Fair-Share	Je ein bester Treffer pro Kategorie garantiert
4. Auffüllung	Rest nach Score sortiert bis zum Limit

Routing ausprobieren

bash

# Einen Prompt routen
$ python3 -m src.main route "Erstelle einen neuen Branch"

Routed Matches:
1. Command: git-branch (Score: 0.85)
2. Tool: Bash (Score: 0.72)
3. Command: commit (Score: 0.45)
...

# Limit anpassen
$ python3 -m src.main route "Lies die Datei" --limit 3

Wie der Score berechnet wird

Der Algorithmus vergleicht die Tokens des Prompts mit:

Befehls-Name — exakte Wortübereinstimmung
Source-Hint — woher der Befehl stammt
Responsibility — was der Befehl tut

Je mehr Tokens übereinstimmen, desto höher der Score (0.0 bis 1.0).

Teil II — Kern-Features

Sessions & Bootstrap

Eine vollständige Laufzeitsitzung aufbauen, persistieren und wiederherstellen.

Kern 25 Min

Session-Lebenszyklus

Sitzung erstellen

QueryEnginePort.from_workspace() sammelt Workspace-Kontext und erstellt eine neue Session.

Prompt verarbeiten

submit_message() verarbeitet den Prompt und aktualisiert das Transkript.

Kompaktierung

compact_messages_if_needed() reduziert das Transkript bei Bedarf.

Persistenz

persist_session() speichert die Session in .port_sessions/.

Bootstrap ausführen

bash

# Vollständige Session starten
$ python3 -m src.main bootstrap "Analysiere die Codebasis"

Session-Bericht:
Session-ID: sess_abc123xyz
Commands matched: 5
Tools matched: 3
Status: success

# Session speichern
$ python3 -m src.main flush-transcript "Meine Analyse-Session"

# Session laden
$ python3 -m src.main load-session sess_abc123xyz

💡

Session-ID

Die Session-ID wird bei jedem Bootstrap und Flush angezeigt. Speichere sie, um später die Session wiederherstellen zu können.

Teil II — Kern-Features

Turn-Loops & Budget-System

Multi-Turn-Schleifen ausführen, Token-Budgets verstehen und Stop-Conditions kontrollieren.

Kern 25 Min

Was sind Turn-Loops?

Ein Turn ist ein Durchgang durch das System: Prompt → Routing → (simulierte) Ausführung → Antwort. Turn-Loops führen mehrere Turns nacheinander aus, ähnlich wie ein echter Agent arbeitet.

Turn-Loop ausführen

bash

# Standard: bis zu 5 Turns
$ python3 -m src.main turn-loop "Refaktoriere den Code"

# Anzahl der Turns begrenzen
$ python3 -m src.main turn-loop "Refaktoriere" --max-turns 3

# JSON-Ausgabe für Weiterverarbeitung
$ python3 -m src.main turn-loop "Analysiere" --structured-output

Budget-System

Das System verfolgt Token-Verbrauch über Turns hinweg:

Input-Tokens — Prompt-Länge
Output-Tokens — Generierte Antwort
Total-Budget — Maximale Tokens pro Session

Bei Budget-Überschreitung wird automatisch kompaktisiert oder gestoppt.

⚠️

Hinweis

Das Budget-System ist im aktuellen Port eine Simulation. Es zeigt, wie das originale System Ressourcen verwaltet, ohne echte API-Kosten zu verursachen.

Teil III — Fortgeschritten

Permission-System & Sicherheit

Trust-Gating, Tool-Berechtigungen und die 7 Bootstrap-Phasen im Detail.

Fortgeschritten 20 Min

Trust-Gating

Die verzögerte Initialisierung wird über einen trusted-Parameter gesteuert:

trusted=True → Plugins, Skills, MCP-Prefetch und Session-Hooks aktiviert
trusted=False → Alle verzögerten Initialisierungen deaktiviert

Tool-Berechtigungen

bash

# Einzelnes Tool blockieren
$ python3 -m src.main tools --deny-tool Bash

# Mehrere Tools blockieren
$ python3 -m src.main tools --deny-tool Bash --deny-tool Write

# Nach Präfix blockieren (alle MCP-Tools)
$ python3 -m src.main tools --deny-prefix mcp__

Die 7 Bootstrap-Phasen

Prefetch — Vorab-Laden von Ressourcen
Trust Gate — Vertrauensprüfung
CLI Parser — Argumente parsen
Setup — Umgebung initialisieren
Deferred Init — Verzögerte Initialisierung
Mode Routing — Betriebsmodus wählen
Query Submit — Prompt verarbeiten

$ python3 -m src.main bootstrap-graph

Teil III — Fortgeschritten

Tests & Qualitätssicherung

Alle 49 Tests ausführen, Parity Audit durchführen, Port Manifest interpretieren.

Fortgeschritten 15 Min

Tests ausführen

bash

# Alle Tests mit verbose Output
$ python3 -m unittest discover -s tests -v

test_commands_load (test_porting_workspace.TestWorkspaceBasics) ... ok
test_tools_load (test_porting_workspace.TestWorkspaceBasics) ... ok
test_runtime_bootstrap (test_porting_workspace.TestRuntimeBasics) ... ok
... (49 Tests insgesamt)

Parity Audit

Vergleicht den Python-Arbeitsbereich mit dem archivierten TypeScript-Snapshot:

$ python3 -m src.main parity-audit

Parity Audit Report:
- Root-Datei-Abdeckung: 85%
- Verzeichnis-Abdeckung: 90%
- Befehls-Einträge: 100%
- Tool-Einträge: 100%

Was wird getestet?

Alle 24 CLI-Befehle
Befehls- und Tool-Katalog-Ladung
Session-Management
Prompt-Routing
Turn-Loop-Ausführung
JSON-Snapshot-Validität

✅

Erfolgskriterium

Alle 49 Tests sollten mit "OK" bestehen. Bei Fehlern prüfe deine Python-Version (muss 3.8+ sein).

Teil III — Fortgeschritten

Eigenes KI-System bauen

Custom Commands und Tools erstellen, eigene Routing-Strategien implementieren, das System erweitern.

Fortgeschritten 40 Min

Eigene Befehle hinzufügen

Befehle werden in src/reference_data/commands_snapshot.json definiert. Ein Befehl hat folgende Struktur:

json

{
  "name": "my-command",
  "responsibility": "Beschreibung was der Befehl tut",
  "source_hint": "my_module",
  "args": ["arg1", "arg2"]
}

Eigene Tools hinzufügen

Tools folgen einem ähnlichen Schema in src/reference_data/tools_snapshot.json:

{
  "name": "MyTool",
  "description": "Beschreibung der Tool-Funktionalität",
  "permission_level": "read-only"
}

Routing-Strategie anpassen

In src/runtime.py kannst du den Scoring-Algorithmus modifizieren:

# Beispiel: Gewichtung anpassen
def _score(self, tokens, entry):
  score = 0
  score += len(tokens & entry.name_tokens) * 2.0 # Name wichtiger
  score += len(tokens & entry.desc_tokens) * 1.0
  return score / len(tokens)

Subsystem erstellen

Neue Subsysteme werden als Pakete unter src/ angelegt:

# Neues Subsystem "custom" erstellen
$ mkdir src/custom
$ touch src/custom/__init__.py
$ touch src/custom/engine.py

# In src/custom/__init__.py:
from .engine import CustomEngine

__all__ = ["CustomEngine"]

💡

Architektur-Tipp

Behalte die Drei-Schichten-Architektur bei: Spiegelung (Daten), Orchestrierung (Logik), Infrastruktur (Persistenz). So bleibt dein Code wartbar.

🎉

Glückwunsch!

Du hast den kompletten Guide durchgearbeitet. Du verstehst nun die Architektur eines KI-Agent-Harness und kannst eigene Erweiterungen bauen. Zeit, deine Ideen umzusetzen!