Flaiwheel

Selbstgehostete Speicher- & Governance-Ebene für KI-Coding-Agenten. Verwandeln Sie jeden Bugfix in dauerhaftes Wissen. Keine Cloud. Kein Vendor-Lock-in.

🚀 Warum gibt es Flaiwheel?

KI-Coding-Agenten vergessen alles zwischen den Sitzungen. Das führt zu wiederkehrenden Fehlern, verlorenen Architektur-Entscheidungen und Wissensverlust.

Flaiwheel stellt sicher:

• Agenten suchen, bevor sie programmieren

• Agenten dokumentieren nach der Fehlerbehebung

• Commits erfassen automatisch Wissen

• Wissen baut sich über die Zeit auf

Jeder behobene Fehler macht den nächsten Fehler günstiger.

Related MCP server: MCP VectorStore Server

🧠 Was macht Flaiwheel anders?

• Persistenter KI-Speicher, der sich aufbaut — Wissen geht zwischen Sitzungen nicht verloren.

• Git-native Automatisierung — Commits werden automatisch zu strukturiertem Wissen.

• Governance, nicht nur Speicherung — Qualitäts-Gates + erzwungene Dokumentation.

• Hybride Suche + Reranking — Hochpräziser Kontext für echte Codebasen.

• Vollständig selbstgehostet — Ein einzelner Docker-Container, keine externe Infrastruktur.

• Kein Lock-in — Alles Wissen wird als strukturierte Flat-Files in Git gespeichert.

✅ Für wen ist Flaiwheel?

• Engineering-Teams, die KI-Coding-Assistenten in echten Projekten einsetzen

• Codebasen, bei denen wiederkehrende Fehler teuer sind

• Teams, die volle Datenkontrolle benötigen

• KI-native Entwicklungsumgebungen

❌ Nicht für

• Kleine Hobbyprojekte mit weniger als ein paar tausend Zeilen

• Entwickler, die nur eine bessere Autovervollständigung wollen

• Reine SaaS-Workflows ohne Interesse an Self-Hosting

🆚 Wo passt Flaiwheel hinein?

• KI-Coding-Tools generieren Code.

• RAG-Tools rufen Dokumente ab.

• Flaiwheel steuert und bündelt strukturiertes Engineering-Wissen innerhalb Ihrer eigenen Infrastruktur.

Es ersetzt nicht Ihren KI-Assistenten. Es macht ihn skalierbar zuverlässig.

📄 Whitepaper (PDF) — Vision, Architektur und Design im Detail.

⚙️ Wichtige technische Funktionen

Flaiwheel ist ein in sich geschlossener Docker-Dienst, der auf drei Ebenen arbeitet: Pull — Agenten suchen, bevor sie programmieren (search_docs, get_file_context) Push — Agenten dokumentieren während der Arbeit (write_bugfix_summary, write_architecture_doc, …) Capture — Git-Commits erfassen automatisch Wissen über einen Post-Commit-Hook, auch ohne KI-Agent

• Indiziert Ihre Projektdokumentation (.md, .pdf, .html, .docx, .rst, .txt, .json, .yaml, .csv) in eine Vektordatenbank

• Stellt einen MCP-Server bereit, mit dem sich KI-Agenten (Cursor, Claude Code, VS Code Copilot) verbinden

• Hybride Suche — kombiniert semantische Vektorsuche mit BM25-Stichwortsuche via Reciprocal Rank Fusion (RRF) für die Vorteile beider Welten

• Cross-Encoder Reranker — optionaler Reranking-Schritt, der Kandidaten mit einem Cross-Encoder-Modell neu bewertet, für deutlich höhere Präzision bei Anfragen mit Vokabular-Diskrepanzen

• Verhaltens-Direktiven — KI-Agenten durchsuchen Flaiwheel stillschweigend vor jeder Antwort, dokumentieren automatisch nach jeder Aufgabe und verwenden Wissen wieder, anstatt es neu zu erstellen — alles ohne Aufforderung

