CC-Viewer

🌐 웹사이트 및 기능 둘러보기: weiesky.github.io/cc-viewer — 18개 언어 지원.

Claude Code를 기반으로, 자신의 개발 경험을 증류하여 축적한 Vibe Coding 도구입니다:

1. 능력의 상한을 끌어올립니다. /ultraPlan, /ultraReview를 로컬에서 실행할 수 있어 프로젝트 코드를 Claude 클라우드에 완전히 노출시키지 않아도 됩니다;
2. 멀티 디바이스 동시 지원. 로컬 네트워크 내에서 모바일 프로그래밍이 가능하며, 웹 버전은 다양한 시나리오에 자동 적응하여 브라우저 확장 프로그램이나 OS 분할 화면에 손쉽게 임베딩할 수 있고, 네이티브 설치 프로그램도 제공합니다;
3. 완전한 로그 추적. Claude Code 페이로드를 완전히 가로채고 분석하는 기능을 제공하여 로깅, 문제 분석, 학습, 리버스 엔지니어링에 최적입니다;
4. 학습 경험 공유. 풍부한 학습 자료와 개발 경험을 축적해 두었습니다(시스템 곳곳의 "?" 아이콘을 참고하세요);
5. 네이티브 경험 유지. Claude Code의 능력을 강화할 뿐, 코어에는 어떠한 실질적인 수정도 가하지 않아 네이티브 경험을 유지합니다;
6. 서드파티 모델 지원. deepseek-v4-*, GLM 5.1, Kimi K2.6을 지원하며, cc-switch 기능을 내장하여 언제든지 서드파티 도구로 핫 스위칭할 수 있습니다; 또한 핫 스위칭은 역할별 소스를 지원합니다 — Main Agent, Sub-Agent, Teammate가 각각 다른 프록시 프로필을 사용할 수 있습니다(기본값: Main Agent 따름). Main Agent가 공식 엔드포인트의 내장 Default를 사용할 때는 역할 할당이 숨겨지고 저장된 할당은 비활성 상태로 유지됩니다.

English | 简体中文 | 繁體中文 | 한국어 | 日本語 | Deutsch | Español | Français | Italiano | Dansk | Polski | Русский | العربية | Norsk | Português (Brasil) | ไทย | Türkçe | Українська

Config Convergence & Cloud Sync (design doc)

How local config maps to a cloud database and the cloud-sync model (cloud-authoritative, local read-only fallback) is described in Config Convergence & Cloud-Sync Advisory (中文). This is a proposal, not yet implemented.

Reverse-proxy base URL (CCV_BASE_URL): docs/base-url.md (中文) — serve cc-viewer under a public URL path prefix (Host allowlist, WS upgrades, share/QR links follow automatically).

사용 방법

전제 조건

• nodejs 20.0.0+ 가 설치되어 있는지 확인하세요; 다운로드 및 설치
• claude code 가 설치되어 있는지 확인하세요; 설치 가이드

ccv 설치

npm 으로 설치

npm install -g cc-viewer --registry=https://registry.npmjs.org

Homebrew 로 설치 (macOS / Linux 권장)

brew tap weiesky/cc-viewer
brew install cc-viewer
brew upgrade cc-viewer   # 업그레이드는 이 명령으로 — brew 로 설치한 ccv 를 npm install -g 로 업그레이드하지 마세요

pnpm 로 설치 (전역)

pnpm add -g cc-viewer
pnpm add -g cc-viewer@latest   # 업그레이드는 이 명령으로 — pnpm 로 설치한 ccv 를 npm install -g 로 업그레이드하지 마세요

시작 방법

ccv 는 claude 의 드롭인 대체이며, 모든 인자를 claude 에 그대로 전달하면서 동시에 Web Viewer 를 실행합니다.

ccv                    # == claude (대화형 모드)

제가 가장 자주 사용하는 명령은 다음과 같습니다:

ccv -c --d             # == claude --continue --dangerously-skip-permissions
                       # ccv 는 Claude Code 의 모든 시작 인자를 그대로 전달합니다 — 원하는 대로 자유롭게 조합할 수 있습니다

프로그래밍 모드로 실행되면 웹 페이지가 자동으로 열립니다.

cc-viewer 는 네이티브 데스크톱 앱도 제공합니다: 다운로드 페이지

SDK 모드 (headless, ccv --sdk)

ccv --sdk 는 대화형 터미널 대신 Agent SDK 를 통해 세션을 실행합니다 — 메인 PTY 가 없고, 메시지는 웹 UI 에서 전송되며, 그 외 모든 것(세션 로그, 스트리밍 타자기 효과, 사용량 통계)은 터미널 모드와 동일하게 작동합니다. 헤더에는 여전히 「터미널」 버튼이 있지만, 이는 프로젝트 PTY 가 아니라 독립적인 스크래치 멀티탭 셸(SDK 세션과 무관)을 엽니다.

