desktop-cc-gui (ccgui) 딥다이브
— 터미널 AI 코딩 CLI를 데스크톱 앱으로 감싼 멀티엔진 클라이언트의 설계

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

ccgui는 데스크톱 AI 코딩 클라이언트다. 프로젝트 폴더를 열고 채팅으로 작업을 지시하면, 내부의 Rust 백엔드가 적절한 CLI(claude -p 등)를 자식 프로세스로 띄우고 stream-json 형식의 출력을 실시간 파싱해 화면에 흘려 보낸다. 파일 트리·내장 터미널·Git 패널·전역 검색은 물론, 프로젝트 맵(지식 그래프)·프로젝트 메모리·컨텍스트 원장(ledger)·사용량 통계·칸반·인텐트 캔버스까지 갖춘 풀 IDE급 데스크톱 앱이다. CodexMonitor라는 작은 프로젝트에서 출발해 멀티엔진 클라이언트로 성장했다.

2왜 주목받는가

트렌딩 이유 · Claude Code 단독·웹 챗봇 대비 장점.

AI 코딩 CLI(Claude Code·Codex 등)는 강력하지만 터미널 UX의 한계가 있다. 긴 출력은 스크롤로 사라지고, 어떤 파일이 바뀌었는지·비용이 얼마인지 추적이 어렵고, 여러 세션·여러 엔진을 오가기가 번거롭다. ccgui가 빠르게 스타를 모으는 이유는 이 "터미널에서 진짜 불편한 부분"을 데스크톱 앱으로 정면 돌파했기 때문이다. 첫째 하나의 앱에서 여러 엔진을 전환·혼합, 둘째 모든 동작이 시각적 카드로 투명하게, 셋째 세션·비용·컨텍스트의 영속화, 넷째 프로젝트 맵·메모리 같은 "프로젝트 지능"이다.

3기술 스택 전체 지도

백엔드(Rust/Tauri)·프론트엔드(React)·인프라 각각.

① 백엔드 — Rust + Tauri 2 (src-tauri/)

ccgui의 진짜 엔진은 Rust다. CLI 프로세스 관리, 파일·Git·터미널·SQLite 접근, 코드 분석 등 OS와 부딪치는 모든 일을 Rust가 맡고, 프론트엔드는 #[tauri::command]로 노출된 함수를 호출한다(소스 전반에 44개 파일에 걸쳐 명령이 흩어져 있다).

② 프론트엔드 — React 19 + TypeScript (src/)

UI는 60개 이상의 기능(feature) 폴더로 모듈화돼 있다(git·terminal·project-map·kanban·context-ledger 등). 화면 자체는 웹 기술이지만, @tauri-apps/api의 invoke로 Rust 명령을 호출하고 이벤트를 구독한다.

③ 인프라 · 빌드 · 품질 게이트

4아키텍처 심화 분석

웹뷰(React) ↔ IPC ↔ Rust ↔ CLI 자식 프로세스, 그리고 멀티엔진 어댑터.

ccgui의 심장은 "프론트엔드(웹뷰)와 백엔드(Rust)가 IPC로 대화하고, 백엔드가 CLI를 자식 프로세스로 띄워 그 스트림을 다시 프론트로 중계"하는 흐름이다. 전체 구조를 그림으로 보면 다음과 같다.

핵심 설계 패턴 ① — 멀티엔진 어댑터 (Adapter Pattern)

가장 중요한 추상화는 src-tauri/src/engine/다. 서로 다른 CLI(Claude·Codex·Gemini·OpenCode)는 명령어 인자도, 출력 포맷도 다르다. ccgui는 이를 공통 EngineType 열거형 + 엔진별 어댑터 모듈로 통일한다. 프론트엔드는 "어떤 엔진인지"를 신경 쓰지 않고 같은 명령을 호출하면, EngineManager가 알맞은 어댑터로 라우팅한다.

// src-tauri/src/engine/mod.rs  (발췌·요약)
pub enum EngineType {
    Claude,    // "Claude Code"  — 기본값
    Codex,     // "Codex"
    Gemini,    // "Gemini"
    OpenCode,  // "OpenCode"
}
// 각 엔진은 별도 어댑터 파일로:
//   claude.rs / codex_adapter.rs / gemini.rs / opencode.rs
// 기본 엔진은 Claude Code (impl Default for EngineType)

이 패턴 덕에 새 엔진 추가 = 새 어댑터 파일 작성이고, UI와 나머지 백엔드는 거의 손대지 않는다. capability_matrix.rs 같은 보조 모듈로 "이 엔진이 어떤 기능을 지원하는가"를 표로 관리해, UI가 엔진에 맞춰 버튼을 켜고 끈다.

핵심 설계 패턴 ② — CLI를 stream-json으로 구동 (Process + Stream)

Claude 어댑터(claude.rs, 약 87KB)는 CLI를 단순히 "텍스트로 실행"하지 않는다. 입력도 출력도 stream-json으로 묶어, 프롬프트 텍스트를 셸이 해석할 위험을 없애고 출력을 구조화된 이벤트로 받는다.

// src-tauri/src/engine/claude.rs  (인자 구성 발췌)
cmd.arg("-p");                       // print(비대화) 모드
cmd.arg("--input-format");  cmd.arg("stream-json");  // 입력도 JSON
cmd.arg("--output-format"); cmd.arg("stream-json");  // 출력도 JSON
cmd.arg("--verbose");                 // 더 많은 이벤트
// 실제 프롬프트 본문은 인자가 아니라 stdin(stream-json)으로 주입
// → 셸 래퍼가 프롬프트를 절대 파싱하지 않는다(안전)