• get_file_context(filename) — lädt räumliches Wissen für jede Datei vor, die der Agent bearbeiten soll (ergänzt get_recent_sessions für vollständigen zeitlichen + räumlichen Kontext)

• Post-Commit Git-Hook — erfasst jeden fix:, feat:, refactor:, perf:, docs: Commit automatisch als strukturiertes Wissensdokument

• Lebendige Architektur — KI-Agenten sind angewiesen, sich selbst aktualisierende Mermaid.js-Diagramme für Systemkomponenten und Abläufe zu pflegen

• Ausführbare Test-Flows — Testszenarien werden im maschinenlesbaren BDD/Gherkin-Format (Given, When, Then) für die QA-Automatisierung dokumentiert

• Lernt aus Bugfixes — Agenten schreiben Bugfix-Zusammenfassungen, die sofort indiziert werden

• Strukturierte Schreib-Tools — 7 kategorienspezifische Tools (Bugfix, Architektur, API, Best-Practice, Setup, Changelog, Testfall), die Qualität an der Quelle erzwingen

• Pre-Commit-Validierung — validate_doc() prüft freies Markdown, bevor es in die Wissensdatenbank gelangt

• Ingest-Qualitäts-Gate — Dateien mit kritischen Problemen werden bei der Indizierung automatisch übersprungen (niemals gelöscht — die Dateien gehören Ihnen)

• Auto-Sync via Git — zieht UND schiebt in ein dediziertes Wissens-Repo

• Tool-Telemetrie (persistent) — verfolgt jeden MCP-Aufruf pro Projekt (Suchen, Schreiben, Fehlversuche, Muster), erkennt Wissenslücken und fordert Agenten zur Dokumentation auf — bleibt über Neustarts hinweg erhalten und ist im Web-UI sichtbar

• Impact-Metriken-API — /api/impact-metrics berechnet die geschätzte Zeitersparnis + vermiedene Regressionen; CI-Pipelines können Guardrail-Ergebnisse an /api/telemetry/ci-guardrail-report senden

• Proaktive Qualitätsprüfungen — validiert die Wissensdatenbank automatisch nach jeder Neuindizierung

• Wissens-Bootstrap — "This is the Way": analysiert unordentliche Repos, klassifiziert Dateien, erkennt Duplikate, schlägt einen Aufräumplan vor, führt ihn nach Benutzerfreigabe aus (löscht niemals Dateien)

• Cold-Start Codebase Analyzer — analyze_codebase(path) scannt ein Quellcode-Verzeichnis vollständig serverseitig (null Token, null Cloud). Verwendet Pythons eingebautes ast-Modul für Python, Regex für TypeScript/JavaScript, das vorhandene MiniLM-Embedding-Modell für Klassifizierung und Duplikaterkennung. Gibt einen bootstrap_report.md mit Sprachverteilung, Kategorienkarte, den 20 am besten dokumentierbaren Dateien, Duplikatpaaren und Abdeckungslücken zurück. Reduziert die Cold-Start-Token-Kosten bei Legacy-Codebasen um ~90%.

• Multi-Projekt-Unterstützung — ein Container verwaltet mehrere Wissens-Repos mit Isolation pro Projekt

• Enthält ein Web-UI für Konfiguration, Überwachung und Tests

Was ist neu in v3.9.29

• Glama-Tool-Erkennungs-Fix — AuthManager stürzte auf schreibgeschütztem /data ab, bevor der MCP-Server starten konnte (der wahre Grund, warum Glama 0 Tools sah). Im stdio-Cold-Start-Modus übersprungen.

• Kein print() auf stdout — 36 verbleibende print() in Watcher, Indexer, Readern, Bootstrap durch diag() (stderr) ersetzt. Verifiziert: Vollständiger MCP-Handshake gibt alle 28 Tools über stdio zurück.

• config.save() resilient — schreibgeschütztes Dateisystem protokolliert Warnung statt abzustürzen.

