BookBridge: Bidirektionaler Sync zwischen Obsidian und BookStack

Obsidian als persönliche Knowledge Base, BookStack als Team-Wiki — zwei gute Tools, die nicht miteinander reden. Dieselben Inhalte an zwei Stellen pflegen ist kein Workflow, sondern Sisyphusarbeit. Die vorhandenen Community Plugins hatten Schwächen bei der HTML-zu-Markdown-Konvertierung und keinen bidirektionalen Sync. Also selbst bauen.

BookBridge ist ein Open-Source Obsidian-Plugin, das bidirektional zwischen einem Obsidian-Vault und einer BookStack-Instanz synchronisiert. Entwickelt mit Claude Code als strukturiertem Co-Developer.

Was BookBridge löst

HTML→Markdown, das tatsächlich funktioniert. BookStack speichert intern HTML. Obsidian arbeitet mit Markdown. Komplexe Tabellen mit Colspan, BookStack-Callouts, Code-Blöcke mit Sprachmarkierung, verschachtelte Listen — das alles muss sauber konvertiert werden. Turndown mit Custom Rules statt Hoffnung und Gebet.

Bilder und Anhänge lokal im Vault. Jedes Bild, jedes PDF wird heruntergeladen und lokal gespeichert. Die Markdown-Links zeigen auf lokale Pfade. Offline-Zugriff auf alles, keine kaputten Bilder bei unerreichbarem Server.

Lösch-Synchronisation. Seite in BookStack gelöscht? BookBridge erkennt das, fragt nach und räumt auf — oder lässt es bewusst stehen. Der User entscheidet, nicht das Tool.

Conflict Resolution. Dieselbe Seite auf beiden Seiten geändert? BookBridge zeigt einen Diff und lässt den User wählen. Kein „Remote wins, Pech gehabt." Wer Daten verliert, weil ein Sync-Tool eigenmächtig entscheidet, hat kein Sync-Tool — er hat ein Risiko.

Entwicklung mit Claude Code als Co-Developer

BookBridge ist nicht mit einem „schreib mir ein Plugin"-Prompt entstanden. Die Basis war ein Multi-Agent-Setup in Claude Code mit klarer Struktur.

Zwei Agenten, getrennte Perspektiven

Ein plugin-dev Agent für die Implementierung — Obsidian API, TypeScript, BookStack REST, Turndown-Konvertierung. Ein qa-engineer für Tests, Security Audits und Konvertierungsqualität. Zwei verschiedene Perspektiven auf denselben Code, bewusst getrennt.

Vier Skills als Workflow-Stufen

Jede Phase hat klare Ein- und Ausgangskriterien. Kein Feature gilt als fertig, bevor Lint, Build und Test grün sind.

QA als Absicherung

Automatisierte Tests sind kein Nice-to-have, wenn eine KI Code schreibt — sie sind die Absicherung. Der qa-engineer Agent führt nach jeder Implementierung einen strukturierten 7-Schritt-Testdurchlauf durch: Unit Tests mit Vitest, Obsidian-API-Compliance, Security Audit und Konvertierungsqualität.

Rules als Leitplanken

Vier Rule-Dateien definieren, was erlaubt ist: Obsidian API statt Node.js-Zugriffe, requestUrl() statt fetch(), TypeScript strict, keine Tokens in Logs. Die KI hält sich konsequent daran.

Feature-Tracking

Jedes Feature hat eine ID (FE-1, FE-2), jeder Bug einen Report (BUG-1, BUG-2). Conventional Commits mit Referenz. Wirkt aufwendig, zahlt sich aber aus — spätestens wenn man drei Wochen später nachschaut, warum eine bestimmte Entscheidung getroffen wurde.

Erkenntnisse

Ohne Plan kein Ergebnis. Eine KI ersetzt nicht den Entwicklungsprozess. Architektur, Konventionen, Feature-Specs, Akzeptanzkriterien — das alles muss stehen, bevor die erste Zeile Code entsteht. Wer ohne klaren Plan eine KI auf ein Projekt loslässt, bekommt planlosen Code.

Die KI ist so gut wie das Setup. Claude Code ohne Rules, ohne Agents, ohne klare Architektur liefert generischen Output. Investition in Struktur und Kontext zahlt sich direkt aus.

Human-in-the-Loop. Jede Architekturentscheidung, jede neue Dependency, jede destruktive Operation — der Mensch entscheidet. Die KI schlägt vor, der Entwickler approved oder korrigiert. Kostet Zeit, spart die Stunden, die sonst mit dem Debugging von Halluzinationen draufgehen.

Die Konvertierung war die eigentliche Herausforderung. Nicht der Sync, nicht die API-Anbindung. HTML→Markdown→HTML roundtrip-stabil zu bekommen — das war die Arbeit. Jede Turndown Custom Rule hat Testfälle, jeder Edge Case einen Bug-Report. BookStack-Drawings können nicht sinnvoll in Markdown abgebildet werden? Dann ein ehrlicher Fallback statt kaputter Output.

TypeScript strict ist ein Feature. Gerade bei KI-generiertem Code. Kein any, kein @ts-ignore. Wenn der Compiler meckert, ist das eine Absicherung — keine Störung.

Für wen

Für alle, die Obsidian als persönliche Knowledge Base nutzen und im Team mit BookStack arbeiten. Die nicht zwei getrennte Welten pflegen wollen. Die ihre Bilder und Anhänge offline verfügbar haben möchten. Die einen Sync erwarten, der bei Konflikten fragt statt rät.

Und für alle, die sehen wollen, wie man mit einem strukturierten AI-Setup ein Community Plugin von der Idee bis zum Release bringen kann — ohne Vollzeit-Entwicklerteam.

BookBridge ist Open Source auf GitHub.