Show GN: Obsidian Vault Terminal — 사이드바에서 Claude Code를 실행하는 올바른 방법

Obsidian Vault Terminal — 사이드바에서 Claude Code를 실행하는 올바른 방법

Obsidian Vault Terminal — 사이드바에서 Claude Code를실행하는 올바른 방법

Obsidian으로 프로젝트 문서를 관리하면서, 동시에 터미널에서 Claude Code나 Codex 같은 AI 에이전트를 실행하는 workflow에 불편함을 느낀 경험이 있는가? 기존 Obsidian 터미널 플러그인들은 Windows 환경에서 agent CLI를 제대로 다루기 어렵다는 문제가 있었다. 바로 이 문제를 해결하기 위해 등장한 것이 Vault Terminal이다.

Vault Terminal이란?

Vault Terminal은 Obsidian 우측 사이드바에 실제 터미널을 띄우고, 현재 볼트(Vault) 경로를 작업 디렉터리로 사용하는 플러그인이다. 기존 터미널 플러그인과 달리, Claude Code나 Codex CLI 같은 AI 에이전트를 사이드바에서 바로 실행할 수 있도록 설계되었다.

핵심 아이디어는 간단하다. Obsidian에서 프로젝트 문서, 설계 메모, 작업 로그를 열어두고, 우측 터미널에서는 claude, codex, git, npm 같은 CLI를 즉시 실행하는 workflow. 에이전트 CLI는 같은 볼트 안의 AGENTS.md, CLAUDE.md, 프로젝트 노트, 소스 파일을 기준으로 작업하므로, 문서와 코드의 작업 컨텍스트가 완벽하게 일치한다.

주요 기능

Vault Terminal의 핵심 기능을 정리하면 다음과 같다.

• Obsidian 우측 사이드바에서 터미널 실행: 별도 창 없이 Obsidian 내에서 터미널 사용 가능

• 볼트 경로 자동 설정: 현재 Obsidian 볼트 경로를 터미널 작업 디렉터리로 사용

• 다양한 셸 지원: PowerShell, zsh, bash 등 로컬 셸 실행 가능

• AI 에이전트 CLI 완벽 지원: Claude Code, Codex CLI, git, npm, Python 등

• Windows/macOS 지원: 각 OS에 맞는 릴리스 ZIP 제공

• Obsidian 테마 연동: 라이트/다크 테마에 맞춘 터미널 색상 자동 전환

• 멀티라인 입력 지원: Shift+Enter로 Claude Code 멀티라인 입력 처리

• 스크롤백 버퍼: 긴 출력 확인을 위한 강제 스크롤 기능

• TLS/Custom CA 설정: 기업 환경의 사용자 정의 인증서 지원

설치 방법

현재 Obsidian Community Plugin Directory 등록 심사가 진행 중이므로, GitHub Release ZIP으로 설치해야 한다.

1단계: 최신 릴리스 다운로드

OS에 맞는 패키지를 다운로드한다.

• Windows x64: VaultTerminal--windows-x64.zip

• macOS Intel: VaultTerminal--macos-x64.zip

• macOS Apple Silicon: VaultTerminal--macos-arm64.zip

다운로드 주소: https://github.com/obst2580/obsidian-powershell/releases

2단계: 볼트에 설치

다운로드한 ZIP을 다음 경로에 압축 해제한다.

/.obsidian/plugins/vault-terminal/

설치 후 플러그인 폴더 구조가 다음과 같아야 한다.

manifest.jsonmain.jsstyles.csspty-host.jsnode_modules/runtime.json

3단계: Obsidian에서 활성화

Obsidian을 재시작한 뒤 Settings → Community Plugins에서 Vault Terminal을 활성화하면 된다.

전제 조건

Vault Terminal을 정상적으로 사용하려면 다음이 시스템에 설치되어 있어야 한다.

• Obsidian Desktop: 모바일 버전은 지원하지 않음

• Node.js: 시스템 전역에 설치되어 있고 일반 터미널에서 접근 가능해야 함

• CLI 도구: claude, codex, git, npm, python 등 실행 파일이 PATH에 있어야 함

