CodePilot은 Electron과 Next.js를 기반으로 구축된 Claude Code를 위한 네이티브 데스크톱 GUI 클라이언트입니다. 이 애플리케이션은 터미널 대신 시각적인 인터페이스를 통해 AI 기반 코딩 및 프로젝트 관리를 용이하게 하는 것을 목표로 합니다.

주요 기능 (Features):

• 대화형 코딩 (Conversational Coding): Claude의 응답을 실시간으로 스트리밍하며, 완전한 Markdown 렌더링, 구문 강조된 코드 블록, 그리고 도구 호출(tool-call) 시각화를 지원합니다.
• 세션 관리 (Session Management): 채팅 세션을 생성, 이름 변경, 보관 및 재개할 수 있습니다. 모든 대화는 로컬 SQLite 데이터베이스에 지속적으로 저장됩니다.
• 프로젝트 기반 컨텍스트 (Project-Aware Context): 세션별로 작업 디렉터리를 지정할 수 있으며, 오른쪽 패널에 실시간 파일 트리와 파일 미리보기가 표시되어 Claude가 보고 있는 내용을 명확히 파악할 수 있습니다.
• 파일 및 이미지 첨부 (File & Image Attachments): 채팅 입력에 파일과 이미지를 직접 첨부할 수 있으며, 이미지는 Claude가 분석할 수 있는 멀티모달(multimodal) 비전 콘텐츠로 전송됩니다.
• 권한 제어 (Permission Controls): 도구 사용에 대해 동작별로 승인, 거부 또는 자동 허용을 선택할 수 있는 다양한 권한 모드를 제공합니다.
• 다중 상호작용 모드 (Multiple Interaction Modes): 세션 내에서 Claude의 동작을 제어하기 위해 Code, Plan, Ask 모드 간 전환이 가능합니다.
• 모델 선택기 (Model Selector): 대화 중에 Claude Opus, Sonnet, Haiku 모델을 전환할 수 있습니다.
• MCP 서버 관리 (MCP Server Management): Model Context Protocol(MCP) 서버를 Extensions 페이지에서 직접 추가, 구성 및 제거할 수 있으며, stdio, sse, http 전송 유형을 지원합니다.
• 사용자 정의 스킬 (Custom Skills): 전역 또는 프로젝트별로 재사용 가능한 프롬프트 기반 스킬을 정의하고, 채팅 중 슬래시 명령어(slash command)로 호출할 수 있습니다.
• 토큰 사용량 추적 (Token Usage Tracking): 각 Assistant 응답 후 입력/출력 토큰 수와 예상 비용을 확인할 수 있습니다.
• 편의 기능: Resizable panels, Settings editor (Visual/JSON), Auto update check, Dark/Light theme, /help, /clear, /cost, /doctor 등 내장 슬래시 명령어를 제공합니다.

핵심 방법론 및 기술 스택 (Core Methodology & Tech Stack):

CodePilot은 Claude Code Agent SDK를 내부적으로 호출하여 AI 기능을 통합합니다. 따라서 claude CLI가 시스템 PATH에 등록되어 있고 인증이 완료되어 있어야 합니다.

• 아키텍처 (Architecture):
  • 데스크톱 셸은 Electron 40을 사용하며, 내부에 Next.js 16(App Router) 서버를 번들링합니다.
  • Electron 메인 프로세스(electron/main.ts)는 Next.js 스탠드얼론 서버를 fork하고, 무작위로 할당된 사용 가능한 포트를 통해 127.0.0.1로 연결하여 통신합니다. 이는 클라이언트-서버 모델을 데스크톱 애플리케이션 내에 통합한 형태입니다.
• 데이터 저장 (Data Storage): better-sqlite3를 사용하여 로컬 데이터베이스(~/.codepilot/codepilot.db)에 세션 및 관련 데이터를 영구 저장합니다. 동시 읽기 성능을 위해 SQLite의 WAL(Write-Ahead Logging) 모드를 사용합니다. 데이터베이스 스키마 및 CRUD 작업은 lib/db.ts에서 관리됩니다.
• AI 통합 (AI Integration): Claude Agent SDK의 스트리밍 래퍼는 lib/claude-client.ts에 구현되어 있습니다. 메시지 스트리밍은 Vercel AI SDK 헬퍼와 Server-Sent Events(SSE)를 활용합니다.
• UI/UX:
  • UI 컴포넌트는 Radix UI와 shadcn/ui를 기반으로 구축되었으며, 스타일링은 Tailwind CSS 4를 사용합니다.
  • 애니메이션에는 Framer Motion(Motion) 라이브러리가 활용됩니다.
  • Markdown 렌더링은 react-markdown, remark-gfm, rehype-raw 및 Shiki를 통해 구현되어 코드 블록 구문 강조를 제공합니다.
• 파일 시스템 연동 (File System Integration): lib/files.ts는 파일 시스템 헬퍼 함수를 제공하며, src/app/api/files는 파일 트리 및 미리보기를 위한 REST API 엔드포인트를 노출합니다.
• 권한 관리 (Permission Management): 도구 사용 권한 요청 및 응답 브리지는 lib/permission-registry.ts에서 처리됩니다.
• 개발 및 빌드 (Development & Build):
  • 개발 모드에서는 npm run dev (브라우저에서 Next.js만 실행) 또는 npm run electron:dev (Electron 앱 실행)을 사용합니다.
  • 빌드는 electron-builder와 esbuild를 사용하여 macOS(.dmg), Windows(.exe NSIS installer), Linux(.AppImage, .deb, .rpm) 등 멀티 플랫폼 배포 패키지를 생성합니다.
• CI/CD: GitHub Actions를 통해 자동화된 빌드 및 릴리스 파이프라인이 구축되어 있습니다. v* 태그를 git push하면 모든 플랫폼에 대한 빌드가 트리거되고 GitHub Releases에 아티팩트가 자동으로 게시됩니다.
• 프로젝트 구조 (Project Structure):
  • .github/workflows/: CI/CD 워크플로우
  • electron/: Electron 메인 및 preload 프로세스 관련 코드
  • src/: Next.js App Router 기반의 페이지(app/), API 라우트(api/), UI 컴포넌트(components/), 커스텀 React Hooks(hooks/), 핵심 로직(lib/), 타입 정의(types/) 등으로 구성됩니다. 특히 src/app/api/에는 채팅 세션, 메시지, 스트리밍, 파일, 플러그인, 설정, 스킬 등 다양한 백엔드 API 엔드포인트가 포함됩니다.