Claude Code UI 프로젝트 상세 소개

프로젝트 개요

Claude Code UI는 Anthropic 공식 Claude Code CLI를 위해 설계된 오픈 소스 웹 및 모바일 친화적인 사용자 인터페이스입니다. 이 프로젝트를 통해 사용자는 모든 Claude Code 세션과 프로젝트를 로컬 또는 원격으로 확인하고 CLI와 동일한 방식으로 관리할 수 있습니다. 이는 사용자에게 어디서든 작업할 수 있는 완전한 인터페이스를 제공합니다.

프로젝트 특징

🎨 반응형 디자인

• 크로스 플랫폼 호환성: 데스크톱, 태블릿, 모바일 장치 완벽 지원
• 적응형 레이아웃: 접을 수 있는 사이드바 및 스마트 콘텐츠 우선순위
• 터치 친화적: 스와이프 제스처 및 터치 내비게이션
• 모바일 내비게이션: 엄지손가락 조작이 편리한 하단 탭 바

💬 대화형 채팅 인터페이스

• 내장 채팅: Claude Code와 원활하게 통신하는 내장 채팅 인터페이스
• 실시간 통신: WebSocket 연결을 통해 Claude의 응답 스트리밍
• 세션 관리: 이전 대화 재개 또는 새 세션 시작
• 메시지 기록: 타임스탬프 및 메타데이터를 포함한 전체 대화 기록
• 다중 형식 지원: 텍스트, 코드 블록 및 파일 참조

🖥️ 통합 터미널 기능

• 직접 CLI 액세스: 내장 셸 기능을 통해 Claude Code CLI에 직접 액세스
• 프로세스 관리: Claude CLI 통합 프로세스 생성 및 관리
• 명령 실행: 모든 Claude Code CLI 명령 지원

📁 파일 탐색기

• 대화형 파일 트리: 구문 강조 및 실시간 편집 기능을 갖춘 대화형 파일 트리
• 실시간 파일 편집: 인터페이스에서 직접 파일 읽기, 수정 및 저장
• 구문 강조: 다양한 프로그래밍 언어 지원
• 파일 작업: 파일 및 디렉터리 생성, 이름 변경, 삭제

💾 세션 영속성

• 자동 저장: 모든 대화 자동 저장
• 세션 구성: 프로젝트 및 타임스탬프별 세션 그룹화
• 세션 작업: 대화 기록 이름 변경, 삭제 및 내보내기
• 장치 간 동기화: 모든 장치에서 세션 액세스

기술 아키텍처

시스템 아키텍처 다이어그램

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Frontend │ │ Backend │ │ Claude CLI │
│ (React/Vite) │◄──►│ (Express/WS) │◄──►│ Integration │
└─────────────────┘ └─────────────────┘ └─────────────────┘

백엔드 기술 스택

• Express 서버: RESTful API 및 정적 파일 서비스 제공
• WebSocket 서버: 채팅 및 프로젝트 새로 고침 통신용
• Claude CLI 통합: 프로세스 생성 및 관리
• 세션 관리: JSONL 파싱 및 대화 영속화
• 파일 시스템 API: 프로젝트에 파일 브라우저 제공

프론트엔드 기술 스택

• React 18: Hooks를 사용하는 현대적인 컴포넌트 아키텍처
• CodeMirror: 구문 강조 기능이 있는 고급 코드 편집기
• Vite: 빠른 빌드 도구 및 개발 서버
• Tailwind CSS: 유틸리티 우선 CSS 프레임워크

설치 및 구성

시스템 요구 사항

• Node.js v16 이상
• Claude Code CLI 설치 및 구성 완료

설치 단계

1. 저장소 복제:

git clone https://github.com/siteboon/claudecodeui.git
cd claudecodeui

2. 의존성 설치:

npm install

3. 환경 설정:

cp .env.example .env
# 필요에 따라 .env 파일 편집

4. 애플리케이션 시작:

# 개발 모드 (핫 리로드 포함)
npm run dev

5. 브라우저 열기:

• 개발 환경: http://localhost:3001

보안 설정

🔒 중요 보안 알림

모든 Claude Code 도구는 기본적으로 비활성화되어 있습니다. 이는 잠재적으로 유해한 작업이 자동으로 실행되는 것을 방지합니다.

Claude Code의 모든 기능을 사용하려면 도구를 수동으로 활성화해야 합니다:

1. 도구 설정 열기: 사이드바에서 톱니바퀴 아이콘 클릭
2. 선택적 활성화: 필요한 도구만 활성화
3. 설정 적용: 선호하는 설정이 로컬에 저장됩니다.

권장 방법: 기본 도구 활성화부터 시작하여 필요에 따라 점진적으로 더 많은 기능을 추가하세요.

주요 기능

프로젝트 관리

• 프로젝트 자동 검색: UI가 ~/.claude/projects/에서 Claude Code 프로젝트를 자동으로 검색합니다.
• 시각적 프로젝트 브라우저: 사용 가능한 모든 프로젝트와 해당 메타데이터 및 세션 수를 표시합니다.
• 프로젝트 작업: 프로젝트 이름 변경, 삭제 및 구성
• 스마트 내비게이션: 최근 프로젝트 및 세션에 빠르게 액세스

파일 관리

• 프로젝트 구조 탐색: 확장/축소 내비게이션 기능 포함
• 실시간 편집: 인터페이스에서 직접 파일 수정
• 파일 작업: 완전한 파일 및 디렉터리 관리 기능

세션 관리

• 영구 저장: 모든 세션 자동 저장
• 기록: 전체 대화 기록 추적
• 다중 세션 지원: 여러 프로젝트 세션을 동시에 관리

문제 해결

일반적인 문제 1: UI에 프로젝트가 없거나 빈 프로젝트 목록이 표시됨

해결책:

• Claude CLI가 올바르게 설치되었는지 확인하십시오.
• 최소한 하나의 프로젝트 디렉터리에서 claude 명령을 실행하여 초기화하십시오.
• ~/.claude/projects/ 디렉터리가 존재하고 적절한 권한이 있는지 확인하십시오.

일반적인 문제 2: 파일이 로드되지 않거나, 권한 오류가 발생하거나, 디렉터리가 비어 있음

해결책:

• 프로젝트 디렉터리 권한을 확인하십시오 (터미널에서 ls -la 사용).
• 프로젝트 경로가 존재하고 액세스 가능한지 확인하십시오.
• 자세한 오류 정보는 서버 콘솔 로그를 확인하십시오.
• 프로젝트 범위 외부의 시스템 디렉터리에 액세스하려고 시도하지 않는지 확인하십시오.