ccv --sdk                # 무인 세션; 브라우저에서 대화
ccv --sdk -c             # 가장 최근 세션 계속
ccv --sdk --model sonnet # 모델 선택

승인(Bash/Edit/Write/WebFetch/…)은 허용 / 거부 / 세션 동안 허용 의 형태로 브라우저에 표시되며, AskUserQuestion / 계획 프롬프트는 모달로 나타납니다. npm publish 는 항상 명시적 승인을 요구합니다 — --d 를 붙여도 마찬가지입니다. @anthropic-ai/claude-agent-sdk 패키지가 필요합니다(cc-viewer 에 함께 번들됨); 사용할 수 없으면 터미널 모드로 대체됩니다.

1.7.0 으로 업그레이드 (로그 형식 v2)

1.7.0 부터 로그는 단일 .jsonl 파일 대신 세션별 디렉터리 형식(wire-format v2)으로 저장되며, 디스크 사용량이 약 90% 줄어듭니다. 기존 v1 .jsonl 파일은 절대 수정되거나 삭제되지 않으며, 로그 대화상자는 기본적으로 v2 세션을 표시하며, 작은 “레거시(v1) 로그 보기” 항목(오래된 파일이 있는 동안 표시됨)에서 v1 보기를 열어 확인, 마이그레이션 또는 삭제할 수 있습니다. 시작 시 레거시 로그가 발견되면 cc-viewer 가 원클릭 마이그레이션을 제공합니다(claude -c 로 이전 대화를 이어갈 때는 대화의 전반부가 이전 파일에 저장되어 있으므로 마이그레이션을 강력히 권장합니다). 터미널에서 마이그레이션할 수도 있습니다:

ccv convert <project>   # 프로젝트 하나 마이그레이션
ccv convert --all       # 모든 프로젝트 마이그레이션
ccv verify <v1-file>    # v1 파일을 변환된 세션과 대조하여 확인

세션이 golden 검증을 통과하지 못하면 전체 마이그레이션을 실패시키는 대신 sessions-quarantine/에 보관되어 검토할 수 있습니다. 나머지 세션은 정상적으로 마이그레이션됩니다.

로거 모드

여전히 네이티브 claude 도구나 VS Code 확장을 사용하고 싶다면 이 모드를 사용하세요.

이 모드에서 claude 를 실행하면 로깅 프로세스가 자동으로 시작되어 요청 로그를 ~/.claude/cc-viewer/yourproject/sessions/ 아래의 세션별 디렉터리(wire-format v2)에 기록합니다.

로거 모드 활성화:

ccv -logger

콘솔에서 구체적인 포트를 출력하지 못하는 경우, 기본 첫 번째 포트는 127.0.0.1:7008 입니다. 여러 인스턴스가 존재할 때는 7009, 7010 처럼 순차적으로 포트가 증가합니다.

로거 모드 제거:

ccv --uninstall

문제 해결 (Troubleshooting)

실행에 문제가 발생한 경우, 궁극의 해결 방법이 있습니다: 1단계: 임의의 디렉터리에서 Claude Code 를 엽니다; 2단계: Claude Code 에 다음 지시를 내립니다:

저는 cc-viewer 라는 npm 패키지를 설치했지만, ccv 를 실행해도 여전히 정상적으로 작동하지 않습니다. cc-viewer 의 cli.js 와 findcc.js 를 살펴보고, 현재 환경에 맞춰 로컬 Claude Code 의 배포 방식에 적응시켜 주세요. 가능한 한 수정 범위는 findcc.js 에 한정해 주세요.

Claude Code 가 직접 문제를 진단하게 하는 것이 누군가에게 묻거나 어떤 문서를 읽는 것보다 훨씬 효과적입니다!

위 지시가 완료되면 findcc.js 가 업데이트됩니다. 프로젝트가 로컬 배포를 자주 필요로 하거나, 포크한 코드가 종종 설치 문제를 해결해야 한다면 이 파일을 보관해 두면 됩니다. 다음에는 그대로 복사만 하면 됩니다. 현 단계에서는 Claude Code 를 사용하는 많은 프로젝트와 회사들이 Mac 이 아닌 서버 측 호스팅 배포를 사용하기 때문에, 저는 cc-viewer 소스 코드 업데이트 추적을 용이하게 하기 위해 findcc.js 를 분리했습니다.

주의: 이 앱은 claude-code-switch, claude-code-router 와 충돌합니다. 프록시 경합 문제가 있으니 사용 시에는 반드시 claude-code-switch, claude-code-router 를 비활성화하세요. cc-viewer 내부에 프록시 핫 업데이트 기능이 제공되어 그것들을 대체할 수 있습니다.

기타 보조 명령

참조:

ccv -h

사일런트 모드 (Silent Mode)

기본적으로 ccv 는 claude 를 래핑할 때 사일런트 모드로 실행되어 터미널 출력이 깔끔하게 유지되며 네이티브 경험과 일관성을 가집니다. 모든 로그는 백그라운드에서 캡처되며 http://localhost:7008 에서 확인할 수 있습니다.

