Claude Code Desktop : 터미널 없이 AI 코딩 에이전트 사용하기

안녕하세요! 갓대희 입니다. :- )

오늘은 "Claude Code Desktop Preview"에 대해 써보려고 한다. 

 

 

Anthropic이 Claude Desktop 앱에 AI 코딩 에이전트 기능을 추가했다. 터미널에서만 가능했던 Claude Code가 이제 GUI 환경에서 사용 가능해졌으며, 여러 세션을 병렬로 실행할 수 있다. 2025년 11월 24일 Opus 4.5와 함께 공개되었다.

 

나의 경우 Claude Desktop을 사용하던 중 다음과 같이 Claude Code Desktop 버전 사용을 유도하는 팝업이 노출되어 확인 할 수 있었다. 

 

 

⚡ 3줄 요약

1. Claude Desktop 앱에서 Claude Code 프리뷰 사용 가능 - GUI로 코드 분석, 편집, 실행
2. Git worktree 기반 병렬 세션으로 여러 작업 동시 진행 (버그 수정 + 리서치 + 문서화)
3. Max/Team/Enterprise 플랜 전용, 로컬 세션과 GitHub 클라우드 세션 모두 지원

ex) 금요일 저녁 6시, 퇴근 10분 전. Slack에 긴급 버그 리포트가 올라온다. "프로덕션에서 결제 오류 발생". 지금 작업 중인 기능 브랜e치를 stash하고, 핫픽스 브랜치로 전환하고, 디버깅 시작. 원인을 찾았는데, 다른 팀원이 관련 문서를 요청한다. 또 컨텍스트 스위칭.

개발자라면 누구나 겪어봤을 컨텍스트 스위칭의 고통이다.

 

Claude Code Desktop Preview가 이 문제를 해결하려 한다. 여러 개의 AI 코딩 세션을 병렬로 실행하면서, 한 에이전트는 버그를 고치고, 다른 에이전트는 GitHub을 리서치하고, 또 다른 에이전트는 문서를 업데이트한다.

터미널에서만 가능했던 Claude Code가 이제 GUI 환경에서도 사용 가능해졌다. 그것도 병렬 세션과 함께.

 

Claude Code란?

Claude Code는 Anthropic의 에이전틱(Agentic) 코딩 어시스턴트다. 단순히 코드를 생성하는 것이 아니라, 코드베이스를 탐색하고, 파일을 읽고 편집하고, 터미널 명령어를 실행하고, Git 작업까지 수행하는 자율적인 AI 에이전트다.

클로드 코드에 대해서는 이미 다들 알고 계실것 같고, 나도 초창기에 관련글을 이미 작성했었기에 넘어 가려고 한다. 

기존 제공되던 방식들

 - CLI 방식 :

Claude Code 2.0(클로드 코드 2.0) 설치 - (Claude Code 1.0에서 2.0 업그레이드 하기)

 - web 방식 : 

Claude Code Web - 설치 없이 브라우저만으로 코드 자동화, 병렬 작업 해보기

 

Claude Code Desktop Preview

Claude Code Desktop은 기존 CLI 기반의 Claude Code를 네이티브 데스크톱 앱에서 사용할 수 있게 한 기능이다.

차이점은 다음과 같은 내용 정도 일 것 이다.

 

1. 비주얼 인터페이스
터미널 대신 GUI로 Task, Grep, Read, Edit 등의 도구 실행 과정을 시각적으로 확인할 수 있다.

2. 병렬 세션 지원
여러 개의 로컬/원격 세션을 동시에 실행할 수 있다. Git worktree를 활용해 각 세션이 독립된 작업 공간을 갖는다.

3. VS Code 연동
Desktop에서 작업 중인 내용을 VS Code에서 열거나, CLI로 이어서 작업할 수 있다.

Claude Code 출시 타임라인

• 2025년 2월: Claude Code CLI 최초 공개
• 2025년 10월 20일: Claude Code on the Web 발표 (브라우저에서 GitHub 연동)
• 2025년 11월 24일: Claude Code Desktop Preview 공개 (Opus 4.5와 동시 발표)

 

Claude Code 플랫폼 비교

Claude Code는 여러 플랫폼에서 사용할 수 있다. 각 플랫폼의 특징을 비교해보자.

