Codex for Obsidian

Codex for Obsidian은 Obsidian vault 안에서 Codex CLI를 작업대처럼 쓰기 위한 데스크톱 플러그인입니다. 채팅만 하는 AI 패널이 아니라, vault 맥락을 읽고, 계획을 세우고, 수정안을 미리 보여주고, 보고서와 시각 자료를 결과물로 남기는 Codex-native Obsidian workspace를 목표로 합니다.

이 프로젝트의 핵심은 reallygood83님의 원본 Codexian 아이디어를 출발점으로 삼아, Codex를 단순 채팅창이 아니라 Claudian에서 기대하는 작업 흐름에 가까운 Obsidian-native 작업 공간으로 끌어올리는 것입니다. 즉, “노트를 읽고 답하는 플러그인”보다 “vault 맥락을 잡고, 계획하고, 수정하고, 보고서와 시각 자료를 남기는 Codex 작업대”에 가깝습니다.

Independent community project. This is not an official OpenAI or Obsidian product.

한눈에 보는 가치

사용자가 원하는 일	Codex for Obsidian이 하는 일
vault 내용을 근거로 질문하기	현재 노트, 선택 영역, pinned note/folder, @mention, Context Graph를 한 턴 컨텍스트로 묶습니다.
긴 작업을 바로 실행하지 않기	Plan Mode에서 읽기 전용 계획을 받고, Approve/Revise/Cancel로 실행 여부를 나눕니다.
노트를 안전하게 고치기	inline edit가 line diff, word diff, Markdown/table preview, stale-range recovery를 보여준 뒤 적용합니다.
보고서를 vault에 남기기	Data Forge / Insight가 Markdown 결과 노트와 HTML companion report를 저장합니다.
시각 자료까지 만들기	Codex image/code generation 경로로 PNG/SVG/infographic asset을 생성하고 노트에 연결합니다.
더 큰 심층 리서치가 필요할 때	사용자가 직접 띄운 localhost Odysseus를 선택형 provider로 연결해 Markdown/HTML/JSON 결과를 가져옵니다.

왜 이 플러그인인가

기존 Codexian의 장점은 Obsidian 안에서 Codex를 호출할 수 있다는 점이었습니다. Codex for Obsidian은 그 기반 위에 다음 경험을 더합니다.

• Claudian-like workflow: plan, review, approve, inline edit, slash command, instruction chip, context chip을 한 흐름으로 연결합니다.
• Vault-aware context: 현재 노트, 폴더, pinned context, @mention, Context Graph, Canvas/Excalidraw 읽기 전용 컨텍스트를 함께 다룹니다.
• 결과물을 남기는 작업대: 단순 답변이 아니라 Markdown 보고서, HTML companion report, visual asset, Odysseus Local 결과를 vault에 정리합니다.
• Codex-native 방향성: multi-LLM 범용 도구가 아니라 Codex CLI/app-server/exec fallback을 중심에 둡니다.
• 안전한 확장: 쓰기 기능은 Markdown 중심으로 유지하고, Canvas/Excalidraw/MCP/subagent/Odysseus는 권한과 경계를 분리합니다.

Codexian에서 확장한 지점

이 저장소는 원본 Codexian의 “Obsidian에서 Codex 호출” 경험을 유지하면서, 실제 작업 흐름에 필요한 주변 기능을 대폭 보강합니다.

• 대화형 assistant panel: app-server 기반 대화, exec fallback, retry/error card, runtime log.
• 컨텍스트 운영: note/folder pinning, Context Graph, per-message @mention, Canvas/Excalidraw 읽기 전용 인덱싱.
• 안전한 쓰기 UX: Plan Mode, scope audit, inline edit preview/apply, stale-content guard.
• 반복 작업 도구화: slash commands, $ Codex skill picker, # instruction chips, conversation resume/fork/compact/export.
• 결과물 중심 workflow: Data Forge/Insight Markdown+HTML, visual assets, Odysseus Local result import.

최근 업데이트 한눈에

Version	핵심 변화	배포 상태
0.2.37	Multi-tab conversations, inline edit word diff/Markdown preview, app-server error cards, external-directory prompt-only contract, Data Forge 시작 확인 모달	BRAT release
0.2.36	Canvas/Excalidraw Visual Context, Insight HTML v3, Instruction Mode #, MCP/subagent prompt-only visibility, Odysseus Local bridge	BRAT release
0.2.35 and earlier	app-server runtime, exec fallback, folder context, Plan Mode, slash/template foundations, compact composer	Development baseline

지금 설치하기

현재 배포 방식은 BRAT release입니다. Obsidian Community Plugin 정식 제출은 아직 진행하지 않았습니다.

1. Obsidian에서 Obsidian42 - BRAT 플러그인을 설치합니다.
2. BRAT 설정에서 Add Beta Plugin을 누릅니다.
3. 아래 저장소 URL을 입력합니다.

https://github.com/flytothesky23/codex-for-obsidian

4. Community Plugins에서 Codex for Obsidian을 활성화합니다.

