aedificium — ein persönliches Lern-Notizbuch + Lexikon, Claude-nativ

Eine Card-Grid-Oberfläche auf http://localhost:8788 für Notizen, Definitionen (ein Lexikon) und PDFs, mit einem Chat-Bereich, der über MCP mit Claude Code verbunden ist. Mathematik wird erstklassig gerendert (KaTeX). Alles auf der Festplatte ist einfaches Markdown, wird automatisch per Git committet und (optional) automatisch zu GitHub gepusht.

Dies ist die Open-Source-Vorlage. Forke sie, klone deinen Fork als Schwester-Repository neben ein scriptorium/-Code-Lab und beginne zu schreiben.

Was du bekommst

• Card-Grid + Reader — Notizen links, Chat mit Claude rechts.

• Erstklassige Mathematik — $e^{i\pi}+1=0$ inline, $$…$$ als Display-Gleichung, KaTeX serverseitig. Wird im Card-Grid und im Reader gerendert.

• Lexikon — eine Definition pro Datei (lexicon/eigenvalue.md), dargestellt als Wörterbucheintrag mit Stichwort + Synonymen + Fachgebiets-Label.

• PDF-Bibliothek — Lege ein PDF in pdfs/ ab; eine Sidecar-Diskussionskarte erscheint automatisch. Kein eingebetteter Viewer – der native Viewer des Browsers ist besser. Deep-Links auf Seiten mit #page=N.

• Chat ist Claude Code — du tippst im Browser, Claude antwortet, und deine aktuelle Kartenauswahl reist als Kontext mit (refs=…).

• Wiki-Links — [[slug]] wird in jeder Notiz zu einem klickbaren Link im Reader, mit /note/<slug>-Deep-Links über die History-API.

• Git-nativ — Schreibvorgänge werden automatisch committet (debounced, ~3 s) und, falls origin gesetzt ist, automatisch gepusht. LFS ist für PDFs vorkonfiguriert, damit GitHub große Binärdateien sauber verarbeitet.

Voraussetzungen

Entwickelt und getestet auf macOS (arm64). Linux sollte mit den entsprechenden Paketinstallationen funktionieren.

• bun — die JavaScript-Laufzeit, die der Server verwendet. brew install oven-sh/bun/bun.

• git-lfs — für PDFs. brew install git-lfs.

• Claude Code — die CLI, mit der der Chat-Bereich spricht. Das macht das Notizbuch interaktiv.

Einrichtung

# Fork on GitHub first, then:
git clone git@github.com:clausd/aedificium.git
cd aedificium
bun install
git lfs install

Start

Ein Flag ist entscheidend und wird leicht übersehen. Claude Code benötigt --dangerously-load-development-channels server:aedificium, damit die Browser → Claude-Richtung des Kanals funktioniert. Ohne dieses Flag funktionieren die Tools reply / commit_chat weiterhin (Claude → Browser), aber nichts, was du in den Chat-Bereich tippst, erreicht Claude. Stille wirkt wie ein Bug und ist keiner.

claude --dangerously-load-development-channels server:aedificium

Claude Code startet bun server.ts automatisch (gemäß .mcp.json). Öffne dann http://localhost:8788.

Erwäge einen Alias:

alias claude-aed='claude --dangerously-load-development-channels server:aedificium'

Die Regel „Nicht nohup bun“

Starte bun nicht selbst mit nohup / disown. Wenn du es tust, wird bun zu einem verwaisten Prozess, der von der MCP-stdio-Pipe von Claude Code getrennt ist — der Browser funktioniert weiterhin, aber Claude verliert reply und commit_chat, und auch keine zukünftige Claude-Code-Sitzung kann Port 8788 binden (der verwaiste Prozess hält ihn besetzt).

Wenn du eine Änderung an server.ts übernehmen willst:

kill $(lsof -tiTCP:8788 -sTCP:LISTEN)   # or just kill the pid you see
# then exit + re-enter Claude Code; the harness respawns a fresh bun child.

Layout