항목	Desktop (신규)	CLI	Web (claude.ai/code)
인터페이스	GUI (비주얼)	터미널	브라우저
파일 접근	로컬 전체	로컬 전체	GitHub 레포만
병렬 세션	Git worktree 기반	여러 터미널 이용	여러 탭으로 가능
실행 환경	로컬 + 원격	로컬만	Anthropic 클라우드
버전	번들 안정 버전	최신 버전	클라우드 버전
VS Code 연동	내장	확장 설치 필요	미지원

💡 버전 차이 참고
Desktop은 안정성을 우선하여 번들된 버전을 사용하고, CLI는 최신 기능을 먼저 제공한다. 두 버전이 다를 수 있으므로 참고하자.

 

설치 및 시작하기

요구사항

• 소프트웨어: Claude Desktop 앱 (macOS, Windows, Linux)
• 구독: Claude Max ($100~200/월), Team ($30/사용자/월), 또는 Enterprise
• 제한: Windows arm64 아키텍처에서는 로컬 세션 불가
• 추가 비용: 없음 (플랜에 포함)

Pro 플랜 사용자
Pro 플랜($20/월)은 Claude Code for Web만 사용 가능하다. Desktop에서 Claude Code를 사용하려면 Max 플랜 이상이 필요하다.

 

설치 방법

1. Claude Desktop 앱 다운로드

https://claude.ai/download 에서 운영체제에 맞는 버전 다운로드

 

2. 앱 실행 후 로그인

Max/Team/Enterprise 계정으로 로그인

 

3. Claude Code 프리뷰 안내 확인

"Claude Code에 오신 것을 환영합니다!" 화면에서 "시작하기" 클릭

 

또는 좌측 상단의 </> 클릭

 

4. 런타임 종속성 설치

"런타임 종속성 설치" 버튼 클릭 - Claude Code 실행에 필요한 번들(ripgrep 등)이 자동 다운로드됨 (인터넷 연결 필요)

자세한 내용은 공식 페이지에서 확인하자.

https://code.claude.com/docs/en/desktop

 

 - 설치가 완료된 후의 모습

 

5. 프로젝트 폴더 선택

Git이 초기화된 폴더를 선택하면 worktree 기반 세션 생성 가능 하다.

⚠️ Git 초기화 필수
Git이 초기화되지 않은 폴더에서는 worktree를 생성할 수 없다. 병렬 세션을 사용하려면 반드시 Git 레포지토리여야 한다.

 

Desktop 초기 화면 구성

설치 완료 후 Claude Code Desktop을 실행하면 다음과 같은 초기 화면이 나타난다.

 

세션 타입 선택

Claude Code Desktop은 로컬 세션과 클라우드 세션 두 가지 방식을 제공한다.

옵션	설명
💻 Local worktree	로컬 세션 - 내 컴퓨터의 프로젝트 폴더를 선택하여 작업한다. "폴더 선택" 드롭다운에서 로컬 디렉토리를 탐색할 수 있다. Git 레포지토리를 선택하면 worktree 기반 병렬 세션을 사용할 수 있다.
☁️ Default (Select repository)	클라우드 세션 - GitHub 원격 저장소에 연결하여 Anthropic 클라우드에서 작업한다. "Select repository" 드롭다운에서 연결된 GitHub 저장소 목록을 선택할 수 있다. GitHub 앱 설치가 필요하다.
➕ 환경 추가	클라우드 환경 생성 - 새로운 클라우드 환경을 만들고 환경 변수와 네트워크 액세스를 설정할 수 있다.

 

클라우드 환경 설정 (New cloud environment)

"환경 추가"를 클릭하면 클라우드 환경을 커스터마이징할 수 있는 다이얼로그가 나타난다.

• 이름: 클라우드 환경의 이름을 지정한다 (예: Default, Production, Development)
• 네트워크 액세스: Claude가 접근할 수 있는 도메인을 설정한다. "신뢰됨" 옵션을 선택하면 npm 패키지 다운로드 등 외부 네트워크 접근이 가능하다.
• 환경 변수: .env 형식으로 API 키, 데이터베이스 URL 등을 설정한다.
  API_KEY=your_key
