README file from
GithubNotePack CODEX v3
About (English)
NotePack CODEX is an Obsidian plugin that turns scattered memos into a bottom-up writing workbench. AI personas debate and annotate your notes in the background, and when your thinking stalls, a Hearthstone-style idea card pack forces you into angles you would not have picked yourself.
Key features in v3:
- Multi-seed cardpacks — pick several notes via multi-select and draw cards that synthesize cross-seed context.
- Offline capture mode — toggle AI off and just dump memos; AI catches up later.
- Batch AI annotation — multi-select cards and run annotations with a concurrency-3 queue, retry-aware.
- Plan mode trio — OpenAI / Claude / Gemini all formally validated; bring your own API keys (BYOK).
- Quantum metacognition cardpacks — five rarity tiers tuned by your set grade level.
NotePack CODEX operates on .codex files inside your vault, kept separate from regular markdown so the AI-enriched workbench does not pollute your notes. Promote favorite cards into proper markdown notes when they are ready.
The Korean documentation below is the canonical version maintained by the author.
Bottom-up writing tool — 메모를 던지면 AI 페르소나들이 토론하며 주석을 달고, 사고가 막히면 하스스톤식 아이디어 카드 뽑기로 글쓰기 주제를 강제로 파생시켜주는 옵시디언 플러그인.
원래의 mskayyali/Notepad 앱이 너무 강력해서 옵시디언 플러그인으로 옮겼고, 양자 프레임워크 기반 메타인지 난이도별 카드 뽑기 시스템과 MikaNote 스타일의 UX/UI 까지 입혔습니다.
옵시디언 vault 안에서
.codex파일 단위로 동작합니다. 일반 마크다운 노트와 분리된 워크벤치 공간에서 사고를 굴리다가, 마음에 드는 카드만 vault의 마크다운 노트로 promote합니다.
🧭 핵심 사용 흐름 — 딱 하나만 기억
질문하고 → 노트를 업데이트하고 → 더 빡센 노트를 쓰고 → 또 질문하고, 이 사이클만 반복하세요.
- 떠오르는 단상을 보드에 던집니다 (메모 추가).
- AI 페르소나들이 자동으로 주석을 달고, 카테고리를 분류해 줍니다.
- 메모가 좀 쌓이면 통합 인사이트(Synthesis) 가 카테고리 사이의 숨은 다리를 제안합니다.
- 사고가 막히면 아이디어 카드 생성(구 "카드팩 뽑기")으로 일반/주목/핵심/원형 등급 카드 5장이 나옵니다.
- keep / discard로 카드들을 솎아내며 새로운 메모를 파생시킵니다.
- 충분히 발효된 카드는 vault의 마크다운 노트로 promote.
이 한 사이클이 인간 주도 bottom-up writing의 한계를 깨도록 강제로 사고력을 시험합니다.
✨ v3.0.0 신규 기능 한눈에
멀티 시드 카드팩, 오프라인 캡처 모드, 멀티 셀렉트 일괄 AI 주석 세트 신규 + Plan mode 3종(OpenAI / Claude / Gemini) 정식 완성 + Gemini Plan 안정성·셀렉션 UX 전면 강화.
| 분류 | v3.0.0 신규 |
|---|---|
| 🎴 카드 팩 | 여러 노트 시드 기반 카드 팩 (Ctrl/Shift-click 멀티 셀렉트 → "선택 시드로 카드 팩"), cross-seed 컨텍스트 자동 탐지 |
| 🔌 오프라인 | 헤더 우측 오프라인 캡처 토글 — ON 시 AI 주석 스킵하고 순수 메모만 저장. 워크벤치 단위 |
| 📋 일괄 주석 | 멀티 셀렉트 후 "선택 카드 주석" — 동시성 3 큐, 실패 카드 자동 추적·재시도, shimmer 시각 인디케이터 |
| 🤖 Plan mode | OpenAI / Claude / Gemini Plan 3종 정식 검증 완료 — v2.0.0엔 카탈로그만 있었음 |
| 🛠 Gemini 안정성 | Code Assist project onboarding 실패 시 명확한 에러, stored stale model 식별자 자동 마이그레이션, 죽은 모델 ID 자동 제거 |
| 🎨 셀렉션 시각 | 멀티 셀렉트 카드에 좌상단 indigo ✓ 디스크 + 외곽선 + 글로우 헤일로 — 어떤 파스텔 카드 배경에서도 무조건 보임 |
| 🖱 UI 안정성 | 액션 바 가려진 카드 Ctrl-click 통과, 일괄 주석 streaming 중 render 80ms throttle로 lockout 차단 |
함께 묶인 v2.1.0 + v2.2.0 (별도 minor 릴리스 항목)
| 사이클 | 항목 |
|---|---|
| v2.1.0 | 보드 카드 크기 4단계(S/M/L/XL), 즐겨찾기 상단 영구 고정, 우측 Inspector 패널 접기/펴기, 설정 메뉴 UX 정리, Google Keep 스타일 메모 편집기 |
| v2.2.0 | 커스텀 에이전트 전면 리뉴얼(커스텀 프롬프트), 1~10개 동시 주석, Gemini CLI Plan mode 검증 |
v3.0.0 변경 디테일은 RELEASE_NOTES_3.0.0.md 참고. v2.0.0 base 기능들은 아래 섹션들에 그대로 문서화되어 있고 v3.0.0에서도 유효합니다.
✨ v2.0.0 base 기능 한눈에
Youngbin201/MikaNote의 시각 미학에서 영감을 받아 보드 전체를 바둑판형 컬러 타일로 재설계했고, AI 분석 시스템을 진짜 디베이트 기반으로 갈아엎었으며, 학년별 난이도 시스템과 GPT-5.5 Plan 같은 신모델 지원, 보안 강화까지 들어간 메이저 base.
| 분류 | v2.0.0 base |
|---|---|
| 🎨 비주얼 | 220×220 정사각 컬러 타일 보드, content type별 14가지 자동 색상, 호버 액션, 긴 메모 접기, archived/trashed dim |
| ✏️ 편집기 | Markdown 단축키 (Ctrl+B/I/U + Ctrl+Shift+S/8/T), 상단 고정 툴바 + 선택 시 버블 메뉴, 리스트/할일 자동 이어쓰기 |
| 🤖 AI 분석 | Single / Parallel / 진짜 Sequential 디베이트 모드, turn-by-turn 화면 등장, 커스텀 페르소나 |
| 📚 난이도 | 학년 기반 5단계 (1=초등 4-6학년 ~ 5=대학원), 어휘+주제 동시 제어, 카드 뽑기에도 동일 적용 |
| 🪟 팝아웃 | 카드를 별도 창으로 띄워 폰트/줄간격 슬라이더로 편안하게 쓰기 |
| 🗂️ 컨텍스트 메뉴 | 폴더 우클릭에 "새 노트팩 코덱스" 즉시 생성 (옵시디언 기본 + Notebook Navigator 지원) |
| 🔐 보안 | Gemini OAuth 평문 시크릿 제거 → BYO OAuth, AI 호출 rate limiter / retry / abort 도입 |
| 🧠 신모델 | GPT-5.5 (Plan) 기본 / GPT-5.5 / GPT-5.5 Instant / Claude 4.5 / Gemini 3 Pro Preview |
🪟 보드 — MikaNote에서 흡수한 시각 미학
- 정사각 220×220 타일 — 짧은 메모는 자연스럽게 여백, 긴 메모는 5줄 clamp + "더보기" 토글. 모든 타일 키 일치해서 멀리서 보면 진짜 바둑판처럼 정돈.
- Content type별 자동 색상 — 14종(entity / claim / question / task / idea / reference / quote / definition / opinion / reflection / narrative / comparison / thesis / general)이 각자 파스텔 톤. AI 분류만으로 카드 색이 결정되니 어떤 종류의 사고를 했는지 한눈에.
- AI 주석은 어두운 chip 통일 — 카드 색깔 무관하게 일관 가독성. 기본은 접혀 있고
🤖 AI 주석 N ▾토글로 펼치기. - Hover 액션 — 별(고정)·휴지통 아이콘이 우상단에 페이드인.
- 정렬 / 휴지통 — 고정 우선 / 최근 수정 / 생성일 / 제목 / 유형 정렬, 30일 후 자동 영구삭제.
- Inspector — 카드 클릭 시 우측 패널에 본문 + 풀 AI 주석 + 액션 버튼. 클릭으로 즉시 편집 모드.
✏️ 마크다운 편집기 — Composer & Inspector
기존 plain <textarea>를 새 MarkdownEditor 컨트롤로 전면 교체.
| 단축키 | 동작 |
|---|---|
Ctrl+B |
굵게 **...** 토글 |
Ctrl+I |
기울임 *...* 토글 |
Ctrl+U |
밑줄 <u>...</u> 토글 (마크다운 표준 외 옵시디언 호환) |
Ctrl+Shift+S |
~~...~~ 토글 |
Ctrl+Shift+8 |
글머리 기호 - |
Ctrl+Shift+T |
할일 - [ ] |
Ctrl+Shift+> |
인용문 > |
Ctrl+` |
인라인 코드 ``...`` |
Enter |
리스트/할일/인용문 자동 이어쓰기 (빈 마커는 자동 종료) |
- 상단 고정 툴바: 포커스 시 8개 버튼 노출, blur 시 숨김.
- 버블 메뉴: 텍스트 선택 시 캐럿 위에 떠오르는 미니 툴바 (Notion 스타일).
- 모든 입력은 순수 마크다운으로 저장 → vault 노트로 promote 시 그대로 호환.
🤖 AI 분석 — Single / Parallel / 진짜 Sequential
세 모드 모두 여러 페르소나(annotation agent) 가 동일 메모에 주석을 달지만 작동 방식이 다릅니다.
Single
한 페르소나만 빠르게 한 번 응답. 가벼운 일반 메모용.
Parallel
여러 페르소나가 동시 다발로 응답. 빠르고 다양한 관점, 단 서로의 의견은 모름.
Sequential (v2.0.0 핵심 개편)
페르소나끼리 진짜 디베이트. 이전 v1.x는 이름만 sequential이었고 사실 병렬이었지만, v2.0.0부터:
- 턴 1: 첫 페르소나가 sharp한 첫 stance를 잡습니다.
- 턴 2~: 다음 페르소나는 직전 턴의 한 주장을 명시적으로 push back / probe. "잠깐, 그건 좀 다른데", "그게 진짜 그래?" 같은 디베이트 톤. "OO 말에 덧붙이자면" 같은 회피 패턴은 명시적으로 금지.
- 마지막 턴: 미해결 긴장을 한 줄로 짚고 사용자가 즉시 쓸 수 있는 한 가지 다음 행동을 제시.
- 화면 등장도 진짜 turn-by-turn: 매 턴 완료 시 store가 업데이트되어 사용자는 메모 카드에서 주석이 한 개씩 차례로 등장하는 걸 봅니다 (이전엔 4개가 동시에 한꺼번에 나타났음).
같은 메모에서도 페르소나 구성·순서·난이도를 바꾸면 완전히 다른 토론이 나옵니다.
📚 학년 기반 난이도 5단계
기존 v1.x의 추상적 "Easy / Normal / Deep / Expert"를 명확한 학년 단계로 재정의. 어휘만 쉬워지는 게 아니라 주제 자체의 복잡도도 학년에 맞춰지는 게 핵심.
| Level | 대상 | 어휘 | 주제 |
|---|---|---|---|
| 1 | 초등 4-6학년 | 10세가 매일 쓰는 단어. 메타인지/인식론/존재론/프레임/메커니즘 같은 27개 학술 어휘 명시 금지 | 친구·게임·간식·만화·일상 — 철학·전략·연구방법 같은 추상 주제는 어휘만 쉬운 척으로 위장하더라도 거부 |
| 2 | 중학교 | 일상어 + 학교 과목 용어 (필요 시 1개) | 학교 주제, 정체성, 가벼운 미디어 분석 |
| 3 | 고등학교 (기본값) | 일반 학술 용어 가능 | 논증/근거/가설, 윤리적 딜레마, 문화·시민 |
| 4 | 학부 | 분야 용어, 이론적 렌즈, 방법론적 구분 | 분과 학문 문제, 방법론적 선택 |
| 5 | 대학원/전문가 | 분과 어휘 풀 활용 | 전제·메타-수준, 모델 한계, 2차 함의 |
카드 뽑기 시스템에도 동일한 학년 기준이 적용됩니다. Level 1에서 "원형(legendary)" 카드를 뽑아도 어른스러운 단어로 위장한 어려운 질문이 아니라, 초등생이 진짜 답하고 싶을 큰 질문이 5-10분 안에 답할 수 있는 형태로 나옵니다.
학년 명세가 페르소나의 default 톤을 override하도록 시스템 프롬프트 최상단에 배치 — Skeptical reader 같은 페르소나의 학술적 register가 Level 1을 무시하지 못합니다.
🎴 아이디어 카드 생성 (구 "카드팩 뽑기")
발효 중인 메모에 막히면 카드 뽑기를 누릅니다. 양자 프레임워크 기반 프롬프트가 다양성 매트릭스(question type × lens) 를 강제로 분산시켜, 같은 메모에서도 매번 다른 5장이 나옵니다.
- 등급 4단계: 기본 / 주목 / 핵심 / 원형 (v1.x의 일반/희귀/영웅/전설을 게임풍 톤 다운)
- 등급은 "원본 메모로부터의 개념적 거리"를 결정 (난이도와 별개)
- 각 카드는 hook + 큰 질문 + 브릿지 단계 + 즉시 쓸 수 있는 행동 + 확장 질문 + 추천 태그/링크 포함
- 카드를 keep하면 새 메모로 흡수, discard하면 다음 회전에서 카드 풀이 다시 섞임
- promote 시 vault에 정식 마크다운 노트로 저장
💡 통합 인사이트 (Synthesis / Ghost Notes)
엔리치된 카드가 일정량 쌓이면 자동으로 카테고리 사이의 숨은 다리를 찾는 ghost note가 생성됩니다. v2.0.0에서:
- 500ms debounce + in-flight guard — 카드 상태 변경마다 fan-out하던 v1.x의 폭주 차단.
- 보이지 않는 곳에서 quietly 작업 → 결과만 카드 형태로 보드 위쪽 banner로 등장 → claim / dismiss.
- 학년 난이도 그대로 적용.
🪟 카드 팝아웃 창
Inspector의 "별도 창" 버튼으로 한 카드를 옵시디언 별도 윈도우에 띄울 수 있습니다.
- 폰트 크기 슬라이더 (12-32pt)
- 줄간격 슬라이더 (1.0-2.4)
- 슬라이더 값은 카드별로 저장 → 같은 카드 재오픈 시 복원
- 본문은 일반 MarkdownEditor 그대로 — 단축키·툴바·자동 이어쓰기 모두 동작
긴 글을 집중해서 쓰고 싶을 때 vault의 다른 노트와 분리된 별창에서 작업.
🗂️ 폴더 우클릭 메뉴 — "새 노트팩 코덱스"
옵시디언 파일 탐색기에서 폴더를 우클릭하면 "새 노트팩 코덱스" 항목이 새 드로잉 바로 밑에 자동 추가됩니다.
| 호환 | 작동 |
|---|---|
| 옵시디언 기본 file-explorer | ✅ 폴더·빈 영역 모두 |
| Notebook Navigator | ✅ 폴더·빈 영역 모두 (v2.0.0에서 DOM hook 우회로 지원) |
| 기타 file-tree plugin | 표준 file-menu 이벤트 emit하면 자동 호환, 자체 메뉴 빌드해도 DOM 기반 폴백으로 대부분 잡음 |
| 항상 동작하는 fallback | 명령 팔레트 Ctrl+P → "Create new NotePack CODEX workbench" / 좌측 ribbon layers 아이콘 |
🧬 AI 모델 지원 (BYOK + OAuth Plan)
본 플러그인은 AI 연동 없이는 동작하지 않지만, 별도 API 충전 없이도 유료 구독으로 인증 가능한 OAuth Plan 흐름을 제공합니다 (Smart Composer 영감).
OAuth Plan (구독 인증)
| Provider | 인증 방식 | v2 기본 모델 |
|---|---|---|
| OpenAI Plan (ChatGPT 구독) | PKCE-only OAuth | GPT-5.5 (Plan) |
| Claude Plan (Anthropic 구독) | PKCE-only OAuth | Claude Sonnet 4.5 (Plan) |
| Gemini Plan | BYO OAuth (사용자가 GCP 콘솔에서 자신의 OAuth Desktop 클라이언트 발급 → Client ID/Secret 입력) | Gemini 3 Pro Preview (Plan) |
⚠️ v2.0.0 보안 변경: v1.x는 Gemini OAuth용 client_secret이 plugin 코드에 평문으로 박혀 있어 OSS 배포 시 누구나 추출 가능했습니다. v2.0.0에서 시크릿 완전 제거, 사용자가 GCP 콘솔에서 자기 OAuth 클라이언트(Desktop App)를 발급받아 Client ID + Secret을 settings에 입력하는 BYO 방식으로 전환. v1.x에서 Gemini Plan 토큰을 갖고 있던 사용자는 v2 첫 실행 시 자동 무효화 + Notice 안내됩니다.
단순 API Key (Direct API)
OAuth가 부담스러우면 일반 API Key 모드도 그대로 지원: OpenAI / Anthropic / Gemini (AI Studio) / xAI / DeepSeek / Mistral / Perplexity / OpenRouter / Azure OpenAI / Ollama / LM Studio.
페르소나 (커스텀 가능)
각 annotation agent는 (모델 ID + 페르소나 프리셋 + 출력 언어 + 사용자 정의 지시) 의 조합. 기본 제공 페르소나(Skeptical reader / Question generator / Friendly tutor 등) 외에 직접 만든 페르소나도 등록 가능 — Settings에서.
같은 메모에 다른 모델·다른 페르소나 4명이 sequential 디베이트하는 것도 OK.
🛡️ 신뢰성 — Rate limit / Retry / Abort
v1.x는 AI 호출에 어떤 throttle도 없어 카드 다발 입력 시 quota 폭주 위험이 있었습니다. v2.0.0에서:
- Per-provider 동시성 제한 (공식 API 2건, Plan 엔드포인트 1건)
- 최소 호출 간격 (공식 API 2초, Plan 6초)
- 429/503/네트워크 오류 자동 재시도 —
Retry-After헤더 존중, exponential backoff + jitter - AbortController 풀 와이어링 — 카드 삭제·문서 닫힘·재분석 트리거 시 in-flight 요청 즉시 중단
- Synthesis debounce 500ms — 카드 상태 변경마다 호출되던 fan-out 차단
429 발생 시 카드 statusText에 표시 + 분당 1회 Notice 알림 (스팸 방지).
🔁 마크다운 라운드트립
.codex 파일은 JSON이지만 카드 본문은 순수 마크다운입니다. 카드를 vault 노트로 promote하면 그대로 마크다운 노트로 저장되며, 그 반대도 가능.
- 옵시디언 기본 마크다운 처리(
- [ ]체크박스,**bold**,~~strike~~등)와 100% 호환 - 단 한 가지 예외: 밑줄(
<u>...</u>) — CommonMark에 없으나 옵시디언이 인라인 HTML로 렌더하므로 라운드트립 OK
📦 설치
GitHub Releases에서 v3.0.0 zip 다운로드 → <vault>/.obsidian/plugins/achmage-notepack-codex/에 압축 풀기 → 옵시디언 Settings → 커뮤니티 플러그인 → 활성화.
⚠️ Dropbox 안 vault 사용자 주의: vault 자체가 Dropbox로 sync되는 경우 plugin 업데이트 시 sync race로 옵시디언이 캐시된 구 main.js를 메모리에 잡는 케이스가 확인됐습니다. 새 빌드를 덮어쓴 뒤에는 NotePack CODEX 플러그인 OFF→5초→ON으로 강제 리로드 (또는 시스템 트레이의 옵시디언 완전 종료 후 재시작). 만성 재발 시 plugin 폴더만 Dropbox 밖에 두고 junction(symlink)으로 묶는 방법이 가장 안정적.
또는 BRAT plugin으로 베타 트랙 설치도 가능.
⚠️ v1.x → v2.0.0 마이그레이션 안내
v2.0.0 첫 실행 시 자동으로 처리됩니다:
.codex파일 schema v2 → v3 silent 업그레이드 (기존 카드 손실 없음)- 기존 Gemini Plan OAuth 토큰 자동 무효화 (보안 시크릿 제거 마이그레이션) → 사용자 재연결 안내 Notice
- OpenAI Plan 활성 모델이 GPT-5.2 또는 GPT-5.4였다면 자동으로 GPT-5.5 (Plan)로 swap
- UI 용어 변경: "카드팩 뽑기" → "아이디어 카드 생성", 등급 일반/희귀/영웅/전설 → 기본/주목/핵심/원형
⚠️ 사용자가 직접 처리할 항목 1건: 평문 시크릿이 v1.x 설치본에 박혀 있었으므로 자기 GCP 콘솔에서 해당 OAuth client_secret을 회전(reset) 또는 삭제 권장. v2 코드는 더 이상 그 시크릿을 사용하지 않지만, 평문이 git 히스토리·이전 빌드에 남아 있을 수 있어 회전이 가장 안전.
개인정보와 네트워크 사용
NotePack CODEX는 사용자가 선택한 AI 제공자(OpenAI, Anthropic, Gemini, OpenRouter 등)로 노트 내용을 보낼 수 있습니다.
네트워크 요청은 AI 주석 생성과 아이디어 카드 생성에만 사용됩니다. 사용자가 직접 AI 제공자 또는 인증 방식을 설정해야 AI 기능이 작동합니다.
이 플러그인은 클라이언트 측 텔레메트리, 즉 사용자 행동을 몰래 수집해 보내는 기능을 포함하지 않습니다.
🙏 영감
- mskayyali/Notepad — bottom-up writing 핵심 흐름의 원형
- Youngbin201/MikaNote — v2.0.0 시각 미학 (정사각 컬러 타일·hover 액션·정렬/휴지통)
- Smart Composer — OAuth 구독 인증 패턴
- johansan/notebook-navigator — 호환 대상
Made by Achmage (더베러 단톡방 ACH_안창현)