aedificium — un cuaderno de aprendizaje personal + léxico, nativo de Claude

Una interfaz de cuadrícula de tarjetas en http://localhost:8788 para notas, definiciones (un léxico) y PDFs, con un panel de chat conectado a Claude Code mediante MCP. Las matemáticas se renderizan de primera clase (KaTeX). Todo lo que hay en disco es markdown plano, con auto-commit a git y (opcionalmente) auto-push a GitHub.

Esta es la plantilla de código abierto. Haz un fork, clona tu fork junto a un laboratorio de código hermano scriptorium/ y empieza a escribir.

Lo que obtienes

• Cuadrícula de tarjetas + lector — notas a la izquierda, chat con Claude a la derecha.

• Matemáticas de primera clase — $e^{i\pi}+1=0$ en línea, $$…$$ en modo display, KaTeX del lado del servidor. Se renderiza en la cuadrícula de tarjetas y en el lector.

• Léxico — una definición por archivo (lexicon/eigenvalue.md), renderizada como entrada de diccionario con lema + sinónimos + etiqueta de dominio.

• Biblioteca de PDFs — coloca un PDF en pdfs/; aparece automáticamente una tarjeta de discusión auxiliar. Sin visor integrado: el nativo del navegador es mejor. Enlace profundo a páginas con #page=N.

• El chat es Claude Code — escribes en el navegador, Claude responde y tu selección actual de tarjeta viaja como contexto (refs=…).

• Wiki-enlaces — [[slug]] en cualquier nota se convierte en un enlace de clic para abrir en el lector, con enlaces profundos /note/<slug> mediante la History API.

• Nativo de Git — las escrituras hacen auto-commit (con debounce ~3 s) y, si origin está definido, auto-push. LFS preconfigurado para PDFs, de modo que GitHub maneja los binarios grandes sin problemas.

Requisitos previos

Desarrollado y probado en macOS (arm64). Linux debería funcionar con las instalaciones de paquetes equivalentes.

• bun — el entorno de ejecución de JavaScript que usa el servidor. brew install oven-sh/bun/bun.

• git-lfs — para PDFs. brew install git-lfs.

• Claude Code — la CLI con la que habla el panel de chat. Esto es lo que hace que el cuaderno sea interactivo.

Configuración

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

Lanzamiento

Una bandera es importante y es fácil pasarla por alto. Claude Code necesita --dangerously-load-development-channels server:aedificium para que funcione la dirección del canal navegador → Claude. Sin ella, las herramientas reply / commit_chat siguen funcionando (Claude → navegador), pero nada de lo que escribas en el panel de chat llega a Claude. El silencio parece un error y no lo es.

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

Claude Code ejecutará bun server.ts automáticamente (según .mcp.json). Luego abre http://localhost:8788.

Considera crear un alias:

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

La regla de «no nohup bun»

No inicies bun tú mismo con nohup / disown. Si lo haces, bun se convierte en un proceso huérfano separado de la tubería stdio MCP de Claude Code — el navegador sigue funcionando, pero Claude pierde reply y commit_chat, y ninguna sesión futura de Claude Code puede vincular el puerto 8788 tampoco (el huérfano lo está ocupando).

Si necesitas aplicar un cambio en server.ts:

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.

Estructura

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

Convenciones en una página

• Los tipos de tarjeta se infieren, no se declaran: los archivos en notes/ son notas, los archivos en lexicon/ son entradas de léxico, y los PDFs obtienen tarjetas auxiliares.

• Matemáticas: $x$ en línea (los signos de dólar van pegados al contenido), $$…$$ en modo display. Consulta CLAUDE.md para casos límite.

• Etiquetas de máquina en el cuerpo: #area:calculus, #see:other-slug o una #question simple. La interfaz las oculta de la prosa y las muestra como chips.

• Wiki-enlaces: [[some-slug]] (opcionalmente [[some-slug|texto mostrado]]) se resuelven del lado del servidor y se abren en el lector.

Especificación completa: CLAUDE.md.

Opcional — el laboratorio de código hermano

Si quieres un repositorio Python complementario para modelos, cuadernos y figuras, usa scriptorium-template como checkout hermano:

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

El puente aedificium.py de scriptorium permite que las celdas del cuaderno rendericen prosa de aedificium en línea y guarden figuras de matplotlib directamente en aedificium/assets/.

Define AEDIFICIUM_DIR (en scriptorium) o AED_SCRIPTORIUM_DIR (aquí) si los dos no están hermanados.

Configuración de GitHub

Haz push a GitHub como de costumbre una vez que tengas LFS instalado localmente:

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

El auto-push se ejecuta después de cada auto-commit (debounce de 5 s). Desactívalo con AED_NO_PUSH=1. El nivel gratuito de GitHub LFS es de 1 GB de almacenamiento / 1 GB de ancho de banda al mes por cuenta — más que suficiente para una biblioteca personal de PDFs de hasta unos cientos de artículos.

Ajustes de entorno