coreydaley/obsidian-ai-agent-sidebar-plugin

AI 에이전트(Claude Code, OpenAI Codex, Google Gemini, GitHub Copilot 및 모든 OpenAI 호환 엔드포인트)와 채팅할 수 있는 사이드바를 추가하고, 에이전트가 사용자의 Vault 내 파일을 읽고, 생성하고, 편집하고, 이름을 변경하고, 삭제할 수 있도록 하는 Obsidian 플러그인입니다. 에이전트는 CLI 도구를 통해 사용하거나 API를 통해 직접 사용할 수 있습니다.

최소 하나 이상의 에이전트에 대한 액세스 권한 확보— CLI 도구를 설치하거나 API 키를 확보하세요:

• Claude Code CLI 또는 Anthropic API 키 → API Keys 참조

• OpenAI Codex CLI 또는 OpenAI API 키 → API Keys 참조

• Google Gemini API 키 (API 전용) → API Keys 참조

• GitHub Copilot CLI (CLI 전용)

• 로컬 Ollama, vLLM 또는 LM Studio 서버

플러그인 설치:

• 최신 릴리스에서 main.js, manifest.json, styles.css를 다운로드하세요. - 세 파일 모두를 <your-vault>/.obsidian/plugins/obsidian-ai-agent-sidebar/ 경로로 복사하세요.

• Obsidian에서:
  Settings → Community Plugins → "AI Agent Sidebar" 활성화

• 다운로드

• 리본 아이콘에서 사이드바를 열거나 **Ctrl/Cmd+P → "Open AI Agent Sidebar"**를 실행하여 채팅을 시작하세요.

멀티 에이전트 탭 (Multi-agent tabs): 대화 기록을 잃지 않고 활성화된 에이전트 간 전환 가능
CLI 및 API 모드 (CLI and API modes): 설치된 CLI 도구를 사용하거나 API 키를 통해 직접 에이전트 사용
OpenAI 호환 엔드포인트 지원 (OpenAI-compatible endpoint support): 모든 OpenAI 호환 서버(Ollama, vLLM, LM Studio 등)에 연결 가능
Vault CRUD: 에이전트가 사용자의 노트를 읽고, 생성하고, 편집하고, 이름을 변경하고, 삭제할 수 있음
스트리밍 응답 (Streaming responses): 응답이 도착하는 대로 토큰 단위로 확인 가능
자동 컨텍스트 (Auto-context): 현재 열려 있는 노트가 에이전트와 자동으로 공유됨
모델 선택 (Model selection): API 모드에서 사용 가능한 모델을 가져와 설정 페이지에서 선택 가능
대화 유지 (Persist conversations): 선택적으로 Obsidian 재시작 시에도 채팅 기록을 저장 및 복구
디버그 모드 (Debug mode): 선택적으로 채팅 패널에 가공되지 않은 CLI 출력 및 API 요청 세부 정보 표시

에이전트 (Agent)	제공자 (Provider)	CLI	API
Claude Code	Anthropic	✓	✓
...

Obsidian 데스크톱 전용 — 모바일은 지원되지 않습니다.

다음 중 최소 하나는 반드시 설치 및 인증되어 있어야 합니다:

Claude Code— docs.anthropic.com
OpenAI Codex CLI— github.com/openai/codex
GitHub Copilot CLI— docs.github.com/en/copilot/github-copilot-in-the-cli
Google Gemini API 키— Gemini는 API 전용이며, CLI는 필요하지 않습니다.
OpenAI 호환 서버 (OpenAI-compatible server)— OpenAI chat completions API를 구현하는 모든 서버 (예: Ollama, vLLM, LM Studio)

npm run build를 실행하여 main.js를 생성합니다.

main.js, manifest.json, styles.css를 다음 경로로 복사합니다:
<vault>/.obsidian/plugins/obsidian-ai-agent-sidebar/

Settings → Community Plugins에서 플러그인을 활성화합니다.

리본 아이콘(ribbon icon) 또는 커맨드 팔레트(command palette)에서 AI Agent Sidebar를 엽니다.

API 모드는 Claude, Codex, Gemini 및 OpenAI 호환 서버에서 사용할 수 있습니다. 플러그인은 셸 환경 (shell environment)에서 API 키를 읽어옵니다. 셸 프로필(.zshrc, .bash_profile 등)에 키를 설정한 후 Obsidian을 재시작하십시오.

각 제공업체(provider)에 대해 플러그인은 먼저 플러그인 전용 변수(OBSIDIAN_AI_AGENT_SIDEBAR_*)를 확인한 다음, 해당 제공업체의 자체 도구에서 사용하는 표준 변수로 대체(fallback)합니다. 플러그인 전용 변수를 사용하면 이 플러그인을 위한 **전용 API 키 (dedicated API keys)**를 생성할 수 있으므로, 동일한 제공업체 계정을 공유하는 다른 도구(CLI, 스크립트 등)와 별개로 Obsidian에서의 사용량을 추적할 수 있습니다.