최신 BRAT release: 0.2.37

Release page: https://github.com/flytothesky23/codex-for-obsidian/releases/tag/0.2.37

BRAT가 받는 release asset:

• main.js
• styles.css
• manifest.json
• versions.json

Plugin id는 기존 설정과 BRAT 호환성을 위해 아직 codexian 으로 유지합니다. 화면에 보이는 제품명만 Codex for Obsidian입니다.

핵심 기능

영역	제공 기능
Codex Chat	Obsidian 사이드바에서 Codex CLI 기반 채팅, app-server 런타임, exec fallback
Context	현재 노트, 선택 영역, pinned note/folder, per-message @mention 컨텍스트
Context Graph	vault 인덱싱, 관련 노트 추천, Markdown/Canvas/Excalidraw 읽기 전용 컨텍스트
Inline Edit	선택 텍스트, 현재 문단, 현재 노트 수정 제안, line/word diff, Markdown/table preview, stale-range recovery
Plan Mode	Shift+Tab 기반 읽기 전용 계획, Approve/Revise/Cancel, scope audit
Slash / Skill	/summarize, /todo, /risk-check, user/vault templates, $ Codex skill picker
Instruction Mode	#verify, #readonly, #korean 같은 한 턴 지시문 chip
Insight / Data Forge	Markdown 보고서, HTML companion report, Tavily 기반 web deep research 옵션
Visual Assets	Codex image generation 기반 PNG, Codex code generation 기반 SVG/infographic
Conversations	로컬 대화 목록, 이전 thread resume, fork, compact summary, transcript/handoff note
Odysseus Local	사용자가 직접 실행한 localhost Odysseus 서버를 선택형 provider로 호출

0.2.37 업데이트

0.2.37은 대화 관리, inline edit polish, app-server 오류 투명성, 외부 디렉터리 prompt-only 계약, Odysseus HTML visual enrichment smoke, Data Forge 오작동 방지 모달을 묶은 BRAT 릴리즈입니다.

• Multi-tab Conversations
  • 대화 목록에서 이전 thread를 resume할 수 있습니다.
  • 현재 또는 과거 대화를 fork, compact, transcript/handoff note로 내보낼 수 있습니다.
• Inline Edit Polish
  • 기존 line diff에 더해 word-level diff와 Markdown/table preview를 제공합니다.
  • 생성 patch 복사와 stale range recovery를 추가했습니다.
• App-server Error Transparency
  • mid-turn 오류를 일반 텍스트가 아니라 오류 카드로 표시합니다.
  • runtime log 복사와 동일 prompt retry UI를 제공합니다.
• External Directory @mention Contract
  • allowlist된 외부 디렉터리는 파일 첨부가 아니라 prompt-only/read-only 힌트로만 전달합니다.
  • raw recursive dump나 외부 경로 쓰기 권한은 부여하지 않습니다.
• Odysseus HTML Visual Enrichment
  • Odysseus Local 결과 HTML에 Codexian 생성 이미지를 연결하는 visual enrichment 경로를 smoke gate에 포함했습니다.
• Data Forge Quick Forge Safety
  • Context Graph 우측 Forge 버튼은 즉시 실행하지 않고 확인 모달을 먼저 띄웁니다.
  • Start를 눌러야 Data Forge 노트 생성이 시작됩니다.

0.2.36 업데이트

0.2.36은 Visual Context, Insight HTML, Instruction Mode, MCP/subagent visibility, Odysseus Local bridge를 포함하는 큰 BRAT 후보입니다.

• Visual Context Phase 1A-1F
  • .canvas와 .excalidraw.md를 Context Graph와 @mention에서 읽기 전용 컨텍스트로 인덱싱합니다.
  • Canvas/Excalidraw 생성이나 수정은 아직 범위 밖입니다.
• Insight HTML v3
  • internal_only, hybrid_lens, web_deep_research source mode를 분리합니다.
  • Mermaid raw 문법 노출을 줄이고, 가능한 경우 Obsidian 렌더링/PNG bridge를 사용합니다.
  • HTML report는 Deep Research 중립 라벨과 한국어 메타데이터를 사용합니다.
• Data Forge Note Refresh
  • Codexian Report Markdown 스타일을 추가했습니다.
  • 현재 Markdown 노트를 원본 불변 기본값으로 두고, Codex exec로 한국어 보고서형 Markdown을 새로 만듭니다.
• Instruction Mode #
  • 한 턴 지시문 chip을 composer에 붙이고 전송 후 자동 해제합니다.
• MCP/subagent prompt-only visibility
  • Codex 설정에서 발견한 MCP/subagent 이름을 안전하게 보여주되, 플러그인 쪽에서 MCP tool 실행이나 subagent spawn은 하지 않습니다.
• Odysseus Local Provider
  • http://127.0.0.1:7860 같은 사용자의 로컬 Odysseus 서버를 선택적으로 호출합니다.
  • 비밀번호는 저장하지 않고, 로그인 성공 시 반환된 local session cookie만 저장합니다.
  • 결과 Markdown/HTML/JSON은 vault 결과 폴더에 저장하고 원본 노트는 수정하지 않습니다.

