Claude Code Viewer 소개
Claude Code Viewer는 터미널 기반의 AI 코딩 에이전트인 Claude Code를 웹 브라우저에서 편리하게 관리하고 사용할 수 있도록 돕는 오픈소스 웹 클라이언트입니다. 기존의 Claude Code는 강력한 성능을 자랑하지만, 터미널 환경(CLI)에서만 동작하여 시각적인 정보 확인이나 긴 대화 내역을 탐색하는 데에는 다소 불편함이 있었습니다. 이 프로젝트는 이러한 제약을 해결하기 위해 개발되었으며, Claude Code의 로컬 로그 파일을 실시간으로 읽어와 현대적인 웹 UI로 시각화해 줍니다.
사용자는 이 도구를 통해 새로운 대화를 시작하거나 기존 세션을 재개할 수 있으며, 실행 중인 태스크를 실시간으로 모니터링할 수 있습니다. 특히 ~/.claude/projects 디렉터리에 저장되는 표준 로그 데이터를 데이터 소스로 활용하므로, 별도의 데이터베이스 설정 없이도 기존 작업 내역을 완벽하게 동기화하여 보여줍니다. 또한, 모바일 환경에 최적화된 반응형 디자인을 제공하여 언제 어디서나 코딩 에이전트와의 협업 상황을 확인할 수 있습니다.
최근 Anthropic에서 발표한 Claude Code는 개발자의 터미널에 상주하며 코드를 작성하고 수정하는 강력한 도구로 주목받고 있습니다. 하지만 텍스트 기반 인터페이스(TUI)는 복잡한 파일 변경 내역(Diff)을 확인하거나, 과거의 긴 대화 맥락을 파악하는 데에는 한계가 있습니다. Claude Code Viewer는 이러한 CLI 도구의 사용성을 웹 기술로 확장하여, 개발자 경험(DX)을 크게 향상시키기 위해 등장했습니다.
Anthropic의 공식 Web Client 및 다른 도구들과의 비교
-
공식 Claude Code on the Web과의 비교: Anthropic의 공식 Claude Code on the Web은 클라우드 VM에서 매번 리포지토리를 클론하고 환경을 새로 설정하는 방식입니다. 이는 로컬 설정이 없는 상태에서 빠른 테스트를 하거나 공용 컴퓨터를 사용할 때 유용합니다. 반면, Claude Code Viewer는 이미 구축된 데이터베이스나 복잡한 의존성, 모노레포(Monorepo) 설정이 완료된 사용자의 로컬 개발 환경을 그대로 활용하여 리소스 집약적인 작업을 수행하는 데 최적화되어 있습니다.
-
커뮤니티 웹 클라이언트와의 차이: webuisupport, cui 등 다양한 커뮤니티 도구가 존재하지만, Claude Code Viewer는 단순한 클라이언트가 아닌 **'세션 로그 뷰어'**로서의 전문성을 갖추고 있습니다. Zod 스키마 검증을 통해 대화 내용의 누락 없는 보존(Zero Information Loss)을 보장하며, 정보의 밀도를 조절하여 보여주는 UI(Progressive Disclosure), 세션 흐름 분석, 다국어 지원 등을 제공합니다. 특히 웹에서 직접 Git Diff를 확인하고 커밋까지 할 수 있는 기능은 타 도구와 차별화되는 핵심 요소입니다.
Claude Code Viewer의 주요 기능
Claude Code Viewer는 단순한 로그 뷰어를 넘어, 세션 제어와 프로젝트 관리를 위한 다양한 기능을 제공합니다.
실시간 세션 동기화 및 관리
-
로그 시각화:
~/.claude/projects/<project>/<session-id>.jsonl경로의 로그 파일을 실시간으로 파싱하여 대화 내용을 채팅 UI로 보여줍니다. Server-Sent Events(SSE)를 활용하여 터미널에서의 진행 상황이 웹 화면에 즉시 반영됩니다. -
세션 제어: 웹 인터페이스에서 직접 새로운 대화를 시작(
Start)하거나, 중단된 작업을 이어갈 수 있습니다(Resume). 특히Continue Session기능을 통해 세션 ID 변경 없이 기존 프로세스를 유지하며 대화를 이어갈 수 있습니다. -
검색 기능:
Cmd+K(macOS) 또는Ctrl+K(Linux/Windows) 단축키를 통해 전체 대화 내역을 빠르게 검색할 수 있습니다. 퍼지 매칭(Fuzzy matching)을 지원하여 프로젝트 전반의 컨텍스트를 쉽게 찾을 수 있습니다.
향상된 개발 워크플로우
-
Git 통합: 내장된 Git Diff 뷰어를 통해 코드 변경 사항을 시각적으로 검토할 수 있습니다. 변경된 파일 내역을 확인하고, 웹 인터페이스에서 직접 커밋(Commit) 및 푸시(Push)까지 수행할 수 있어 터미널을 오갈 필요가 없습니다.
-
파일 업로드 및 미리보기: 이미지, PDF, 텍스트 파일을 채팅창에 드래그 앤 드롭하여 업로드할 수 있습니다. 각 파일 유형에 맞는 미리보기 컴포넌트를 제공하여 에이전트에게 전달된 자료를 직관적으로 확인할 수 있습니다.
-
MCP 서버 뷰어: 현재 연결된 Model Context Protocol (MCP) 서버의 상태와 설정, 사용 가능한 도구 목록을 사이드바에서 실시간으로 확인할 수 있습니다.
원격 개발 환경 지원 및 보안
이 프로젝트는 클라이언트-서버가 분리된 아키텍처를 채택하여 원격 호스팅과 개발 워크플로우를 강력하게 지원합니다.
-
원격 및 모바일 최적화: 모바일 환경에 최적화된 반응형 UI와 사이드바, 터치 컨트롤을 제공하여 이동 중에도 프로젝트 상태를 확인할 수 있습니다. 작업 완료 시 오디오 알림을 제공하여 워크플로우의 끊김을 방지하며, 터미널 접속 없이 웹 인터페이스 내에서 코드 변경 사항을 검토하고 커밋(Commit)할 수 있어 원격지에서도 완벽한 개발 제어가 가능합니다.
-
보안 및 인증: 원격 호스팅 시 보안을 위해
CLAUDE_CODE_VIEWER_AUTH_PASSWORD환경 변수를 설정하여 기본적인 비밀번호 인증을 활성화할 수 있습니다. 다만, 이는 단일 사용자를 위한 간단한 인증 메커니즘이므로, 다중 사용자 관리나 OAuth 연동 등 고도화된 보안이 필요한 조직에서는 VPN이나 리버스 프록시와 같은 인프라 레벨의 보안 구성을 권장합니다.
사용 예시 화면
기본 대화 화면(Desktop)
기본 대화 화면(Mobile)
명령어 자동 완성(Command Completion)
파일명 자동 완성(File Completion)
변경 내역 조회(Diff Viewer)
Claude Code Viewer 설치 및 사용
Claude Code Viewer 프로젝트는 별도의 DB 없이 로컬 파일 시스템을 데이터 소스로 활용하는 가벼운 구조를 가지고 있습니다. Node.js 환경에서 동작하며, npm install 명령어로 로컬 환경에 설치하거나, npx 명령어로 즉시 실행 가능합니다:
# npx로 즉시 실행 (설치 불필요)
npx @kimuson/claude-code-viewer
# 또는 전역 설치 후 실행
npm install -g @kimuson/claude-code-viewer
claude-code-viewer
설치 후, 또는 즉시 실행 전에는 필요에 따라 환경 변수를 통해 동작을 커스터마이징할 수 있습니다. 다음은 Claude Code Viewer에서 지원하는 몇 가지 환경 변수 예시입니다:
-
CLAUDE_CODE_VIEWER_PASSWORD: 웹 뷰어 접속 시 비밀번호 인증을 활성화합니다. -
CLAUDE_CODE_VIEWER_HIDE_NO_USER_MESSAGES: 시스템 로그만 있고, 사용자 메시지가 없는 세션을 목록에서 숨깁니다. -
CLAUDE_CODE_VIEWER_PERMISSION_MODE: 도구 실행 시 승인 절차(Ask permission) 방식을 제어합니다.
또한, Claude Code Viewer 프로젝트 GitHub 저장소에서는 npm 및 npx를 사용한 설치 또는 즉시 실행 방법 외에도 docker 이미지를 빌드하여 사용하는 방법도 소개되어 있으니 참고 부탁드립니다.
라이선스
Claude Code Viewer 프로젝트는 MIT License로 공개 및 배포 되고 있습니다.
Claude Code Viewer의 npm 패키지 소개 페이지
https://www.npmjs.com/package/@kimuson/claude-code-viewer
Claude Code Viewer 프로젝트 GitHub 저장소
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 