DATABASE_URL=your_url

⚠️ 클라우드 세션 참고사항

• 클라우드 세션은 GitHub 저장소만 지원한다. (GitLab 등 미지원)
• 클라우드 세션 사용량은 다른 Claude Code 사용량과 공유된다.
• 비공개 저장소 접근을 위해 Claude GitHub 앱 설치가 필요하다.
  
  

 

퀵 액션 카드

초기 화면 하단에는 빠른 시작을 위한 제안 프롬프트가 표시된다.

• "Create or update my CLAUDE.MD file"
  프로젝트의 CLAUDE.md 파일을 생성하거나 업데이트한다. 이 파일에는 프로젝트 컨벤션, 아키텍처 패턴, 팀 워크플로우 등을 정의할 수 있다.
• "Search for a TODO comment and fix it"
  코드베이스에서 TODO 주석을 검색하고 해결한다.
• "Recommend areas to improve our tests"
  테스트 커버리지를 분석하고 개선이 필요한 영역을 추천받는다.

💡 CLAUDE.md란?
프로젝트 루트에 위치하는 메모리 파일로, Claude가 프로젝트 컨텍스트를 이해하는 데 사용한다. /init 명령어로 생성할 수 있으며, 팀원과 소스 컨트롤을 통해 공유된다.

 

ex) 

 

 

핵심 기능 상세

1. 비주얼 도구 인터페이스

Desktop에서는 Claude가 사용하는 도구들을 시각적으로 확인할 수 있다:

• Task: 하위 작업 생성 및 실행 (예: "Find claw'd crab component")
• Grep: 코드베이스 내 패턴 검색 (예: "claw|crab|mascot")
• Read: 파일 읽기 (예: "Read 120 lines")
• Edit: 파일 편집 - 변경된 코드가 하이라이트로 표시됨
• Bash: 터미널 명령어 실행

 

2. 실시간 변경 추적

Claude가 파일을 수정하면 diff 형태로 변경 내역을 실시간 확인할 수 있다. 추가된 라인은 녹색(+), 삭제된 라인은 빨간색(-)으로 표시된다.

// ClawdCharacter.tsx 편집 예시
10   }
12 + @keyframes crab-walk {
13 +   0% { transform: translateX(0); }
14 +   25% { transform: translateX(-60px); }
15 +   50% { transform: translateX(0); }
16 +   75% { transform: translateX(60px); }
17 +   100% { transform: translateX(0); }
18 + }

ex) CLAUDE.md 생성 ( 신규 파일이니 모두 녹색(+) )

 ex) 빨간색(-)

 

3. VS Code / CLI 전환

Desktop에서 작업하다가 더 복잡한 편집이 필요하면 VS Code에서 열거나 CLI로 이어서 작업하는 옵션을 사용할 수 있다. 작업 중인 worktree를 그대로 유지하면서 도구를 전환할 수 있어 유연하다.

 

우측 하단에 위치해 있다. 

ex) VSCode

 - 권한을 허용해 주자.

 

 - 다만 실제 내 폴더의 경로가 아닌 신규 별도의 경로(~/.claude-worktrees/하위)에서 열리는것으로 보인다. (경로는 claude desktop 설정에서 변경 가능한데 하기에 다시 작성해 두겠다.)  바로 vscode로 코딩을 이어갈 수 있따.

 

 - cli 도 동일하게 확인해보자.

 

 - cli는 Claude Desktop 화면 위에 팝업처럼 뜨며 바로 이전 대화 Session을 이어 갈 수 있게 Claude Code가 뜨게 되는 것을 볼 수 있다. 

 

 - 하기 내용은 참고

  

프리뷰 버전 알아두기

⚠️ 현재 프리뷰 상태입니다

Claude Code Desktop은 2025년 11월 24일 기준 프리뷰 버전으로 출시되었습니다. 정식 버전이 아니므로 다음 사항을 알아두세요:

• 기능 변경 가능: 향후 업데이트로 UI나 기능이 변경될 수 있습니다
• 불안정할 수 있음: 예상치 못한 오류나 응답 지연이 발생할 수 있습니다
• CLI와 버전 차이: Desktop은 번들 버전을 사용하여 CLI보다 최신 기능이 늦게 적용될 수 있습니다
• 플랫폼 제한: Windows arm64에서 로컬 세션 미지원

 