Vorher: v3.9.28

• Glama / MCP stdio-Fix — alle Diagnoseausgaben auf stderr verschoben; stdout ist jetzt nur noch JSON-RPC. Glama Inspector erkennt jetzt alle 28 Tools korrekt.

• Verbesserte Cold-Start-Erkennung — stdio-Cold-Start-Logik behandelt leere Docker-Volumes korrekt (kein Bootstrap / Model-Download während der Glama-Inspektion).

Vorher: v3.9.27

• Lizenz-Bereinigung — eine LICENSE-Datei (BSL 1.1) für korrekte GitHub/Glama-Erkennung; alle Dokumente und Header verweisen auf LICENSE (nicht LICENSE.md).

• Glama / stdio-Inspektion — optionale [inspect]-Abhängigkeiten und Cold-Start-stdio-Pfad für leichtgewichtige MCP-Verzeichnis-Builds.

Vorher: v3.9.26

• Claude Cowork Skill — der Flaiwheel-Workflow wird jetzt als native Claude-Skill verteilt. Der Installer schreibt .skills/skills/flaiwheel/SKILL.md in Ihr Projekt. Wenn Sie das Projekt in Claude (Cowork) öffnen, ist die Skill automatisch verfügbar — kein zusätzliches Setup erforderlich. Die Skill steuert die Wiederherstellung des Sitzungskontexts, die Wissenssuche vor dem Programmieren, die obligatorische Dokumentation nach dem Bugfix und die Zusammenfassung am Sitzungsende.

• Skill-Quelle ebenfalls in skills/flaiwheel/SKILL.md in diesem Repo zur Referenz und manuellen Installation committet.

Vorher: v3.9.25

• WSL2 automatisches Pre-Flight-Setup — WSL2 wird jetzt automatisch erkannt und ein dedizierter Pre-Flight-Block läuft vor dem Haupt-Installer-Flow. Keine manuellen Schritte erforderlich:

  1. Schaltet iptables auf das Legacy-Backend um (behebt Docker-Netzwerk- / DNAT-Fehler)

  2. Fügt den aktuellen Benutzer zur docker-Gruppe hinzu (kein permission denied mehr)

  3. Startet den Docker-Daemon via service (kein systemd auf WSL2)

  4. Fügt ein Docker-Auto-Start-Snippet zu ~/.bashrc hinzu (idempotent, läuft bei jedem WSL2-Login)

• Verstreute WSL2-Prüfungen im Skript im einzigen Pre-Flight-Block konsolidiert.

Vorher: v3.9.24

• Fix: auto-install python3 falls fehlend — der Installer verwendet python3 intensiv für JSON-Manipulation. Auf minimalen Linux/WSL2-Systemen ohne python3 schlugen Konfigurationsdatei-Schreibvorgänge stillschweigend fehl (/dev/fd/63: line N: python3: command not found). python3 wird jetzt als Voraussetzung #0 geprüft und bei Fehlen automatisch via apt/dnf/yum/pacman/brew installiert.

Vorher: v3.9.23

• Fix: Docker-Daemon-Start auf WSL2 mit iptables-legacy — Docker auf WSL2 schlägt oft stillschweigend fehl, da das Standard-iptables-nft-Backend nicht unterstützt wird. Der Installer schaltet jetzt vor dem Start von Docker via update-alternatives auf iptables-legacy um. Fügt den aktuellen Benutzer auch automatisch zur docker-Gruppe hinzu.

• Alle Installationsbefehle auf bash <(curl ...) aktualisiert — jeder angezeigte Installations-/Re-Run-Befehl im gesamten Skript (Fehlermeldungen, AGENTS.md, Cursor-Regeln, etc.) verwendet jetzt Prozess-Substitution, um WSL2-Pipe-Probleme zu vermeiden.

Vorher: v3.9.22

