cc-switch 딥다이브
— Claude Code·Codex·Gemini CLI 등 7개 도구를 하나로 묶는 데스크탑 매니저

1한줄 요약

2왜 지금 주목받는가

① AI 코딩 CLI 폭증 → 멀티 도구 시대가 왔다

2025~2026년에 AI 코딩 CLI 도구가 한꺼번에 쏟아졌다. Anthropic의 Claude Code, OpenAI의 Codex CLI, Google의 Gemini CLI, 오픈소스 OpenCode·OpenClaw·Hermes Agent — 각자 강점이 다르다. Claude는 긴 컨텍스트에서 강하고, Codex는 빠르고, Gemini는 무료 할당량이 크다. 개발자들은 여러 개를 동시에 깔고 상황에 따라 골라 쓴다.

문제는 각 도구가 자기 설정 포맷을 고집한다는 점. Claude Code는 환경 변수, Codex는 TOML, Gemini는 JSON, OpenCode는 .env — 공급자를 갈아끼울 때마다 7개 파일을 손으로 편집해야 한다. cc-switch는 이 "멀티 코딩 CLI 시대의 SIM 매니저"로 정확히 시장 빈틈을 찔렀다.

② 50+개 공급자 프리셋 — 클릭 한 번에 끝

Anthropic 공식, OpenAI 공식, AWS Bedrock, Google Vertex, NVIDIA NIM, 그리고 PackyCode·AIGoCode·DMXAPI·Crazyrouter 같은 중국·글로벌 릴레이 서비스까지 50+개의 공급자가 기본 내장돼 있다. 사용자가 키만 붙여넣으면 끝이다. 직접 endpoint URL을 입력하거나 인증 헤더를 만들 필요가 없다.

③ MCP·스킬·프롬프트 통합 패널

Claude Code·Claude Desktop·Codex·Gemini CLI·OpenCode·OpenClaw·Hermes Agent는 모두 MCP 서버를 따로 등록한다. Slack MCP를 7번 등록해야 지원 도구(7개) 전체에서 다 쓸 수 있다. cc-switch는 한 패널에서 MCP 서버를 추가하면 자동으로 지원 도구(7개)의 설정 파일에 양방향 동기화한다. 라이브 파일에서 직접 편집한 변경도 다시 빨아들인다.

스킬도 마찬가지. GitHub 레포 URL 하나 붙여넣으면 심볼릭 링크 또는 파일 복사 모드로 지원 도구(7개)의 skills 디렉터리에 동시 설치된다. 프롬프트는 CLAUDE.md / AGENTS.md / GEMINI.md를 마크다운 에디터에서 편집하고 활성화 시 라이브 파일에 동기화된다. "backfill protection" — 라이브 파일에서 외부 도구가 수정한 내용도 다시 cc-switch DB로 빨아들여서 손실을 막는다.

④ 로컬 프록시 모드 — 핫스위치, 자동 페일오버, 서킷 브레이커

이게 진짜 차별점이다. cc-switch는 로컬에서 HTTP 프록시 서버를 띄울 수 있다. CLI 도구가 cc-switch 프록시에 요청을 보내면, cc-switch가 진짜 공급자에게 중계한다.

• 핫스위치 — Claude Code를 재시작하지 않고도 공급자 전환 가능
• 포맷 변환 — OpenAI 포맷 ↔ Anthropic 포맷 ↔ Gemini 포맷 자동 변환
• 자동 페일오버 — 메인 공급자가 죽으면 백업으로 자동 전환
• 서킷 브레이커 — 연속 실패 시 해당 공급자를 임시 차단해서 빠르게 다음으로 넘김
• 요청 보정기(rectifier) — 공급자별 API 차이(예: 시스템 프롬프트 위치, max_tokens 기본값)를 자동 조정
• 앱 단위 takeover — Claude만 프록시 통과, Codex는 직결 — 도구별 독립 제어

⑤ 사용량 대시보드 + 세션 매니저

지출·요청 수·토큰 사용량을 트렌드 차트로 보여주고 모델별 커스텀 가격을 입력해서 정확한 청구 추정이 가능하다. 세션 매니저는 지원 도구(7개)의 대화 히스토리를 통합 검색·복원할 수 있다. Claude Code에서 어제 한 작업을 Codex에서 이어서 할 수 있다는 뜻이다.