Plan Mode : 안전한 코드 탐색(CLI)

Plan Mode는 Claude Code의 읽기 전용 모드다. 코드베이스를 탐색하고 계획을 세우되, 실제 파일 수정이나 명령어 실행은 차단된다.

⚠️ CLI 전용 기능
Plan Mode는 CLI 터미널에서만 사용 가능하다. Desktop GUI에서 Plan Mode를 사용하려면 화면 하단의 "CLI" 버튼을 클릭하여 터미널로 전환해야 한다.

 

활성화 방법

• Shift+Tab 두 번: 터미널 하단에 ⏸ plan mode on 표시됨
• CLI 시작 옵션: claude --permission-mode plan
• 기본값 설정: .claude/settings.json에서 "defaultMode": "plan" 설정

 

Plan Mode에서 가능한 것

허용되는 도구
• Read: 파일 읽기
• LS: 디렉토리 목록
• Glob: 파일 패턴 검색
• Grep: 콘텐츠 검색
• Task: 리서치 에이전트
• WebFetch/WebSearch: 웹 검색
• TodoRead/TodoWrite: 작업 관리

차단되는 도구
• Edit/MultiEdit: 파일 편집
• Write: 파일 생성
• Bash: 명령어 실행
• NotebookEdit: 노트북 편집
• 상태를 변경하는 MCP 도구

💡 Plan Mode 활용 팁
새로운 코드베이스를 처음 탐색할 때, 또는 대규모 리팩토링 전 영향 범위를 파악할 때 Plan Mode를 먼저 사용하자.
계획이 확정되면 실행 모드로 전환하여 실제 작업을 수행한다.

 

Git Worktree와 병렬 세션

Claude Code Desktop의 가장 강력한 기능은 Git worktree 기반 병렬 세션이다. 같은 레포지토리에서 여러 브랜치를 독립된 디렉토리로 체크아웃하여, 각 세션이 서로 간섭 없이 작업할 수 있다.

병렬 세션 활용 예시

동시에 3개 작업 진행하기

세션 1	버그 수정: "로그인 오류 #1234 수정해줘"
세션 2	리서치: "이 라이브러리의 최신 버전 변경사항 조사해줘"
세션 3	문서화: "API 문서 업데이트해줘"

각 세션은 독립된 worktree에서 실행되므로 서로의 작업에 영향을 주지 않는다.

 

.worktreeinclude 설정

Git worktree를 생성하면 .gitignore에 있는 파일들(node_modules, .env 등)은 기본적으로 복사되지 않는다. 이를 해결하려면 프로젝트 루트에 .worktreeinclude 파일을 생성한다:

# .worktreeinclude 예시
.env
.env.local
node_modules/
venv/
.claude/settings.json

⚠️ 안전 기능
.worktreeinclude에 매칭되면서 동시에 .gitignore에도 있는 파일만 복사된다. 추적되는 파일이 실수로 복제되는 것을 방지한다.

 

Worktree 저장 위치

기본 위치는 ~/.claude-worktrees이며, Desktop 앱 설정에서 변경할 수 있다.

 

 

로컬 세션 vs 원격 세션

Claude Code Desktop은 두 가지 실행 환경을 제공한다:

구분	로컬 세션	원격 세션
실행 위치	내 컴퓨터	Anthropic 클라우드
리소스 사용	로컬 CPU/메모리	클라우드 리소스
Windows arm64	미지원	지원
적합한 상황	민감한 코드, 오프라인 작업	리소스 절약, arm64 사용자

원격 세션 활용
Windows arm64 사용자나 로컬 리소스가 부족한 경우, 원격 세션을 사용하면 Anthropic의 클라우드 인프라에서 코딩 작업을 수행할 수 있다.

 

실제 활용 시나리오

시나리오 1: 새 코드베이스 온보딩

상황: 새로 합류한 프로젝트의 구조를 빠르게 파악해야 함

💬 프롬프트:
"이 코드베이스의 전체 구조를 설명해줘. 주요 모듈, 데이터 흐름, 인증 방식이 어떻게 되어 있는지 알려줘."