notes/                  YYYY-MM-DD-HHMM-slug.md — free-form notes
lexicon/                <slug>.md — one term per file, dictionary style
pdfs/                   PDFs + auto-generated sidecar .md discussion cards
assets/                 pasted / dropped images referenced from cards
files/                  misc non-PDF uploads
archive/                archived cards (preserves original subdir)
data/chat.jsonl         durable chat transcript (tracked + searchable)

server.ts               the Bun app (single file, ~2500 lines)
CLAUDE.md               the design doc + Claude Code project instructions
.mcp.json               MCP config (Claude Code reads this to spawn bun)
.gitattributes          LFS routing for *.pdf

Konventionen im Überblick

• Kartenarten werden abgeleitet, nicht deklariert: Dateien in notes/ sind Notizen, Dateien in lexicon/ sind Lexikoneinträge, PDFs erhalten Sidecar-Karten.

• Mathematik: $x$ inline (Dollarzeichen umschließen den Inhalt), $$…$$ für Display-Gleichungen. Randfälle siehe CLAUDE.md.

• Maschinen-Tags im Textkörper: #area:calculus, #see:other-slug oder ein bloßes #question. Die UI verbirgt sie im Fließtext und rendert sie als Chips.

• Wiki-Links: [[some-slug]] (optional [[some-slug|display text]]) werden serverseitig aufgelöst und im Reader geöffnet.

Vollständige Spezifikation: CLAUDE.md.

Optional – das Schwester-Code-Lab

Wenn du ein begleitendes Python-Repository für Modelle, Notebooks und Abbildungen möchtest, verwende scriptorium-template als Schwester-Checkout:

your-workspace/
  aedificium/          # this repo
  scriptorium/         # from scriptorium-template

Die aedificium.py-Brücke aus scriptorium ermöglicht es Notebook-Zellen, aedificium-Prosa inline zu rendern und matplotlib-Abbildungen direkt in aedificium/assets/ zu speichern. Setze AEDIFICIUM_DIR (in scriptorium) oder AED_SCRIPTORIUM_DIR (hier), falls die beiden nicht nebeneinander liegen.

GitHub-Einrichtung

Pushe wie gewohnt zu GitHub, sobald du LFS lokal installiert hast:

git remote set-url origin git@github.com:clausd/aedificium.git
git push -u origin main

Auto-Push läuft nach jedem Auto-Commit (5 s Entprellung). Deaktivieren mit AED_NO_PUSH=1. Der kostenlose GitHub-LFS-Tarif umfasst 1 GB Speicher / 1 GB Bandbreite pro Monat und Konto — bequem ausreichend für eine persönliche PDF-Bibliothek mit bis zu ein paar hundert Papers.

Umgebungsvariablen

Fehlerbehebung

• „Ich tippe im Chat-Bereich und nichts passiert.“ Fast immer fehlt das Flag --dangerously-load-development-channels server:aedificium. Starte Claude Code damit neu.

• „Claude sagt, das reply-Werkzeug ist nicht verfügbar.“ Bun wurde verwaist. Beende den Prozess auf Port 8788, verlasse Claude Code und starte es neu.

• „git push lehnt ein PDF ab (exceeds 100 MB).“ LFS war nicht aktiv, als das PDF hinzugefügt wurde. Führe git lfs install aus, dann git lfs migrate import --include="*.pdf" --everything, dann git push --force-with-lease (nur sicher, wenn es keine anderen Klone gibt).

• „Auto-Commit gestoppt.“ Prüfe die stderr-Ausgabe von bun. Die häufigste Ursache ist ein Merge-Konflikt bei data/chat.jsonl zwischen Maschinen — der Konflikt ist normalerweise die Vereinigung beider Seiten (chat.jsonl ist append-only).

Lizenz

MIT. Passe es frei an — der Punkt ist, dass dir dein Notizbuch gehört.

Danksagungen

Ursprüngliches Konzept, Architektur und Implementierung von Claus Dahl. Die Aufteilung in zwei Repositories (Prosa ↔ Code) ist von der Art inspiriert, wie mittelalterliche Skriptorien klösterliche Bibliotheken versorgten — daher die Namen.