02 — Repository klonen & erste Befehle

🎯

Lernziele

Was du in dieser Sektion lernst

Nach dieser Sektion verstehst du die Verzeichnisstruktur des Claw-Code-Projekts und hast deine ersten drei Befehle erfolgreich ausgeführt. Du wirst wissen, wo welche Komponenten liegen und wie du das System erkunden kannst.

Projektstruktur verstehen

Lerne, welche Dateien und Ordner wo liegen und welche Rolle sie spielen.

Erste Befehle ausführen

Führe summary, manifest und subsystems aus und verstehe, was sie tun.

Troubleshooting beherrschen

Kenne häufige Fehler und ihre Lösungen, falls etwas nicht funktioniert.

📁

Grundlagen

Projektstruktur erklärt

Das Claw-Code-Repository folgt einer klaren Ordnung. Jeder Ordner hat eine bestimmte Aufgabe.

Wichtig

Verzeichnisübersicht

Das Repository ist in mehrere Hauptverzeichnisse unterteilt. Hier ist die vollständige Übersicht:

📦 claw-code/ # Projekt-Root

📂 src/ # Hauptquellcode — alle Python-Module

🐍 main.py # CLI-Einstiegspunkt mit 24 Befehlen

🐍 commands.py # ~150 Befehls-Metadaten

🐍 tools.py # ~100 Tool-Metadaten

🐍 runtime.py # Prompt-Routing & Sessions

🐍 models.py # Datenmodelle & Klassen

📂 reference_data/ # JSON-Snapshots

🧪 tests/ # 49 Testfälle

🎨 assets/ # Bilder, Icons, Grafiken

🦀 rust/ # Rust-Implementierung (optional)

📄 README.md # Projekt-Übersicht

📄 ANLEITUNG.md # Vollständige Befehlsreferenz

Detaillierte Erklärung der Ordner

Ordner/Datei	Inhalt	Zweck
`src/`	25+ Python-Dateien	Hauptquellcode mit allen Modulen
`src/main.py`	CLI-Einstiegspunkt	Verarbeitet alle 24 Befehle
`src/commands.py`	~150 Befehls-Metadaten	Spiegelung der verfügbaren Befehle
`src/tools.py`	~100 Tool-Metadaten	Spiegelung der verfügbaren Tools
`src/runtime.py`	Runtime-Logik	Prompt-Routing, Sessions, Turn-Loops
`src/reference_data/`	JSON-Dateien	Archivierte Snapshots als Referenz
`tests/`	49 Testdateien	Qualitätssicherung & Parity-Tests
`assets/`	Bilder, Icons	Dokumentation & Webseite
`ANLEITUNG.md`	Markdown-Dokument	Vollständige deutsche Befehlsreferenz

💡

Merke dir das

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

Erster Befehl

Befehl: summary

Zeigt eine Übersicht des gesamten Python-Arbeitsbereichs an.

Essenziell

📊

summary

Portierungsübersicht anzeigen

python3 -m src.main summary

Was macht dieser Befehl?

Der summary-Befehl zeigt eine Zusammenfassung des gesamten Python-Arbeitsbereichs. Er gibt dir einen schnellen Überblick über:

Dateien: Anzahl der Python-Dateien im Projekt
Subsysteme: Anzahl der Module/Komponenten
Befehle: Anzahl der gespiegelten Befehle (~150)
Tools: Anzahl der gespiegelten Tools (~100)

Beispielausgabe

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

## Status
✓ Alle Module geladen
✓ Referenzdaten valid
✓ Runtime bereit

✅

Erfolgreich?

Wenn du diese Ausgabe siehst, funktioniert dein Setup korrekt! Der Befehl bestätigt, dass alle Module geladen werden konnten und die Runtime bereit ist.

Zweiter Befehl

Befehl: manifest

Listet alle Python-Dateien gruppiert nach Modulen auf.

Essenziell

📋

manifest

Dateistruktur anzeigen

python3 -m src.main manifest [--sort name|time]

Optionale Parameter

--sort name — Sortiert nach Dateiname (alphabetisch)
--sort time — Sortiert nach Änderungszeit (neueste zuerst)

Was macht dieser Befehl?

Der manifest-Befehl zeigt dir eine vollständige Liste aller Python-Dateien im Projekt. Die Dateien werden nach ihrem Modul gruppiert angezeigt, sodass du sofort siehst, welche Dateien zusammengehören.

Beispielausgabe

bash

$ python3 -m src.main manifest

== Python-Port-Manifest ==

src/
main.py
models.py
commands.py
tools.py
runtime.py
query_engine.py
context.py
session_store.py
setup.py
... (weitere Dateien)