결과: Claude가 Plan Mode로 코드베이스를 탐색하고, 아키텍처 다이어그램과 함께 설명

시나리오 2: 애니메이션 구현

상황: 마스코트 캐릭터에 걷는 애니메이션 추가

💬 프롬프트:
"Make Claw'd dance" (스크린샷 예시)

결과: Claude가 컴포넌트를 찾고(Grep), 파일을 읽고(Read), @keyframes 애니메이션을 추가(Edit)

시나리오 3: 병렬 리팩토링

상황: 여러 모듈을 동시에 리팩토링해야 함

💬 각 세션 프롬프트:
세션1: "auth 모듈의 레거시 코드를 최신 패턴으로 리팩토링해줘"
세션2: "API 응답 타입을 TypeScript로 정리해줘"
세션3: "테스트 커버리지를 80%까지 올려줘"

결과: 각 세션이 독립된 worktree에서 작업, 완료 후 각각 PR 생성

 

보안 및 권한

Claude Code Desktop은 로컬 파일 시스템에 직접 접근한다. 이는 강력한 기능이지만, 보안 측면에서 이해해야 할 사항이 있다.

 

어떤 데이터가 Anthropic으로 전송되나?

Claude Code Desktop 사용 시 다음 데이터가 Anthropic 서버로 전송됩니다.

• 프로젝트 파일 내용 (Claude가 분석 요청받은 범위)
• 터미널 명령어 및 출력
• Git 히스토리 및 상태
• 사용자 프롬프트 (질문 및 요청 내용)

※ 기본 설정으로 AI 학습에 사용되지 않습니다. Team/Enterprise는 데이터 보존 정책을 별도 설정할 수 있습니다.

 

프로젝트별 설정: CLAUDE.md

프로젝트 루트에 CLAUDE.md 파일을 생성하여 Claude의 동작을 프로젝트에 맞게 커스터마이징할 수 있다. 코딩 컨벤션, 금지 작업, 프로젝트 맥락 등을 정의할 수 있다.

# CLAUDE.md 예시

## 프로젝트 개요
React + TypeScript 기반 e-commerce 프로젝트

## 코딩 컨벤션
- 함수형 컴포넌트와 hooks 사용
- CSS-in-JS: styled-components
- 상태 관리: Zustand

## 금지 사항
- .env 파일 절대 수정 금지
- main 브랜치 직접 커밋 금지
- rm -rf 명령어 사용 금지

## 자주 사용하는 명령어
- npm run dev: 개발 서버 실행
- npm run test: 테스트 실행

주의사항

• 민감한 정보 주의: API 키, 비밀번호 등이 포함된 파일은 .gitignore에 추가하고, Claude에게 명시적으로 제외 요청
• 실행 전 검토: Claude가 생성한 명령어(특히 rm, git push --force 등)는 실행 전 반드시 확인
• 백업 권장: 중요한 변경 전 Git 커밋 또는 백업 권장

Anthropic 권장 사항

• 변경사항을 항상 검토한 후 커밋
• Plan Mode로 먼저 영향 범위 파악 후 실행
• 조직의 코드 리뷰 프로세스 준수

 

한계점과 주의사항

1. 프리뷰 상태
아직 정식 버전이 아니므로 예상치 못한 버그나 기능 변경이 있을 수 있다.

2. CLI보다 기능이 적을 수 있음
Desktop은 안정성을 우선하여 번들 버전을 사용한다. CLI가 최신 기능을 먼저 받을 수 있다.

3. Windows arm64 미지원
Windows arm64 아키텍처에서는 로컬 세션을 실행할 수 없다. 원격 세션만 가능.

4. Git 초기화 필수
병렬 세션을 사용하려면 Git 레포지토리여야 한다. Git이 없는 폴더에서는 단일 세션만 가능.

5. 사용량 공유
Claude Code 사용량은 Claude 웹/데스크톱/모바일과 공유된다. Max 5x는 5시간당 ~225 메시지.

 

누가 써야 하나?

✅ 추천 대상

1. 터미널이 익숙하지 않은 개발자
GUI 환경에서 AI 코딩 에이전트를 체험하고 싶다면 Desktop이 좋은 시작점이다.

