aedificium — 개인 학습 노트 + 어휘집, Claude 네이티브

http://localhost:8788에서 실행되는 카드 그리드 UI로, 노트, 정의(어휘집), PDF를 다루며, MCP를 통해 Claude Code에 연결된 채팅 창이 포함됩니다. 수식은 일급 지원됩니다(KaTeX). 디스크에 있는 모든 것은 일반 마크다운이며, git에 자동 커밋되고 (선택적으로) GitHub에 자동 푸시됩니다.

이것은 오픈소스 템플릿입니다. 포크한 뒤, 형제 scriptorium/ 코드 랩 옆에 포크를 클론하고 작성을 시작하세요.

제공되는 기능

• 카드 그리드 + 리더 — 왼쪽에는 노트, 오른쪽에는 Claude와의 채팅이 표시됩니다.

• 일급 수식 지원 — $e^{i\pi}+1=0$ 인라인, $$…$$ 디스플레이, KaTeX 서버사이드 렌더링. 카드 그리드 및 리더에서 렌더링됩니다.

• 어휘집 — 파일당 하나의 정의(lexicon/eigenvalue.md)가 표제어 + 동의어 + 도메인 라벨과 함께 사전 항목으로 렌더링됩니다.

• PDF 라이브러리 — pdfs/에 PDF를 넣으면 사이드카 토론 카드가 자동으로 나타납니다. 내장 뷰어는 없습니다 — 브라우저 기본 뷰어가 더 낫습니다. #page=N으로 페이지에 딥링크할 수 있습니다.

• 채팅은 Claude Code — 브라우저에서 입력하면 Claude가 응답하고, 현재 선택한 카드가 컨텍스트로 함께 전달됩니다(refs=…).

• 위키 링크 — 모든 노트의 [[slug]]는 리더에서 클릭하여 열 수 있는 링크가 되며, History API를 통해 /note/<slug> 딥링크를 지원합니다.

• Git 네이티브 — 쓰기는 자동 커밋(디바운스 ~3초)되고, origin이 설정되어 있으면 자동 푸시됩니다. PDF용 LFS가 사전 구성되어 있어 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 방향이 작동하려면 Claude Code에 --dangerously-load-development-channels server:aedificium이 필요합니다. 이 플래그가 없으면 reply / commit_chat 도구는 여전히 작동하지만(Claude → 브라우저), 채팅 창에 입력하는 어떤 것도 Claude에 도달하지 않습니다. 아무 반응이 없어도 버그처럼 보일 뿐, 버그가 아닙니다.

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

Claude Code는 .mcp.json에 따라 bun server.ts를 자동으로 실행합니다. 그런 다음 http://localhost:8788을 엽니다.

별칭(alias)을 고려해 보세요:

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

"nohup bun" 금지 규칙

nohup / disown으로 bun을 직접 시작하지 마세요. 그렇게 하면 bun은 Claude Code의 MCP stdio 파이프에서 분리된 고아 프로세스가 됩니다 — 브라우저는 여전히 작동하지만 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. UI는 이를 본문에서 숨기고 칩으로 렌더링합니다.

• 위키 링크: [[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 설정

LFS가 로컬에 설치되어 있으면 평소처럼 GitHub에 푸시하세요:

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

자동 푸시는 각 자동 커밋 후에 실행됩니다(5초 디바운스). AED_NO_PUSH=1로 비활성화할 수 있습니다. GitHub LFS 무료 티어는 계정당 월 1GB 저장소 / 1GB 대역폭으로, 수백 편의 논문까지 개인 PDF 라이브러리에 충분합니다.

환경 변수

문제 해결

• "채팅 창에 입력해도 아무 일도 일어나지 않습니다." 거의 항상 --dangerously-load-development-channels server:aedificium 플래그가 빠진 경우입니다. 이 플래그를 포함해 Claude Code를 다시 시작하세요.

• "Claude가 reply 도구를 사용할 수 없다고 합니다." bun이 고아 프로세스가 된 것입니다. 포트 8788의 프로세스를 종료하고 Claude Code를 나갔다가 다시 들어오세요.

• "git push가 PDF(exceeds 100 MB)를 거부합니다." PDF를 추가할 때 LFS가 활성화되어 있지 않았다는 뜻입니다. git lfs install을 실행한 다음 git lfs migrate import --include="*.pdf" --everything, 그리고 git push --force-with-lease를 실행하세요(단독 클론일 때만 안전합니다).

• "자동 커밋이 멈췄습니다." bun의 stderr를 확인하세요. 가장 흔한 원인은 기기 간 data/chat.jsonl의 병합 충돌입니다 — 충돌은 보통 양쪽의 합집합입니다(chat.jsonl은 추가 전용입니다).

라이선스

MIT. 자유롭게 수정하세요 — 핵심은 당신이 자신의 노트를 소유한다는 것입니다.

크레딧

원래 개념, 아키텍처, 구현은 Claus Dahl이(가) 했습니다. 두 저장소 분리(산문 ↔ 코드)는 중세 필사실(scriptorium)이 수도원 도서관에 자료를 공급하던 방식에서 영감을 받았습니다 — 그래서 이름이 붙었습니다.