Claude Code 가이드 #16 — 터미널에서 쓰는 Claude Code와 데스크톱 앱은 같은 엔진이지만 경험이 다릅니다. 이 편에서는 데스크톱 앱만의 기능, 터미널·VS Code와의 차이, 멀티 프로젝트 관리와 워크스페이스 설정까지 심화 기준으로 정리합니다. Claude Code는 세 가지 실행 환경을 제공합니다. 각 환경이 어떤 차이가 있는지 먼저 이해해야 올바른 환경을 선택할 수 있습니다.
Claude Code 가이드 #16 — 터미널에서 쓰는 Claude Code와 데스크톱 앱은 같은 엔진이지만 경험이 다릅니다. 이 편에서는 데스크톱 앱만의 기능, 터미널·VS Code와의 차이, 멀티 프로젝트 관리와 워크스페이스 설정까지 심화 기준으로 정리합니다.
※ 이 글은 2026년 3월 기준, Claude Code 데스크톱 공식 문서 기반으로 작성됐습니다.
Claude Code는 세 가지 실행 환경을 제공합니다. 각 환경이 어떤 차이가 있는지 먼저 이해해야 올바른 환경을 선택할 수 있습니다.
| 항목 | 터미널 | VS Code 확장 | 데스크톱 앱 |
|---|---|---|---|
| UI | 텍스트 기반 | 에디터 사이드패널 | 독립 GUI 앱 |
| 멀티 프로젝트 | 탭/tmux 분할 | 워크스페이스 단위 | 내장 프로젝트 전환 |
| 컨텍스트 시각화 | 없음 | 제한적 | 토큰 사용량 실시간 표시 |
| 파일 브라우저 | 없음 | VS Code 파일 트리 | 내장 파일 브라우저 |
| 대화 이력 | 세션 단위 저장 | 세션 단위 저장 | 프로젝트별 영구 이력 |
| 설치 의존성 | Node.js, npm | VS Code + 확장 | 독립 설치 파일 |
데스크톱 앱은 공식 사이트에서 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을 완료했다면, 데스크톱 앱이 자동으로 동일한 인증 정보를 사용합니다.
🎓 유데미 강의 추천
Claude Code 실전 강의 — AI 코딩을 지금 시작하세요
설치부터 자동화·에이전트 활용까지, 실무에서 바로 쓰는 Claude Code 활용법을 단계별로 배울 수 있습니다.
데스크톱 앱의 핵심 강점은 여러 프로젝트를 동시에 관리하는 것입니다. 각 프로젝트는 독립적인 컨텍스트, 대화 이력, 설정을 가집니다.
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 # 프로젝트 검색 팔레트 열기
데스크톱 앱은 터미널에는 없는 고유한 설정과 기능을 제공합니다.
우측 상단의 토큰 미터는 현재 대화에서 사용된 토큰 수와 남은 컨텍스트 윈도우를 실시간으로 표시합니다. 컨텍스트가 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/
모든 작업에 데스크톱 앱이 더 좋은 것은 아닙니다. 작업 성격에 따라 환경을 선택하는 것이 효율적입니다.
| 상황 | 권장 환경 | 이유 |
|---|---|---|
| 여러 프로젝트 동시 진행 | 데스크톱 앱 | 프로젝트 전환과 이력 관리 편리 |
| CI/CD 자동화 | 터미널 | 스크립트 실행, 파이프라인 통합 |
| 코드 작성 + 리뷰 병행 | VS Code 확장 | 에디터와 대화를 같은 화면에서 |
| 장기 세션, 컨텍스트 추적 | 데스크톱 앱 | 토큰 시각화, 이력 영구 저장 |
| 리모트 서버 작업 | 터미널 | SSH 환경에서 GUI 앱 실행 불가 |
정리하면:
Cmd+[, Cmd+])를 활용하면 멀티 프로젝트 관리 효율 극대화관련 가이드:
참고: 데스크톱 앱 공식 문서 | Claude Code 개요
프로젝트를 추가할 때 폴더를 정확히 프로젝트 루트로 지정하는 것부터 챙기세요. 서브 디렉토리를 프로젝트 폴더로 잡으면 상위에 있는 CLAUDE.md를 못 찾아 프로젝트 규칙이 통째로 빠진 채 작업하게 됩니다. 다음으로는 설정과 이력이 저장되는 경로를 알아두세요. macOS는 ~/Library/Application Support/Claude Code/, Windows는 %APPDATA%\Claude Code\에 settings.json과 projects/ 폴더가 있습니다. 데스크톱 앱은 대화 이력을 이 로컬 폴더에만 보관하므로, 재설치 전에 Export Settings로 백업하거나 projects/를 클라우드에 심볼릭 링크로 연결해두는 것이 가장 먼저 해둘 일입니다.
가장 뼈아픈 실수는 백업 없이 앱을 재설치하는 것입니다. 대화 이력과 프로젝트 목록은 OS별 앱 데이터 폴더의 projects/에만 저장되어 있어서, 이 경로를 백업하지 않고 재설치하면 그동안의 이력이 전부 사라집니다. 두 번째로 잦은 것이 내장 터미널 디렉토리 혼동입니다. 데스크톱 앱의 터미널은 기본 쉘 디렉토리, 즉 보통 홈 디렉토리에서 시작하기 때문에, 프로젝트를 열어둔 상태라도 상대 경로 명령이 엉뚱한 곳에서 실행됩니다. 앱 설정의 Default working directory를 프로젝트 루트로 지정하거나 명령에 절대 경로를 쓰는 습관이 안전합니다.
데스크톱 앱은 여러 프로젝트를 전환하며 동시에 진행하거나, 장기 세션에서 토큰 사용량을 실시간으로 보며 컨텍스트를 관리해야 할 때 가장 유리합니다. 프로젝트별 대화 이력이 영구 저장돼 앱을 껐다 켜도 이어가는 점도 장점입니다. 반면 CI/CD 자동화나 파이프라인 통합은 스크립트 실행이 가능한 터미널이 필수이고, SSH 원격 서버에서는 GUI 앱 자체를 띄울 수 없어 부적합합니다. 코드 작성과 리뷰를 같은 화면에서 병행하려면 VS Code 확장이 더 맞습니다. 즉 멀티 프로젝트·장기 컨텍스트는 데스크톱, 자동화·원격은 터미널, 에디터 밀착 작업은 VS Code로 나누는 것이 기준입니다.
데스크톱 앱 공식 문서(code.claude.com/docs/en/desktop)에서 단축키와 워크스페이스 설정을 먼저 확인하고, OS별 설정 경로(macOS의 ~/Library/Application Support/Claude Code/, Windows의 %APPDATA%\Claude Code\)에 있는 settings.json과 projects/ 폴더 구조를 직접 열어보면 이력 백업 전략을 세우기 좋습니다. 컨텍스트 토큰 미터와 연결되는 /clear 명령, Export Settings 백업, projects/를 클라우드에 심볼릭 링크로 거는 방식이 실무 키워드입니다. 토큰 관리를 더 깊게 보려면 컨텍스트·토큰 최적화 편을 이어서 읽는 것을 권합니다.
데스크톱 앱은 터미널과 같은 엔진을 쓰지만 멀티 프로젝트 전환, 토큰 사용량 실시간 시각화, 프로젝트별 영구 대화 이력에서 차별화됩니다. 여러 프로젝트를 오가거나 장기 세션의 컨텍스트를 추적해야 하는 개발자에게 유리하고, CI/CD 자동화나 SSH 원격 작업은 여전히 터미널이 맡습니다. 단 대화 이력이 로컬 projects/ 폴더에만 저장되므로, 재설치 전 Export Settings 백업을 빼먹으면 그동안의 이력이 통째로 사라진다는 점이 가장 중요한 주의사항입니다.
🎓 관련 강의
Claude Code 완전 정복 — 유데미 강의
이 글에서 다룬 내용을 더 체계적으로 배우고 싶다면 강의를 확인해보세요. 실전 예제 중심으로 구성되어 있습니다.
