Relay

✋ 소개

Relay는 Claude Code를 GUI로 사용할 수 있는 Electron 데스크톱 앱입니다. 사용자가 로컬 프로젝트를 열고 AI와 대화하며 코드 탐색, 파일 편집, 터미널 명령 실행 등을 수행할 수 있는 통합 개발 환경을 제공합니다.

🔗 GitHub

데모

🧑‍🤝‍🧑 구성원

  • 프론트엔드 및 백엔드 : 2명

💻 기술 스택

  • Electron, React, TypeScript, Vite
  • TanStack React Router, TanStack React Query
  • Tailwind CSS, shadcn/ui
  • claude-agent-sdk
  • ORPC (IPC 통신)
  • xterm.js, node-pty
  • Shiki
  • electron-store
  • Vitest, Playwright

📁 프로젝트 구조

src/
├── main.ts                  # Electron Main 프로세스 진입점
├── preload.ts               # Preload 스크립트 (IPC 브릿지)
├── renderer.ts              # Renderer 프로세스 진입점
├── App.tsx                  # React 앱 루트 컴포넌트
├── store.ts                 # electron-store 설정
├── actions/                 # Main 프로세스 액션 (테마, 윈도우, 셸 등)
├── components/
│   ├── ai/                  # AI 도구 UI (코드 뷰어, 파일 트리, diff 등)
│   ├── ai-elements/         # AI 채팅 요소 (메시지, 프롬프트, 코드 블록 등)
│   ├── projects/            # 프로젝트 관리 UI
│   └── ui/                  # shadcn/ui 공통 컴포넌트
├── hooks/                   # 커스텀 훅 (채팅, 파일 탐색, 코드 선택 등)
├── ipc/
│   ├── ai/                  # AI SDK 핸들러, PermissionBus
│   ├── chat/                # 채팅 세션 CRUD
│   ├── fs/                  # 파일 시스템 접근
│   ├── terminal/            # 터미널(node-pty) 관리
│   ├── project/             # 프로젝트 디렉토리 관리
│   ├── shell/               # 셸 명령 실행
│   ├── theme/               # 테마 설정
│   ├── window/              # 윈도우 제어
│   ├── router.ts            # oRPC 라우터 통합
│   └── handler.ts           # IPC 핸들러 등록
├── routes/                  # TanStack Router 파일 기반 라우팅
├── styles/                  # 글로벌 CSS
├── types/                   # 타입 정의
├── utils/                   # 유틸리티 함수

🤔 왜 Electron인가

Electron을 선택한 이유는 크게 두 가지입니다.

첫째, 앱의 핵심 기능이 OS 수준의 자원에 대한 직접적인 접근 권한을 필요로 했습니다. 로컬 파일 시스템 읽기/쓰기, 쉘 명령 실행, PTY 기반 터미널 제공 등은 웹 브라우저의 보안 샌드박스 안에서는 근본적으로 제한되는 작업입니다. Electron은 Node.js 런타임을 내장하고 있어 node-pty, fs, child_process 등을 통해 이러한 네이티브 작업을 자유롭게 수행할 수 있었습니다.

둘째, AI 기능의 핵심인 claude-agent-sdk가 Node.js 환경에서 동작하는 서버 사이드 SDK입니다. 이 SDK를 통해 AI 에이전트를 생성하고, 도구 실행 권한을 제어하며, 스트리밍 응답을 처리하려면 Node.js 런타임이 필수적이었습니다. Electron의 Main Process에서 SDK를 직접 실행함으로써 별도의 백엔드 서버 없이도 AI 기능을 온전히 활용할 수 있었습니다.

내가 기여한 기능

AI 채팅

  • claude-agent-sdk를 활용한 실시간 AI 채팅 기능을 구현했습니다.
  • SSE 기반 스트리밍 응답 처리로 실시간 메시지 렌더링을 지원합니다.
  • HITL(Human-In-The-Loop) 패턴을 적용하여 도구 실행 전 사용자 승인을 받는 인터럽트 흐름을 구현했습니다.
  • 세션 저장, 불러오기, 삭제 및 이전 대화 재개 기능을 지원합니다.

도구 실행 및 권한

  • AI Tool(Read, Write, Edit, Bash)의 실행 및 결과를 시각적으로 표시합니다.
  • Pub-Sub 기반 비동기 권한 요청/승인 시스템(PermissionBus)을 구현했습니다.
  • AI Tool 자동 승인 토글 기능을 제공합니다.

코드 탐색

  • 프로젝트 파일 트리를 통해 파일을 탐색할 수 있습니다.
  • Shiki 기반 구문 강조 코드 뷰어로 코드를 확인할 수 있습니다.
  • 코드 블록을 선택하여 AI 채팅 컨텍스트로 전달할 수 있습니다.

터미널

  • xterm.js와 node-pty를 활용한 내장 터미널을 제공합니다.
  • 프로젝트 디렉토리 컨텍스트 내에서 쉘을 실행합니다.

IPC 통신

  • ORPC와 MessagePort를 활용하여 Main Process와 Renderer Process 간 타입 안전한 IPC 통신을 구현했습니다.
  • Zod를 사용한 런타임 스키마 검증으로 데이터 무결성을 보장합니다.