OBSIDIAN_AI_AGENT_SIDEBAR_ANTHROPIC_API_KEY
ANTHROPIC_API_KEY

console.anthropic.com에서 키를 받으세요.

OBSIDIAN_AI_AGENT_SIDEBAR_OPENAI_API_KEY
OPENAI_API_KEY

platform.openai.com에서 키를 받으세요.

OBSIDIAN_AI_AGENT_SIDEBAR_GEMINI_API_KEY
GEMINI_API_KEY
GOOGLE_API_KEY

aistudio.google.com에서 키를 받으세요.

Copilot은 CLI 전용이며 자체 인증(gh auth login)을 사용합니다. API 키는 필요하지 않습니다.

인증이 필요한 OpenAI 호환 서버(예: 호스팅된 vLLM 인스턴스)는 다음에서 읽어옵니다:

OBSIDIAN_AI_AGENT_SIDEBAR_OPENAI_COMPAT_API_KEY
OPENAI_COMPAT_API_KEY

Ollama와 같은 로컬 서버는 API 키가 필요하지 않습니다 — 해당 필드를 비워두거나 비어 있지 않은 임의의 자리 표시자(placeholder)를 설정하세요.

각 제공자(provider)를 구성하려면 Settings → AI Agent Sidebar를 엽니다.

두 모드를 모두 지원하는 에이전트의 경우, 토글을 통해 CLI 모드와 API 모드 사이를 전환할 수 있습니다. CLI 모드는 설치된 도구를 호출하며, API 모드는 사용자의 키를 사용하여 제공자의 API를 직접 호출합니다.

CLI 모드: Extra CLI Args 필드와 (지원되는 경우) YOLO 모드 옵션이 표시됩니다.
API 모드: 제공자의 실시간 모델 목록에서 가져온 모델 선택기(model selector)가 표시됩니다.

활성화되면, 모든 CLI 호출 시 다음 플래그(flags)가 앞에 추가되어 대화형 확인 프롬프트(interactive confirmation prompts)를 비활성화합니다:

Agent	YOLO flags
Claude Code	--dangerously-skip-permissions
...

OpenAI 호환 에이전트는 OpenAI chat completions API를 구현하는 모든 서버에 연결할 수 있습니다. 설정에서 다음과 같이 구성하세요:

Field	Description
Base URL	서버 API의 루트 URL입니다. 예: Ollama의 경우 http://localhost:11434/v1
Model	사용할 모델 이름입니다. 예: llama3.2, qwen2.5:1.5b, mistral
API Key	선택 사항 — 서버에서 인증을 강제하는 경우에만 필요합니다

이 플러그인은 OpenAI 호환 엔드포인트에 대해 모델 목록을 가져오지 않으므로, 모델 이름을 직접 입력하십시오.

모델 목록을 가져올 수 없는 경우, 플러그인은 다음 기본값으로 대체됩니다:

Agent	Default models
Claude	claude-sonnet-4-6, claude-opus-4-6, claude-haiku-4-5-20251001
...

Option	Default	Description
Persist conversations	Off	Obsidian 재시작 시에도 채팅 기록을 저장하고 복구합니다
Debug mode	Off	채팅 패널에 가공되지 않은 CLI 출력 및 API 요청 세부 정보를 표시합니다

에이전트는 사용자의 보관함(vault)에서 다음과 같은 파일 작업(file operations)을 수행할 수 있습니다:

작업 (Operation)	설명 (Description)
read	파일의 내용을 읽습니다
write	파일을 생성하거나 덮어씁니다 (상위 폴더는 자동으로 생성됩니다)
delete	파일을 삭제합니다 — 항상 사용자의 확인이 필요합니다
rename	파일의 이름을 변경하거나 이동합니다
list	디렉터리의 내용을 나열합니다

이 플러그인은 에이전트가 방출하는 구조화된 작업 블록(structured operation blocks)을 가로채어, Obsidian의 보관함 API (vault API)를 통해 이를 실행하며, 채팅창에 무엇이 수행되었는지와 성공 여부를 보여주는 파일 작업 카드(file operation cards)를 표시합니다.

모든 파일 경로는 디렉터리 트래버설 (directory traversal)을 방지하기 위해 보관함 루트 (vault root)를 기준으로 검증됩니다. 삭제 작업은 실행 전 항상 확인 대화 상자를 표시합니다.