• Fix: curl | bash Pipe-Schreibfehler auf WSL2 — curl | bash kann auf WSL2 aufgrund von Pipe-/tmp-Berechtigungsproblemen mit curl: (23) Failure writing output fehlschlagen. Der primäre Installationsbefehl in der README ist jetzt bash <(curl ...) (Prozess-Substitution), was die Pipe vollständig vermeidet. Der Re-Exec-Block versucht auch $HOME als Fallback-Temp-Verzeichnis, wenn /tmp-Schreibvorgänge fehlschlagen. Fehlermeldung empfiehlt explizit die bash <(curl ...)-Form.

Vorher: v3.9.21

• Fix: Sudo-Guard vor Re-Exec-Block verschoben — bei Verwendung von sudo curl | bash schnitt der curl: (23)-Pipe-Fehler das Skript ab, bevor der vorherige Sudo-Guard (der nach Farben/Funktionen kam) jemals erreicht wurde. Der Guard ist jetzt die allererste ausführbare Zeile (abgesehen von set -euo pipefail), sodass er auch bei einem abgeschnittenen Download feuert. Duplizierter Guard nach Farben entfernt.

Vorher: v3.9.20

• Fix: Docker-Daemon-Start-Poll auf WSL2 — statt eines festen 5-Sekunden-Schlafs pollt der Installer jetzt nach service docker start bis zu 30 Sekunden lang alle 2 Sekunden docker info. Zeigt auch die tatsächliche Ausgabe von service docker start, damit Startfehler sichtbar sind, statt stillschweigend verschluckt zu werden.

Vorher: v3.9.19

• Fix: Docker-Daemon-Start auf WSL2 — WSL2 hat normalerweise kein systemd, daher schlug systemctl start docker stillschweigend fehl. Der Installer erkennt WSL2 jetzt via /proc/version und verwendet stattdessen sudo service docker start. Wenn Docker nach der Installation immer noch nicht läuft, wird ein klarer WSL2-spezifischer Fehler mit dem exakten Fix-Befehl und einem Tipp zum Hinzufügen zu ~/.bashrc für den Auto-Start beim Login angezeigt.

Vorher: v3.9.18

• Fix: sudo curl | bash und sudo bash install.sh blockieren — das Ausführen des Installers als Root via sudo bricht die GitHub-CLI-Authentifizierung: gh auth speichert Anmeldedaten in /root/.config/gh/ statt im Home-Verzeichnis des echten Benutzers, wodurch jeder nachfolgende gh-Aufruf fehlschlägt. Verursachte auch curl: (23) Failure writing output-Pipe-Fehler auf WSL. Der Installer erkennt jetzt SUDO_USER beim Start und beendet sich sofort mit einer klaren Nachricht, die den Benutzer auffordert, ohne sudo neu zu starten. Privilegieneskalation für Paketinstallationen wird intern gehandhabt.

Vorher: v3.9.17

• Fix: gh auth login darf nicht mit sudo ausgeführt werden — nach der automatischen Installation von gh auf Linux/WSL weist der Installer den Benutzer jetzt explizit an, gh auth login ohne sudo auszuführen. Wenn die Authentifizierung zuvor mit sudo durchgeführt wurde, landeten die Anmeldedaten in /root/.config/gh/ und waren für den aktuellen Benutzer unsichtbar, was dazu führte, dass die Authentifizierungsprüfung fehlschlug. Die Fehlermeldungen sowohl beim Post-Install als auch beim Auth-Check-Schritt warnen jetzt deutlich: Verwenden Sie kein sudo für gh auth.

Vorher: v3.9.16

• Fix: Installer funktioniert auf WSL und Nicht-Root-Linux — alle Linux-Paketmanager-Befehle (apt-get, dnf, yum, zypper, pacman), das Docker-Convenience-Skript und systemctl-Aufrufe verwenden jetzt automatisch sudo, wenn der Installer nicht als Root läuft. Root-Installationen sind nicht betroffen. Behebt Permission denied / Lock-File-Fehler auf WSL und Standard-Linux-Desktop