2. 멀티태스킹이 필요한 개발자
여러 작업을 동시에 진행해야 하고, 컨텍스트 스위칭 비용을 줄이고 싶다면 병렬 세션이 유용하다.

3. 이미 Claude Max를 사용 중인 사람
추가 비용 없이 사용할 수 있다. 기존 Claude와 동일한 사용량 한도 내에서 작동한다.

 

❌ 비추천 대상

1. Pro 플랜 사용자
Desktop Claude Code는 Max 이상에서만 사용 가능하다. Pro는 Web 버전만 접근 가능.

2. 최신 기능이 필요한 파워 유저
CLI가 항상 최신 기능을 먼저 받는다. 최신 기능이 필요하다면 CLI를 유지하자.

3. 이미 Cursor/Windsurf 등 AI IDE를 잘 쓰고 있는 경우
기존 워크플로우가 잘 작동한다면 굳이 전환할 필요는 없다.

 

자주 묻는 질문

Q: Claude Code Desktop은 무료인가요?

A: Claude Max($100~200/월), Team($30/사용자/월), Enterprise 플랜에 포함되어 있습니다. 별도 비용은 없지만, Pro($20/월)에서는 사용할 수 없습니다.

Q: CLI와 Desktop 중 어떤 것을 써야 하나요?

A: 터미널에 익숙하고 최신 기능이 필요하다면 CLI, GUI와 병렬 세션 관리가 필요하다면 Desktop을 추천합니다. 둘 다 사용해도 됩니다.

Q: 사용량 제한은 어떻게 되나요?

A: Claude 웹/데스크톱/모바일/Code 모두 사용량을 공유합니다. Max 5x는 5시간당 ~225 메시지, Max 20x는 ~900 메시지입니다.

Q: Git이 없는 폴더에서도 사용할 수 있나요?

A: 단일 세션은 가능하지만, 병렬 세션(worktree)은 Git 레포지토리에서만 작동합니다.

Q: Plan Mode는 어떻게 사용하나요?

A: 새 코드베이스 탐색, 대규모 리팩토링 계획, 영향 범위 파악 등 실제 변경 전에 안전하게 분석할 때 사용합니다. Shift+Tab 두 번으로 활성화합니다.

Q: 원격 세션은 무엇인가요?

A: Anthropic의 클라우드 인프라에서 실행되는 세션입니다. 로컬 리소스를 사용하지 않고도 코딩 작업을 수행할 수 있습니다.

참고 자료

• Claude Code Desktop 공식 문서 - 설치 및 사용 방법
• Claude Opus 4.5 공식 발표 - Desktop 프리뷰 발표 포함
• Claude Code on the Web - 웹 버전 소개
• Claude Code Common Workflows - 활용 가이드
• Claude Max 플랜 가격 - 요금제 정보

 

마무리: AI 코딩 에이전트의 새로운 형태

터미널에서 GUI로, 단일에서 병렬로

Claude Code Desktop은 AI 코딩 에이전트를 더 접근하기 쉽게 만든다.
터미널이 익숙하지 않은 개발자도 GUI로 시작할 수 있고,
병렬 세션으로 멀티태스킹의 효율을 높일 수 있다.

아직 프리뷰 단계지만, AI와 함께 코딩하는 방식의 변화를 보여준다.

Claude Code Desktop의 핵심은 병렬 세션과 비주얼 인터페이스다. Git worktree를 활용해 여러 작업을 동시에 진행하고, GUI로 Claude의 작업 과정을 실시간 확인할 수 있다.

최종 판단: 이미 Claude Max를 사용 중이라면 추가 비용 없이 체험해볼 가치가 있다. 터미널에 익숙하다면 CLI와 병행 사용도 좋은 선택이다. AI 코딩 에이전트의 새로운 형태를 경험해보자.

 

AI 코딩 에이전트 시장은 Cursor, Windsurf, GitHub Copilot 등 다양한 플레이어가 경쟁 중이다. Anthropic이 Desktop 앱에 Claude Code를 통합한 것은 개발자 경험을 중시하는 전략적 선택으로 보인다.

관련 글
Claude for Excel

2025.11.26 - [AI/Claude] - Claude for Excel 리뷰 : AI가 엑셀을 직접 분석하고 수정하는 시대