Claude Code 가이드

Claude Code 가이드 #16 — 데스크톱 앱 심화

데스크톱 앱 고유 기능, 터미널·VS Code와의 비교, 멀티 프로젝트 관리와 워크스페이스 설정 실전 가이드.

2026-03-23

Claude Code 가이드 #16 — 터미널에서 쓰는 Claude Code와 데스크톱 앱은 같은 엔진이지만 경험이 다릅니다. 이 편에서는 데스크톱 앱만의 기능, 터미널·VS Code와의 차이, 멀티 프로젝트 관리와 워크스페이스 설정까지 심화 기준으로 정리합니다.

※ 이 글은 2026년 3월 기준, Claude Code 데스크톱 공식 문서 기반으로 작성됐습니다.

데스크톱 앱 vs 터미널 vs VS Code — 무엇이 다른가?

Claude Code는 세 가지 실행 환경을 제공합니다. 각 환경이 어떤 차이가 있는지 먼저 이해해야 올바른 환경을 선택할 수 있습니다.

항목	터미널	VS Code 확장	데스크톱 앱
UI	텍스트 기반	에디터 사이드패널	독립 GUI 앱
멀티 프로젝트	탭/tmux 분할	워크스페이스 단위	내장 프로젝트 전환
컨텍스트 시각화	없음	제한적	토큰 사용량 실시간 표시
파일 브라우저	없음	VS Code 파일 트리	내장 파일 브라우저
대화 이력	세션 단위 저장	세션 단위 저장	프로젝트별 영구 이력
설치 의존성	Node.js, npm	VS Code + 확장	독립 설치 파일

Claude Code 데스크톱 앱 메인 화면 — 프로젝트 목록과 대화 인터페이스 — Claude Code 가이드 #16 — 데스크톱 앱 심화 — 데스크톱 앱 메인 화면과 프로젝트 관리 패널 (출처: 공식 문서 및 벤치마크 데이터 기반)

📌 참고: 데스크톱 앱은 터미널 Claude Code와 동일한 모델과 API를 사용합니다. 기능 차이가 아니라 인터페이스와 프로젝트 관리 방식의 차이입니다. 둘을 동시에 사용해도 충돌하지 않습니다.

데스크톱 앱 설치와 초기 설정

데스크톱 앱은 공식 사이트에서 macOS, Windows, Linux용 설치 파일을 직접 내려받거나, 패키지 매니저로 설치할 수 있습니다.

macOS — Homebrew로 설치
# Homebrew Cask로 설치
brew install --cask claude-code

# 또는 직접 DMG 다운로드
# https://code.claude.com/download 에서 최신 버전 다운로드

# 설치 후 첫 실행
open -a "Claude Code"

Windows — winget으로 설치
# Windows Package Manager (winget)
winget install Anthropic.ClaudeCode

# PowerShell에서 버전 확인
Get-AppxPackage -Name "*ClaudeCode*" | Select-Object Name, Version

최초 실행 시 Anthropic 계정 로그인 또는 API 키 입력이 필요합니다. 터미널에서 이미 claude login을 완료했다면, 데스크톱 앱이 자동으로 동일한 인증 정보를 사용합니다.

멀티 프로젝트 관리와 프로젝트 전환

데스크톱 앱의 핵심 강점은 여러 프로젝트를 동시에 관리하는 것입니다. 각 프로젝트는 독립적인 컨텍스트, 대화 이력, 설정을 가집니다.

프로젝트 추가 방법

앱 좌측 사이드바에서 + New Project 클릭
디렉토리를 선택하거나 드래그&드롭으로 프로젝트 폴더 추가
프로젝트 이름과 설명(선택) 입력
해당 프로젝트의 CLAUDE.md가 자동으로 로드됨

빠른 프로젝트 전환

단축키로 프로젝트 간 빠르게 전환할 수 있습니다. 전환 시 각 프로젝트의 마지막 대화 상태가 보존됩니다.

데스크톱 앱 단축키 — 프로젝트 전환
# macOS 단축키
Cmd + 1~9        # 프로젝트 1~9번으로 즉시 전환
Cmd + [          # 이전 프로젝트
Cmd + ]          # 다음 프로젝트
Cmd + Shift + P  # 프로젝트 검색 팔레트 열기

# Windows / Linux 단축키
Ctrl + 1~9       # 프로젝트 1~9번으로 즉시 전환
Ctrl + [         # 이전 프로젝트
Ctrl + ]         # 다음 프로젝트
Ctrl + Shift + P # 프로젝트 검색 팔레트 열기