사용 흐름

1. Codex와 노트 작업

1. Obsidian에서 노트를 엽니다.
2. 오른쪽 Codex for Obsidian 패널에서 질문합니다.
3. 필요한 노트나 폴더는 pin 또는 @mention으로 한 턴 컨텍스트에 붙입니다.
4. 파일 변경이 필요한 일은 Plan Mode 또는 inline edit preview를 먼저 확인합니다.

2. Context Graph

1. Build Context Graph로 vault 인덱스를 만듭니다.
2. Find Context로 현재 노트와 관련된 노트를 추천받습니다.
3. Markdown뿐 아니라 Canvas/Excalidraw도 읽기 전용 컨텍스트 후보가 됩니다.

3. Data Forge / Insight

1. 여러 노트나 현재 노트를 기준으로 Insight를 생성합니다.
2. 내부 노트만 쓰거나, Tavily web deep research를 켤 수 있습니다.
3. 결과는 Markdown 노트와 HTML companion report로 저장됩니다.
4. 원본 노트는 기본적으로 수정하지 않습니다.

4. Visual Asset

1. 현재 노트에서 image/visual 버튼을 누릅니다.
2. infographic, poster, diagram illustration, thumbnail 등 형식을 선택합니다.
3. Codex가 prompt를 작성하고, 사용자가 검토한 뒤 PNG/SVG를 생성합니다.
4. 생성 파일은 vault attachment/media 폴더에 저장되고 노트에 embed됩니다.

5. Odysseus Local Research

Odysseus급 심층 리서치가 필요할 때만 사용합니다.

1. 로컬에서 Odysseus 서버를 실행합니다.
2. Codex for Obsidian 설정에서 Odysseus Local Research를 켭니다.
3. 로그인 세션을 저장하거나 token/cookie 방식을 설정합니다.
4. 현재 Obsidian 노트를 기준으로 Odysseus research를 실행합니다.
5. 결과 Markdown/HTML/JSON을 vault로 가져옵니다.

이 기능은 Odysseus 코드를 번들하거나 복사하지 않습니다. 사용자가 직접 실행한 localhost 서버를 호출하는 bridge입니다.

요구 사항

• Obsidian desktop
• Node.js 20+
• OpenAI Codex CLI 설치 및 로그인
• Git
• 선택 사항: oh-my-codex
• 선택 사항: Tavily API key
• 선택 사항: 로컬 Odysseus 서버

권장 CLI 설정:

npm install -g @openai/codex oh-my-codex
codex login
codex features enable image_generation
omx setup
omx doctor

Codex for Obsidian은 일반 사용에 OpenAI API key를 직접 요구하지 않습니다. 기본 채팅과 생성은 사용자의 Codex CLI 인증 세션을 사용합니다.

안전 경계

• 기본 권장 모드는 Review입니다.
• Yolo 권한 모드는 신뢰할 수 있고 백업된 vault에서만 사용하세요.
• Data Forge / Insight / infographic 생성은 안정성을 위해 계속 codex exec 경로를 사용합니다.
• Canvas/Excalidraw는 현재 읽기 전용 컨텍스트입니다.
• MCP/subagent는 prompt-only visibility입니다. 플러그인이 직접 MCP tool을 실행하거나 subagent를 spawn하지 않습니다.
• Odysseus Local Provider는 기본 비활성, localhost-only입니다.
• raw password, Tavily key, .env, Obsidian local settings, vault private data는 release asset에 포함하지 않습니다.

현재 한계

이 플러그인은 아직 “완성형 Obsidian AI workspace”가 아닙니다. 현재 명확한 잔여 작업은 다음과 같습니다.

• Codexian 자체 Odysseus-grade Deep Research clean-room engine
• 더 넓은 Settings localization 범위와 Community Plugin 정식 제출 준비
• 장시간 GUI regression smoke 자동화

Odysseus Local Provider는 강력하지만, Codexian native Insight가 Odysseus와 동등하다는 뜻은 아닙니다. Native Deep Research parity는 별도 clean-room 계획으로 관리합니다.

개발과 검증

npm install
npm run typecheck
npm run build
npm run verify:release-assets
npm run verify:stabilization

BRAT release 패키징:

npm run release:brat

release:brat는 다음을 확인합니다.

• release directory에 BRAT 필수 asset만 있는지
• SHA256SUMS가 맞는지
• zip root entry가 올바른지
• zip 내부 main.js/styles.css/manifest.json/versions.json 해시가 현재 빌드 asset과 같은지
• deterministic zip SHA가 유지되는지

현재 0.2.37 zip SHA-256:

88023755b6bf2e615e54d9182b9100b58dd4c19d49bd3a2d1879694df5edb69f

문서

• Changelog
• Development index
• Progress tracker
• Verification loop
• GUI smoke checklist
• BRAT development notes
• Odysseus-grade clean-room plan

License

MIT. See LICENSE.