이 플러그인은 다음 두 가지 상황에서 Obsidian 보관함 외부의 파일에 접근합니다:

셸 프로필 파일 (항상, 시작 시)
macOS 및 Linux에서 GUI 애플리케이션은 Homebrew, nvm, Volta 및 유사한 도구들에 의해 추가된 PATH 항목과 셸 프로필에 설정된 API 키 변수가 생략된 축소된 환경을 상속받습니다. 이를 해결하기 위해, 플러그인은 시작 시 한 번 사용자의 로그인 셸 ($SHELL -l -c env)을 실행하고 그 결과로 나온 환경을 읽습니다. 이 과정에서 사용자의 셸 프로필 파일 (.zshrc, .bash_profile, .profile 등)이 실행되며, 이는 CLI 도구를 안정적으로 찾고 해당 파일에 설정된 API 키를 읽을 수 있는 유일한 방법입니다. 프로필 파일의 내용은 저장되거나 전송되지 않으며, 오직 해결된 환경 변수 (environment variables)만 사용됩니다.

CLI 도구 프로세스 (CLI 모드 전용)
CLI 모드에서 플러그인은 claude, codex, 또는 copilot을 서브프로세스 (subprocess)로 실행합니다. 이들은 보관함뿐만 아니라 전체 파일 시스템에 접근하여 실행되는 완전한 프로그램입니다. 플러그인 자체의 파일 작업 프로토콜 (:::file-op

blocks)는 모든 경로를 보관함(vault) 루트와 대조하여 검증하고 경로 탐색(traversal) 시도를 거부하지만, CLI 도구 자체는 플러그인에 의해 샌드박스(sandbox)로 제한되지 않습니다. 에이전트에게 보관함 외부의 파일을 읽거나 수정하도록 요청하는 사용자 프롬프트는 CLI 도구가 실제로 해당 작업을 수행하는 결과로 이어질 수 있습니다. YOLO 모드에서는 CLI 도구 내부의 확인 프롬프트도 비활성화됩니다. 신뢰할 수 있는 에이전트와 프롬프트가 있는 경우에만 CLI 모드를 사용하십시오.

이 플러그인은 외부 서비스와 통신합니다. 모든 네트워크 요청은 사용자 작업(메시지 전송 또는 모델 목록 가져오기)에 의해 시작되며, 백그라운드 네트워크 호출은 이루어지지 않습니다.

서비스	엔드포인트 (Endpoint)	호출 시점	이유
Anthropic API	api.anthropic.com	API 모드 전용	Claude에게 메시지를 보내고 사용 가능한 모델 목록을 가져옴
OpenAI API	api.openai.com	API 모드 전용	Codex/GPT에게 메시지를 보내고 사용 가능한 모델 목록을 가져옴
Google Generative AI API	generativelanguage.googleapis.com	API 모드 전용	Gemini에게 메시지를 보내고 사용 가능한 모델 목록을 가져옴
OpenAI 호환 서버	설정된 기본 URL (base URL)	API 모드 전용	로컬 또는 호스팅된 엔드포인트로 메시지를 보냄
Claude Code CLI	Anthropic 서버 (claude 바이너리 경유)	CLI 모드 전용	claude CLI가 Anthropic으로의 자체 네트워크 호출을 처리함
OpenAI Codex CLI	OpenAI 서버 (codex 바이너리 경유)	CLI 모드 전용	codex CLI가 OpenAI로의 자체 네트워크 호출을 처리함
GitHub Copilot CLI	GitHub 서버 (copilot 바이너리 경유)	CLI 모드 전용	copilot CLI가 GitHub로의 자체 네트워크 호출을 처리함

API 모드에서 플러그인은 사용자의 API 키를 사용하여 제공자 API와 직접 통신합니다. CLI 모드에서 플러그인은 설치된 CLI 도구를 서브프로세스 (subprocess)로 생성하며, 모든 네트워크 통신은 해당 도구가 자체 인증을 사용하여 처리합니다.

이 플러그인을 사용할 때, 열려 있는 노트의 내용과 에이전트가 읽는 모든 파일은 AI 제공업체의 서버로 전송됩니다. 제3자 AI 서비스로 전송되는 것을 원치 않는 기밀(confidential), 민감(sensitive) 또는 개인 식별 정보(personally identifiable information)가 포함된 노트에는 이 플러그인을 사용하지 마십시오.

로컬 서버(예: Ollama)를 가리키는 OpenAI 호환 엔드포인트 (OpenAI-compatible endpoint)를 사용하는 경우, 귀하의 콘텐츠는 귀하의 기기에 머무릅니다.

npm install
npm run build # 프로덕션 빌드 (production build)
npm run dev # 개발을 위한 워치 모드 (watch mode for development)

MIT