aedificium — личный учебный блокнот + лексикон, с нативной поддержкой Claude

Карточный интерфейс на http://localhost:8788 для заметок, определений (лексикона), и PDF-файлов, с чат-панелью, подключённой к Claude Code через MCP. Математика рендерится первоклассно (KaTeX). Всё на диске — обычный markdown, автоматически коммитится в git и (опционально) автоматически пушится в GitHub.

Это шаблон с открытым исходным кодом. Форкните его и склонируйте свой форк рядом с соседним код-лабом scriptorium/, затем начинайте писать.

Что вы получаете

• Карточная сетка + читалка — заметки слева, чат с Claude справа.

• Полноценная математика — $e^{i\pi}+1=0$ в строке, $$…$$ в отдельной строке, KaTeX на стороне сервера. Рендерится в карточной сетке и в читалке.

• Лексикон — одно определение на файл (lexicon/eigenvalue.md), отображается как словарная статья с заголовочным словом + синонимами + меткой области.

• Библиотека PDF — положите PDF в pdfs/; сопутствующая карточка для обсуждения появится автоматически. Нет встроенного просмотрщика — собственный в браузере лучше. Глубокая ссылка на страницы через #page=N.

• Чат — это Claude Code — вы печатаете в браузере, Claude отвечает, а ваша текущая выбранная карточка передаётся как контекст (refs=…).

• Вики-ссылки — [[slug]] в любой заметке становится кликабельной ссылкой в читалке, с глубокими ссылками /note/<slug> через History API.

• Нативный git — записи автоматически коммитятся (задержка ~3 с) и, если задан origin, автоматически пушатся. LFS предварительно настроен для PDF, чтобы GitHub корректно обрабатывал большие бинарные файлы.

Предварительные требования

Разработано и протестировано на macOS (arm64). Linux должен работать с аналогичной установкой пакетов.

• bun — среда выполнения JavaScript, которую использует сервер. brew install oven-sh/bun/bun.

• git-lfs — для PDF. brew install git-lfs.

• Claude Code — CLI, с которым общается чат-панель. Именно это делает блокнот интерактивным.

Настройка

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

Запуск

Один флаг важен, и его легко упустить. Claude Code требуется флаг --dangerously-load-development-channels server:aedificium для работы направления канала «браузер → Claude». Без него инструменты reply / commit_chat по-прежнему работают (Claude → браузер), но ничего из введённого в чат-панели не доходит до Claude. Тишина выглядит как баг, но это не баг.

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

Claude Code запустит bun server.ts автоматически (согласно .mcp.json). Затем откройте http://localhost:8788.

Рассмотрите алиас:

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

Правило «не запускайте bun через nohup»

Не запускайте bun самостоятельно через nohup / disown. Если сделаете это, bun становится осиротевшим процессом, отсоединённым от MCP stdio-канала Claude Code — браузер продолжит работать, но Claude потеряет reply и commit_chat, и ни одна будущая сессия Claude Code не сможет занять порт 8788 (его удерживает осиротевший процесс).

Если нужно подхватить изменение 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.

Структура

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

Соглашения на одной странице

• Типы карточек определяются автоматически, а не объявляются: файлы в notes/ — заметки, файлы в lexicon/ — записи лексикона, PDF получают сопутствующие карточки.

• Математика: $x$ в строке (доллары прилегают к содержимому), $$…$$ в отдельной строке. Особые случаи — в CLAUDE.md.

• Машинные теги в тексте: #area:calculus, #see:other-slug или просто #question. Интерфейс скрывает их из прозы и отображает как чипы.

• Вики-ссылки: [[some-slug]] (опционально [[some-slug|display text]]) разрешаются на стороне сервера и открываются в читалке.

Полная спецификация: CLAUDE.md.

Опционально — соседний код-лаб

Если вам нужен сопутствующий Python-репозиторий для моделей, ноутбуков и рисунков, используйте scriptorium-template как соседний клон:

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

Мост scriptorium aedificium.py позволяет ячейкам ноутбука отображать текст aedificium прямо в строке и сохранять рисунки matplotlib напрямую в aedificium/assets/. Задайте AEDIFICIUM_DIR (в scriptorium) или AED_SCRIPTORIUM_DIR (здесь), если эти два проекта не расположены рядом.

Настройка GitHub

Пушите на GitHub как обычно, когда LFS установлен локально:

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

Автопуш выполняется после каждого авто-коммита (задержка 5 с). Отключается через AED_NO_PUSH=1. Бесплатный тариф GitHub LFS — 1 ГБ хранилища / 1 ГБ трафика в месяц на аккаунт — с запасом хватает для личной библиотеки PDF объёмом до нескольких сотен статей.

Переменные окружения

Устранение неполадок

• «Я печатаю в чат-панели, и ничего не происходит». Почти всегда это отсутствующий флаг --dangerously-load-development-channels server:aedificium. Перезапустите Claude Code с ним.

• «Claude говорит, что инструмент reply недоступен». Bun осиротел. Убейте процесс на порту 8788, выйдите из Claude Code и войдите снова.

• «git push отказывается принимать PDF (exceeds 100 MB)». LFS не был активен, когда PDF был добавлен. Выполните git lfs install, затем git lfs migrate import --include="*.pdf" --everything, затем git push --force-with-lease (это безопасно, только если у вас единственный клон репозитория).

• «Авто-коммит остановился». Проверьте stderr у bun. Самая частая причина — конфликт слияния в data/chat.jsonl между машинами — обычно конфликт представляет собой объединение двух сторон (chat.jsonl только дополняется).

Лицензия

MIT. Адаптируйте свободно — смысл в том, что блокнот — ваш.

Авторы

Изначальная концепция, архитектура и реализация — Claus Dahl. Разделение на два репозитория (проза ↔ код) вдохновлено тем, как средневековые скриптории снабжали монастырские библиотеки — отсюда и названия.