⑥ 클라우드 동기화 — Dropbox / OneDrive / iCloud / WebDAV

설정 디렉터리를 클라우드 동기화 폴더에 두면 여러 PC에서 같은 공급자·MCP·스킬·프롬프트를 공유한다. WebDAV 서버도 지원해서 셀프호스팅 NAS(Synology·QNAP)에 동기화할 수 있다.

⑦ Tauri 2 — 가벼움 + 코드사이닝

Electron 대안인 Tauri 2.8로 만들어서 설치 용량이 ~10MB 수준, 메모리 사용량도 Electron의 1/3~1/5. macOS는 Apple 코드사이닝·공증 완료여서 다운로드 후 바로 실행된다 — "확인되지 않은 개발자" 경고 우회 절차가 필요 없다. Homebrew Cask(brew install --cask cc-switch)와 AUR(paru -S cc-switch-bin)도 지원.

3기술 스택 전체 지도

백엔드 (Rust · Tauri 2)

프론트엔드 (React 18 · TypeScript)

테스트

빌드 · 배포 · 패키징

외부 통합 대상

4아키텍처 심화 분석

전체 시스템 구조

핵심 설계 패턴 6가지

핵심 서비스 모듈

Deep Link 처리 흐름 (ccswitch:// 스킴)

같은 메커니즘으로 MCP 서버·프롬프트·스킬도 URL로 공유 가능. "클릭 한 번에 설정 공유"의 핵심.

5디렉토리 구조 해부

전체 트리

cc-switch/
├── src/                        # 프론트엔드 (React + TypeScript)
│   ├── components/
│   │   ├── providers/          # 공급자 관리 UI
│   │   ├── mcp/                # MCP 패널
│   │   ├── prompts/            # 프롬프트 관리 (CLAUDE.md / AGENTS.md)
│   │   ├── skills/             # 스킬 관리 (GitHub 레포 설치)
│   │   ├── sessions/           # 세션 매니저 (대화 히스토리)
│   │   ├── proxy/              # 로컬 프록시 모드 패널
│   │   ├── openclaw/           # OpenClaw 전용 워크스페이스 에디터
│   │   ├── settings/           # 설정 (터미널·백업·About)
│   │   ├── deeplink/           # Deep Link 임포트 다이얼로그
│   │   ├── env/                # 환경 변수 관리
│   │   ├── universal/          # 크로스 앱 통합 설정
│   │   ├── usage/              # 사용량 통계 대시보드
│   │   └── ui/                 # shadcn/ui 컴포넌트 라이브러리
│   ├── hooks/                  # 커스텀 훅 (비즈니스 로직 분리)
│   ├── lib/
│   │   ├── api/                # Tauri API 래퍼 (타입 안전 IPC)
│   │   └── query/              # TanStack Query 설정
│   ├── i18n/locales/           # 다국어 번역 (zh / zh-TW / en / ja)
│   ├── config/                 # 프리셋 (50+ 공급자 · MCP 템플릿)
│   └── types/                  # TypeScript 타입 정의
├── src-tauri/                  # 백엔드 (Rust)
│   └── src/
│       ├── commands/           # Tauri 명령 레이어 (도메인별 분리)
│       ├── services/           # 비즈니스 로직 (ProviderService 등)
│       ├── database/           # SQLite DAO 레이어
│       ├── proxy/              # 프록시 모듈 (핫스위치 + 페일오버)
│       ├── session_manager/    # 세션 관리 (대화 히스토리)
│       ├── deeplink/           # Deep Link 핸들러
│       └── mcp/                # MCP 동기화 모듈
├── tests/                      # 프론트엔드 테스트 (vitest + MSW)
├── docs/                       # 사용자 매뉴얼 (다국어)
├── flatpak/                    # Flatpak 빌드 가이드 (커뮤니티용)
└── assets/                     # 스크린샷 · 스폰서 자산

핵심 파일별 역할

사용자 데이터 저장 위치

6학습 포인트 (기술별)

① Tauri 2 — Electron의 가벼운 대안

cc-switch는 Tauri 2를 진지하게 다루는 좋은 레퍼런스다. Electron이 Chromium을 통째로 번들하는 반면, Tauri는 시스템 웹뷰(macOS WebKit, Windows WebView2, Linux WebKitGTK)를 쓴다. 결과: 설치 용량 10MB vs 150MB, 메모리 1/3.

배울 것: Tauri IPC 패턴 — #[tauri::command] 데코레이터로 Rust 함수를 프론트에 노출하고, 프론트에서 invoke()로 호출하는 흐름. 플러그인 시스템 — updater · process · dialog · store · log 같은 공식 플러그인을 조합. 시스템 트레이 — SystemTray::new()로 트레이 아이콘에 메뉴 매다는 법.

실습 아이디어: "내 노트 매니저 데스크탑 앱" — 마크다운 노트를 Tauri 2 + React로 만들어 보기. 트레이 아이콘에서 빠른 메모 추가.

② TanStack Query v5 — 서버 상태 캐시

일반 React 앱에서는 fetch + useState 조합으로 데이터 받아오는데, 그러면 캐시·재검증·로딩·에러 상태를 다 수동으로 짜야 한다. TanStack Query v5는 그걸 1줄로 해결한다:

const { data, isLoading } = useQuery({
  queryKey: ['providers'],
  queryFn: () => invoke('list_providers'),
});

cc-switch는 Tauri IPC 응답을 캐시 키로 자동 관리한다. 공급자 추가 → queryClient.invalidateQueries(['providers']) 한 줄이면 화면 전체가 자동 새로고침.

배울 것: 쿼리 키 설계, mutation + optimistic update, staleTime / gcTime 튜닝, 서버 상태와 클라이언트 상태의 분리.

③ shadcn/ui — 복사-붙여넣기형 컴포넌트

shadcn/ui는 라이브러리가 아니다. CLI로 컴포넌트 코드를 자기 프로젝트에 복사해 넣는 방식이다(npx shadcn add button). 결과: 외부 의존성 0, 마음대로 수정 가능, 트리 쉐이킹 최적.

배울 것: Radix UI 프리미티브 위에 Tailwind로 스타일링하는 패턴. 헤드리스 컴포넌트(접근성·키보드 내비게이션 기본 제공) + 디자인 토큰 분리.

④ Rust + SQLite + Atomic Writes

설정 파일은 깨지면 안 된다. cc-switch는 "temp + rename"으로 깨짐을 막는다. Rust 코드 패턴:

let tmp = path.with_extension("tmp");
std::fs::write(&tmp, content)?;       // 1. 임시 파일에 쓰기
std::fs::rename(&tmp, path)?;         // 2. 원자적 교체
// 중간에 죽어도 원본은 그대로!

배울 것: 파일 시스템 원자성 개념 (POSIX rename = 원자적, write = 비원자적). SQLite WAL 모드. Mutex로 동시성 보호.

⑤ 로컬 HTTP 프록시 서버

cc-switch 안에서 tokio + hyper로 작은 프록시를 띄운다. 들어온 요청의 헤더·본문을 변환해서 진짜 LLM 공급자에게 보낸다. 응답 스트리밍도 그대로 통과시켜야 한다(SSE 기반 LLM 응답).

배울 것: HTTP 프록시 기본기 (Host 헤더, X-Forwarded-For), 스트리밍 응답 패스스루, 서킷 브레이커 패턴 (실패 N회 → open 상태로 빠르게 거절 → half-open으로 복구 시도), OpenAI/Anthropic API 포맷 차이 이해.

⑥ Deep Link · 커스텀 URL 스킴

ccswitch:// 같은 커스텀 스킴은 어떻게 OS에 등록될까? Tauri는 tauri.conf.json의 deepLinkProtocols로 등록하고, 핸들러를 Rust에서 받는다. macOS는 Info.plist의 CFBundleURLTypes, Windows는 레지스트리, Linux는 .desktop 파일 — Tauri가 다 처리해 준다.

⑦ react-i18next — 다국어 패턴

zh/zh-TW/en/ja 4개 언어를 어떻게 깔끔하게 관리할까. src/i18n/locales/{lang}/translation.json에 키-밸류로 저장하고, useTranslation() 훅으로 가져온다.

const { t } = useTranslation();
return <button>{t('provider.add')}</button>;

배울 것: 네임스페이스 분리, 변수 보간, 복수형 처리, 날짜·숫자 포맷.

⑧ MCP (Model Context Protocol)

MCP는 2024년 말 Anthropic이 표준화한 "LLM과 외부 도구의 어댑터 규약"이다. JSON-RPC 기반, stdio 또는 SSE 트랜스포트. cc-switch는 MCP 서버를 등록·실행·상태 모니터링·라이브 파일 동기화까지 한다.

배울 것: MCP 서버 작성법 (Python/TypeScript SDK), 도구 정의(tools), 리소스(resources), 프롬프트(prompts) 3대 프리미티브 — 자기만의 MCP 서버를 만들어보면 LLM에 자기 데이터를 연결하는 능력이 생긴다.

7하드웨어/시스템 요구사항

리소스 사용량

Tauri 기반이라 매우 가볍다. 대략 추정:

• 설치 용량: 10~15MB (Electron 앱의 1/10)
• 메모리 사용량: 50~150MB (Chrome 탭 하나 정도)
• 디스크: ~/.cc-switch/cc-switch.db = 100KB~수 MB (공급자 수에 비례)
• 네트워크: 자동 업데이트 체크 외에는 사용자가 명시적으로 호출할 때만

개발 환경 (기여하려면)

8직접 해볼 수 있는 실습 과제

🟢 초급 — 30분 안에

🟢 초급 — 1시간

🟡 중급 — 반나절

🟡 중급 — 1~2일

🔴 상급 — 1주

9관련 기술 심화 학습 로드맵

Week 1 — Tauri 2 기본기

• 공식 튜토리얼로 "Hello World" 데스크탑 앱 만들기
• Tauri IPC 명령 정의·호출 패턴 이해
• cc-switch의 src-tauri/src/commands/ 한 파일을 정독
• tauri.conf.json의 모든 옵션 한 번씩 훑기

Week 2 — Rust 비동기 + tokio

• tokio 공식 튜토리얼 ("mini-redis")
• async/await 함수 시그니처, Send + Sync, Arc<Mutex<T>> 패턴
• cc-switch의 src-tauri/src/proxy/ 모듈 분석 — tokio·hyper로 HTTP 서버 어떻게 띄우는지

Week 3 — React 18 + TanStack Query v5

• TanStack Query 공식 튜토리얼 완주
• cc-switch의 src/hooks/에서 query/mutation 패턴 분석
• 실습: 자기 프로젝트에 TanStack Query 도입 (지금 useState/useEffect로 짠 부분 리팩토링)

Week 4 — SQLite + 영구 저장 패턴

• SQLite 공식 문서 — WAL 모드, transaction, ATTACH
• Rust에서 SQLite — rusqlite 또는 sqlx 비교
• Atomic write 패턴 직접 구현 — Python·Rust 양쪽으로
• cc-switch의 src-tauri/src/database/ 분석

Week 5 — MCP (Model Context Protocol)

• Anthropic MCP 공식 spec 정독
• Python SDK로 자기만의 MCP 서버 작성 — "내 메모 검색" 같은 작은 도구
• Claude Code에 등록해서 실제로 호출되는 흐름 확인
• cc-switch의 src-tauri/src/mcp/ 동기화 로직 분석

Week 6 — 종합: 자기만의 데스크탑 도구 만들기

• 1~5주에 배운 것을 모두 동원해 작은 데스크탑 앱을 만든다
• 예시 주제: "내 Obsidian vault 검색 + 트레이 빠른 추가", "Notion·Linear 통합 대시보드", "로컬 LLM 게이트웨이"
• 코드 사이닝·자동 업데이트 채널까지 한 번 경험해 보기
• GitHub에 공개하고 README에 cc-switch에서 영감 받았다고 명시(좋은 OSS 매너)

10핵심 키워드 사전

11참고 링크

• cc-switch 공식 사이트: https://ccswitch.io
• GitHub 레포: github.com/farion1231/cc-switch
• Trendshift 페이지: trendshift.io/repositories/15372
• 릴리스 페이지: github.com/farion1231/cc-switch/releases
• 사용자 매뉴얼: docs/user-manual/en/README.md (레포 내부)
• Tauri 2 공식 문서: tauri.app
• TanStack Query v5: tanstack.com/query/latest
• shadcn/ui: ui.shadcn.com
• MCP 공식 스펙: modelcontextprotocol.io
• Claude Code: github.com/anthropics/claude-code
• Codex CLI: github.com/openai/codex
• OpenCode: github.com/anomalyco/opencode