데스크톱 앱 멀티 프로젝트 관리 화면 — 좌측 프로젝트 목록과 전환 인터페이스 — Claude Code 가이드 #16 — 데스크톱 앱 심화 — 멀티 프로젝트 관리 화면과 빠른 전환 패널 (출처: 공식 문서 및 벤치마크 데이터 기반)

⚠️ 막히는 케이스: 프로젝트를 추가했는데 CLAUDE.md가 로드되지 않는다 — 프로젝트 루트 디렉토리를 정확히 선택했는지 확인하세요. 서브 디렉토리를 프로젝트 폴더로 지정하면 상위에 있는 CLAUDE.md를 찾지 못합니다. 앱 설정에서 프로젝트 경로를 수동으로 수정할 수 있습니다.

워크스페이스 설정과 데스크톱 전용 기능

데스크톱 앱은 터미널에는 없는 고유한 설정과 기능을 제공합니다.

컨텍스트 사용량 시각화

우측 상단의 토큰 미터는 현재 대화에서 사용된 토큰 수와 남은 컨텍스트 윈도우를 실시간으로 표시합니다. 컨텍스트가 80% 이상 차면 경고를 표시하며, /clear로 초기화를 유도합니다.

내장 파일 브라우저

대화 창 옆에 프로젝트 파일 트리를 열 수 있습니다. 파일을 클릭하면 해당 파일의 내용을 대화 컨텍스트에 첨부할 수 있습니다.

대화 이력 영구 저장

각 프로젝트의 대화 이력이 앱 로컬에 저장됩니다. 앱을 완전히 종료했다가 다시 열어도 이전 대화를 이어갈 수 있습니다.

데스크톱 앱 설정 파일 위치
# macOS
~/Library/Application Support/Claude Code/settings.json
~/Library/Application Support/Claude Code/projects/

# Windows
%APPDATA%\Claude Code\settings.json
%APPDATA%\Claude Code\projects\

# Linux
~/.config/claude-code/settings.json
~/.config/claude-code/projects/

⚠️ 막히는 케이스: 앱을 재설치했더니 프로젝트와 대화 이력이 모두 사라졌다 — 재설치 전에 설정 파일 경로를 백업하지 않으면 이력이 삭제됩니다. 앱 설정의 Export Settings 기능으로 주기적으로 백업하거나, projects/ 디렉토리를 cloud storage에 심볼릭 링크로 연결해두는 방법을 권장합니다.

어떤 작업에 데스크톱 앱이 유리한가?

모든 작업에 데스크톱 앱이 더 좋은 것은 아닙니다. 작업 성격에 따라 환경을 선택하는 것이 효율적입니다.

상황	권장 환경	이유
여러 프로젝트 동시 진행	데스크톱 앱	프로젝트 전환과 이력 관리 편리
CI/CD 자동화	터미널	스크립트 실행, 파이프라인 통합
코드 작성 + 리뷰 병행	VS Code 확장	에디터와 대화를 같은 화면에서
장기 세션, 컨텍스트 추적	데스크톱 앱	토큰 시각화, 이력 영구 저장
리모트 서버 작업	터미널	SSH 환경에서 GUI 앱 실행 불가

⚠️ 막히는 케이스: 데스크톱 앱에서 터미널 명령을 실행하면 프로젝트 디렉토리가 아닌 홈 디렉토리에서 실행된다 — 데스크톱 앱의 내장 터미널은 기본 쉘 디렉토리에서 시작합니다. 앱 설정에서 Default working directory를 프로젝트 루트로 지정하거나, 명령 실행 시 절대 경로를 명시하세요.

데스크톱 앱 워크스페이스 설정 화면 — 컨텍스트 토큰 시각화와 설정 패널 — Claude Code 가이드 #16 — 데스크톱 앱 심화 — 워크스페이스 설정과 토큰 시각화 화면 (출처: 공식 문서 및 벤치마크 데이터 기반)

요약 및 관련 편

정리하면:

데스크톱 앱은 터미널과 동일한 엔진이지만 멀티 프로젝트 관리, 컨텍스트 시각화, 대화 이력 영구 저장에서 강점
여러 프로젝트를 전환하며 작업하거나 장기 세션을 유지할 때 데스크톱 앱이 유리
CI/CD 자동화나 리모트 서버 작업은 터미널이 필수
설정 파일은 OS별 앱 데이터 디렉토리에 저장 — 재설치 전 백업 필수
프로젝트 전환 단축키(Cmd+[, Cmd+])를 활용하면 멀티 프로젝트 관리 효율 극대화