설정이 완료되면 평소처럼 claude 명령을 사용하면 됩니다. http://localhost:7008 에 접속하여 모니터링 UI 를 열어보세요.

기능

예약 작업

(+) 메뉴(채팅 입력 표시줄 또는 터미널 도구 모음)에서 예약 작업을 열어 프롬프트를 일정에 따라 실행하세요: 프리셋(매시간/매일/평일/매주), 사용자 지정 5필드 cron 또는 일회성 시간. 작업은 현재 세션에 프롬프트를 주입하거나 새로운 격리된 헤드리스 세션(SDK 모드 전용)을 시작합니다. 작업은 프로젝트별로 저장되며 서버 시간대에서 작은 지터와 함께 예약됩니다. 프로세스 간 파일 잠금으로 중복 실행을 방지하고, 재시작 또는 절전 후에는 7일 이내의 가장 최근 누락 실행을 보정합니다. 지금 실행, 일시 중지/재개, 삭제 및 최근 20회 실행 기록을 사용할 수 있습니다. 참고: 작업은 ccv가 실행 중일 때만 실행됩니다.

프로그래밍 모드

ccv 로 시작하면 다음을 확인할 수 있습니다:

편집이 끝난 후 즉시 코드 diff 를 확인할 수 있습니다:

파일을 열어 수동으로 코딩할 수 있지만 권장하지 않습니다 — 그것은 구식 코딩입니다!

모바일 프로그래밍

QR 코드를 스캔하여 모바일 디바이스에서도 코딩할 수 있습니다:

모바일 프로그래밍에 대한 상상을 충족시켜 줍니다. 또한 플러그인 메커니즘도 있어, 자신의 코딩 습관에 맞춰 커스터마이즈가 필요하다면 이후의 플러그인 hook 업데이트를 기대해 주세요.

모델별 시스템 프롬프트

시스템 프롬프트 편집 모달(햄버거 메뉴 → 시스템 프롬프트 편집)은 탭 방식으로 구성되어 있습니다:

• 기본 탭: 현재 워크스페이스에 CC_SYSTEM.md(덮어쓰기) 또는 CC_APPEND_SYSTEM.md(추가)를 기록하며, 다음 ccv 실행 시 주입됩니다.
• 모델 탭: 이름으로 모델을 추가하고(opus, Gemini3 등) 범위를 전역(~/.claude/cc-viewer/system_prompt/) 또는 워크스페이스(<project>/system_prompt/)에서 선택합니다. 각 탭에 자체 추가/덮어쓰기 스위치와 미리보기가 있습니다. 이름은 해석된 모델 ID에 퍼지 매칭되므로(opus는 claude-opus-4-8[1m]에 매칭) 버전과 무관하게 동작합니다. 워크스페이스가 전역보다 우선하고, 가장 긴 이름이 이기며, 매칭된 항목은 기본 파일을 완전히 대체합니다.
• 기본 제공 프리셋: Kimi, DeepSeek, Qwen, GLM 모델 패밀리에 깊이 맞춰 튜닝된 system prompt입니다 — 해석된 모델이 일치하고 내 항목이 일치하지 않으면 자동으로 주입됩니다(내 파일이 항상 우선). 탭의 × 로 기본 제공 프리셋을 비활성화할 수 있습니다.
• system 텍스트는 세션 도중 핫 스위치된 메인 모델을 따라가며 (세션, 모델) 단위로 고정됩니다(KV 캐시는 전환 시 한 번만 재구성). 탭을 비운 채 저장하면 항목이 삭제됩니다. CCV_DISABLE_AUTO_SYSTEM_PROMPT=1로 모든 자동 주입을 비활성화하거나, CCV_DISABLE_LIVE_SYSTEM_PROMPT=1로 세션 중 추적만 비활성화할 수 있습니다.

로거 모드 (Claude Code 의 완전한 세션 보기)

• Claude Code 가 보내는 모든 API 요청을 실시간으로 캡처하며, 편집되지 않은 원문 그대로임을 보장합니다(이것은 매우 중요합니다!!!)
• Main Agent 와 Sub Agent 요청을 자동으로 식별하고 라벨링합니다(서브타입: Plan, Search, Bash)
• MainAgent 요청은 Body Diff JSON 을 지원하여, 직전 MainAgent 요청과의 차이(변경/추가된 필드만)를 접힌 상태로 표시합니다
• 각 요청에는 Token 사용 통계가 인라인으로 표시됩니다(입력/출력 Token, 캐시 생성/읽기, 적중률)
• Claude Code Router (CCR) 및 기타 프록시 시나리오와 호환됩니다 — API 경로 패턴 매칭으로 fallback 처리합니다

<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=weiesky/cc-viewer&type=date&legend=top-left" />

![Star History Chart](https://api.star-history.com/chart?repos=weiesky/cc-viewer&type=date&legend=top-left)

License

MIT