src/reference_data/
commands_snapshot.json
tools_snapshot.json

tests/
test_porting_workspace.py
test_runtime.py
... (weitere Testdateien)

Wozu ist das nützlich?

Das Manifest hilft dir in vielen Situationen:

Überblick verschaffen: Schneller Blick auf alle Dateien
Parity-Prüfung: Vergleich mit dem TypeScript-Original
Navigation: Finde schnell die Datei, die du suchst
Dokumentation: Verstehe die Projektstruktur

Dritter Befehl

Befehl: subsystems

Zeigt die Top-Level-Module und Subsysteme des Projekts.

Essenziell

🧩

subsystems

Subsysteme auflisten

python3 -m src.main subsystems [--limit N]

Optionale Parameter

--limit N — Begrenzt die Ausgabe auf N Subsysteme (Standard: alle)

Was macht dieser Befehl?

Der subsystems-Befehl listet alle Top-Level-Module und Subsysteme des Projekts auf. Ein Subsystem ist eine logische Einheit, die zusammengehörige Funktionalität kapselt — zum Beispiel commands für Befehlsverwaltung oder runtime für die Ausführungslogik.

Beispielausgabe

bash

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

Subsysteme (10 von 30+):

1. assistant
→ KI-Assistent-Integration

2. bridge
→ Adapter & Verbindungen

3. commands
→ Befehlsverwaltung (~150 Befehle)

4. context
→ Workspace-Kontext

5. runtime
→ Ausführungslogik & Routing

... und 25 weitere

Subsysteme im Detail

Jedes Subsystem hat eine spezifische Aufgabe im Gesamtsystem:

Subsystem	Aufgabe
`commands`	Verwaltung aller ~150 verfügbaren Befehle
`tools`	Verwaltung aller ~100 verfügbaren Tools
`runtime`	Prompt-Routing, Sessions, Turn-Loops
`context`	Workspace-Kontext (Pfade, Dateien)
`session_store`	Persistenz für Sessions
`query_engine`	Verarbeitung von Anfragen
`bridge`	Adapter zu externen Systemen

💡

Pro-Tipp

Verwende --limit für einen schnellen Überblick, oder lasse den Parameter weg, um alle 30+ Subsysteme zu sehen. So lernst du nach und nach die Architektur kennen.

✅

Sektion abgeschlossen

Zusammenfassung

Du hast nun die ersten drei essenziellen Befehle ausgeführt und verstehst die Projektstruktur. Hier noch einmal die wichtigsten Punkte:

summary

Zeigt eine Übersicht über Dateien, Subsysteme, Befehle und Tools. Dein "Status-Check" für das System.

manifest

Listet alle Python-Dateien auf, gruppiert nach Modulen. Ideal für Navigation und Parity-Prüfung.

subsystems

Zeigt alle Top-Level-Module. So lernst du die Architektur des Systems kennen.

🎉

Gut gemacht!

Du kannst nun das Projekt erkunden und die ersten Befehle ausführen. Im nächsten Teil lernst du die Drei-Schichten-Architektur kennen und wie die Komponenten zusammenspielen.

🔧

Hilfe

Troubleshooting

Häufige Probleme und ihre Lösungen.

Häufige Fehler

⚠️

"ModuleNotFoundError: No module named 'src'"

Ursache: Du befindest dich nicht im Projekt-Root-Verzeichnis.

Lösung: Navigiere mit cd in das Verzeichnis, das den src/-Ordner enthält. Prüfe mit ls (macOS/Linux) oder dir (Windows), ob src/ sichtbar ist.

⚠️

"python3: command not found"

Ursache: Python ist nicht installiert oder nicht im PATH.

Lösung: Verwende auf Windows python statt python3. Prüfe die Installation mit python --version.

⚠️

"Permission denied"

Ursache: Keine Ausführungsrechte für das Verzeichnis.

Lösung: Auf macOS/Linux: chmod +x für die Dateien setzen. Auf Windows: Terminal als Administrator öffnen.

⚠️

Leere Ausgabe oder Fehler bei Befehlen

Ursache: Python-Version zu alt oder beschädigte Dateien.

Lösung: Stelle sicher, dass Python 3.8+ installiert ist (python3 --version). Falls nötig, klone das Repository erneut.

Schnell-Checkliste

✓ Befinde ich mich im Projekt-Root? (siehe src/-Ordner)
✓ Ist Python 3.8+ installiert?
✓ Verwende ich den richtigen Python-Befehl? (python3 vs python)
✓ Ist das Repository vollständig geklont?

← 01: Arbeitsplatz einrichten 03: Drei-Schichten-Architektur →