백엔드는 이 NDJSON 줄들을 파싱해 도메인 이벤트(텍스트 델타·도구 호출·토큰 사용량 등)로 정규화한 뒤 emit으로 프론트에 보낸다. 그래서 화면에 "파일 편집 카드", "셸 명령 카드", "비용 표시"가 실시간으로 뜬다. 시작 시 일정 시간 내 유효한 스트림 이벤트가 안 오면 타임아웃 진단을 띄우는 등, 실패 경로까지 촘촘히 다뤄져 있다.

핵심 설계 패턴 ③ — 로컬 영속성 + 프로젝트 지능

ccgui는 클라우드 없이 모든 상태를 로컬에 둔다. storage.rs·rusqlite로 세션·노트카드·메모리·사용량을 SQLite에 저장하고, session_management*.rs(여러 파일로 분할)가 세션 카탈로그·폴더·아카이브·되감기(rewind)/포크를 담당한다. 여기에 프로젝트 맵(project_map*.rs — 파일 관계·API 계약·모듈 의존성 그래프)과 프로젝트 메모리(project_memory/), 코드 인텔리전스(code_intel.rs — 심볼·정의 탐색)를 더해 "AI가 이 코드베이스를 안다"는 느낌을 만든다.

5디렉토리 구조 해부

"프론트(src) ↔ 백엔드(src-tauri) ↔ 규칙/스펙 문서"의 3층.

주목할 점: 같은 관심사를 여러 파일로 잘게 쪼갠다. 예를 들어 세션 관리는 session_management.rs(108KB) 한 덩어리가 아니라 _types·_catalog_projection·_folder_counts·각종 _tests로 분리돼 있다. check:large-files 게이트가 거대 파일을 감시하기 때문이다. 또 .trellis/·openspec/·AGENTS.md처럼 "AI 에이전트가 이 레포에서 일할 때의 규칙"을 문서로 명시한 점이 특징이다(이 앱 자체가 AI 코딩 도구로 개발됨).

6학습 포인트 (기술별)

이 레포를 뜯어보며 배울 수 있는 것 + 실습 아이디어.

① Tauri 2 — "웹 UI + Rust 백엔드" 데스크톱 앱

배울 것: invoke(프론트→Rust)와 emit(Rust→프론트)으로 양방향 통신하는 법, #[tauri::command]로 함수를 노출하는 법, capabilities/로 권한을 좁히는 법, 플랫폼별 설정(tauri.windows.conf.json)과 자동 업데이트.

② CLI를 자식 프로세스로 구동하고 스트림 파싱

배울 것: tokio::process로 외부 프로그램을 띄우고, stdout을 줄 단위(NDJSON)로 읽어 구조화 이벤트로 바꾸는 패턴. 인자 대신 stdin으로 데이터를 넣어 셸 인젝션을 피하는 보안 감각. 시작 타임아웃·조기 종료 같은 실패 경로 처리.

③ 어댑터 패턴으로 이종 도구 통일하기

배울 것: 공통 인터페이스(EngineType + 매니저)를 두고 도구별 차이를 어댑터로 격리하는 설계. "능력 행렬(capability matrix)"로 기능 차이를 데이터화해 UI를 조건부로 그리는 기법.

④ 로컬 우선(local-first) 영속성 — SQLite

배울 것: 클라우드 없이 rusqlite로 세션·메모리·사용량을 저장하고, 앱 재시작 후에도 복원하는 설계. 되감기(rewind)·포크처럼 "대화의 시간여행"을 데이터 모델로 표현하는 법.

⑤ 대형 프론트엔드의 모듈화 + 품질 게이트

배울 것: 기능별 폴더(feature-based) 구조, 거대 파일 분할, 그리고 check:*처럼 규약을 빌드 시 강제하는 스크립트로 코드 품질을 자동 관리하는 문화. 가상 스크롤(react-virtual)로 긴 목록 성능 잡기.

7시스템 / 환경 요구사항

그냥 쓰는 경우와, 직접 빌드하는 경우.

그냥 설치해 쓰기

Releases 페이지에서 OS별 설치 파일을 받는다. 설치 후 설정에서 AI 엔진(예: Claude Code API 키나 로컬 CLI)을 구성하고 프로젝트 폴더를 추가하면 끝.

직접 빌드/기여하기

# 빌드 3단계
git clone https://github.com/zhukunpenglinyutong/desktop-cc-gui.git
cd desktop-cc-gui
npm install            # pnpm/yarn 쓰면 preinstall이 막음
npm run tauri:dev      # doctor:strict 검증 후 개발 실행
npm run tauri:build    # 배포용 빌드

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

난이도별 — 손으로 만지며 구조를 체득한다.

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

"데스크톱 AI 코딩 클라이언트"를 이해/제작하기 위한 주차별 길.

10핵심 키워드 사전

이 문서에서 반복된 용어를 한 번에.

11참고 링크

원본과 더 깊이 파기 위한 자료.

• GitHub 저장소: zhukunpenglinyutong/desktop-cc-gui
• Releases(설치 파일): /releases
• 원류 프로젝트 CodexMonitor: Dimillian/CodexMonitor
• Tauri 2 공식 문서: v2.tauri.app · 사전 요구사항: /start/prerequisites
• Claude Code: docs.anthropic.com (claude-code)
• 핵심 소스: src-tauri/src/engine/(어댑터)·terminal.rs(PTY)·storage.rs(SQLite)·project_map*.rs(지식그래프)