주의: VS Code 확장으로 설치된 Claude Code나 Codex는 내부 Node.js 번들을 사용하므로 작동하지 않는다. 반드시 터미널 명령어로 실행 가능한 CLI 버전이 필요하다.

실전 사용 예시

Vault Terminal의 가장 강력한 사용 사례는 문서와 코드의 작업 컨텍스트를 맞춘 AI 에이전트 활용이다.

예를 들어, 어떤 프로젝트의 Obsidian 볼트에 다음과 같은 파일이 있다고 하자.

my-project/├── AGENTS.md          # Claude Code용 에이전트 지침├── CLAUDE.md          # 프로젝트 컨텍스트 정의├── docs/│   ├── architecture.md│   └── api-reference.md└── src/└── main.py

Vault Terminal에서 claude를 실행하면, Claude Code가 AGENTS.md와 CLAUDE.md를 자동으로 참조하며, Obsidian에서 열려 있는 docs/architecture.md의 내용과 동일한 문맥으로 작업한다. 따로 터미널과 Obsidian을 오가며 폴더 경로를 복사할 필요가 없다.

또한 Git 작업도 사이드바에서 바로 수행할 수 있다. git status, git commit, git push 등을 Obsidian을 최소화하지 않고 실행하면서, 동시에 프로젝트 문서를 참조할 수 있다.

대안과의 비교

Obsidian에서 AI 에이전트와 함께 사용하는 기존 방법들이 있다. 각각 장단점이 있다.

Claudian: Obsidian 사이드탭에 Claude와 채팅 형태로 통합하는 플러그인이다. 채팅 인터페이스가직관적이라는 장점이 있지만, 터미널 기반 CLI가 아닌 만큼 복잡한 Shell 명령어 실행에는 제약이 있다.

Terminal 플러그인: Obsidian 내 터미널을 제공하는 기본 옵션이다. 그러나 Windows 환경에서 agent CLI를 실행할 때 PTY 동작, 스크롤, 색상, 특수 입력 처리에서 문제가 발생한다.

Vault Terminal의 차별점: 실제 터미널을 사이드바에 embedded한다는 점에서, 기존 채팅 기반 통합보다 더 강력한 유연성을 제공한다. Agent CLI의 모든 기능을 온전히 활용하면서도 Obsidian의 문서 관리 기능을 함께 사용할 수 있다.

아쉬운 점과 향후 전망

현재 early desktop beta 단계이므로 몇 가지 제약이 있다. Obsidian Community Plugin Directory 등록이 완료되면 ZIP 다운로드 없이 Community Plugins에서 직접 설치할 수 있게 된다. Linux 지원도 소스 빌드만 가능하므로, 향후 공식 지원이 기대된다.

또한 Windows 환경에서는 winpty를 기본으로 사용하고 ConPTY로 전환할 수 있는 옵션이 있지만, 환경에 따라 터미널 동작이 불안정할 수 있다. 사용자 피드백을 수렴하며 점차 개선되고 있는 상태다.

추천 대상

Vault Terminal은 다음과 같은 개발자에게 특히 유용하다.

• Obsidian으로 프로젝트 문서를 관리하면서 동시에 Claude Code나 Codex CLI를 사용하는 분

• 문서와 코드의 작업 디렉터리를 일치시키고 싶은 분

• 여러 에이전트를 오가며 작업하는 분

• dual monitor 환경에서문서를 보면서 agent를 원하는 분

Windows/macOS에서 Claude Code, Codex CLI 같은 agent CLI를 Obsidian과 함께 쓰는 분이라면 한 번시도할 가치가 충분히 있다. 설치는 한 번이면 되므로 부담 없이 시도해 볼 수 있다.

---

📚 출처

• https://news.hada.io/topic?id=29285

• https://github.com/obst2580/obsidian-powershell

• https://github.com/obst2580/obsidian-powershell/releases

tags: Obsidian, Claude Code, Codex, Terminal, Plugin, 개발도구, AI, 에이전트, workflow, productivity

---

📚 출처

• https://news.hada.io/topic?id=29285