Claude Code '로컬 세션에는 Git이 필요합니다' 해결: 버전·Worktree부터

Claude 데스크톱 앱의 Code 탭에서 폴더를 고르자마자 입력창 위에 빨간 글씨로 '로컬 세션에는 Git이 필요합니다.'가 뜨고 'Git 설치' 대화 상자가 앞을 막는다면, Git을 다시 설치하기 전에 앱 버전부터 보세요. Claude Code 데스크톱 문제 해결 문서의 Git 항목에 따르면 2026년 10월 23일 기준 Git이 필요한 것은 Worktree를 켠 세션뿐이고, Windows 데스크톱 앱 1.49585.0 미만은 Worktree와 상관없이 모든 로컬 세션에서 Git을 요구했습니다. 그래서 Windows에서 Help → About Claude 의 번호가 1.49585.0보다 낮다면 답은 Help → Check for Updates… 메뉴로 앱을 업데이트하는 것이고, 이 경우에는 Git을 몇 번 다시 깔아도 풀리지 않습니다.

버전이 최신인데도 뜬다면 둘 중 하나입니다. 세션에 Worktree가 켜져 있다면 Worktree를 끄거나 Git(Windows는 Git for Windows)을 설치하면 됩니다. Git이 이미 깔려 있는데도 뜬다면 앱이 Git을 찾거나 실행하지 못하는 것이므로, Windows는 CLAUDE_CODE_GIT_BASH_PATH 환경 변수를 bash.exe 경로로 지정한 뒤 트레이 아이콘까지 종료하고, Mac은 Xcode 라이선스와 앱 로그를 확인합니다. 터미널에서 claude를 실행했을 때 나오는 "requires git-bash" 계열 메시지는 데스크톱 앱과 다른 화면입니다.

직접 확인한 범위는 좁습니다. 2026년 10월 23일 Mac 한 대(macOS 26.1, Claude 데스크톱 3.6556.2)에서 로컬 세션이 정상으로 열리는 것과 앱에 들어 있는 Git 오류 문구를 확인했고, Windows에서는 아무것도 실행하지 않았습니다. 아래의 Windows 절차는 Anthropic 문서와 GitHub에 올라온 사용자 보고를 옮긴 것이며, 검증된 해결책이 아닙니다.

'로컬 세션에는 Git이 필요합니다'가 뜨는 네 가지 상황

같은 대화 상자라도 원인은 네 가지로 나뉘고, 해결 방법은 원인마다 다릅니다. 앱 버전, Worktree가 켜져 있는지, 터미널에서 Git이 실행되는지 세 가지만 보면 자기가 어디에 해당하는지 대부분 가려집니다.

첫 번째와 세 번째는 증상이 같아 보여서 가장 많이 헷갈립니다. Windows에서 Git을 여러 번 다시 설치하고 환경 변수를 맞췄는데도 몇 달째 같은 대화 상자가 떴다는 GitHub 보고(anthropics/claude-code 이슈 #72976)는 대부분 1.49585.0 이전 앱에서 나온 것이므로, 버전 확인을 건너뛰고 세 번째 상황의 절차부터 반복하면 시간만 듭니다.

Claude Code 데스크톱에 Git이 꼭 필요한가: Worktree를 켤 때만

2026년 10월 23일 기준 데스크톱 앱에서 Git은 Worktree를 쓸 때만 필요합니다. Claude Code 데스크톱 문서의 Worktree 항목에 따르면 Worktree는 세션마다 프로젝트를 Git worktree라는 별도 사본으로 떼어 내 작업하는 기능이고, 기본값은 꺼짐이라 Claude는 고른 프로젝트 폴더 안에서 바로 작업합니다. Git 저장소가 아닌 폴더에서는 처음부터 Worktree를 켤 수 없으므로, 그런 일반 폴더를 열었는데 이 대화 상자가 뜬다면 오래된 앱 버전부터 의심합니다. Windows에서 Git for Windows를 반드시 먼저 깔아야 한다는 설명은 예전 버전 기준입니다.

Worktree를 끄는 위치는 화면 배치에 따라 다릅니다. 현재 배치에서는 입력창 아래 줄의 프로젝트 폴더 컨트롤을 눌러 Worktree 를 끄고, 입력창 위에 브랜치 이름이 보이는 예전 배치에서는 그 옆의 worktree 체크박스를 해제합니다. 저장된 환경(saved environment)에서 세션을 시작한다면 그 환경을 편집하는 화면에 Worktree 설정이 따로 있으니 거기서 끕니다.

Worktree를 계속 쓰고 싶다면 Git을 설치합니다. Mac은 터미널에서 git --version을 실행해 버전 번호가 나오면 이미 설치된 것이고, 없으면 xcode-select --install로 명령줄 도구(Command Line Tools)를 설치하거나 git-scm.com에서 받습니다. Windows는 Git for Windows 다운로드 페이지에서 설치하면 되고, Git Bash는 Git for Windows에 함께 들어 있으므로 따로 설치할 프로그램이 아닙니다.

데스크톱 앱 버전 확인과 업데이트: Windows는 1.49585.0이 기준

Windows에서는 버전 번호 하나로 첫 번째 상황인지 아닌지가 갈립니다. Claude Code 데스크톱 문서의 버전 확인 항목에 나오는 메뉴 이름(영어 화면 기준)으로 다음 순서대로 확인합니다.

1. Mac은 메뉴 막대의 Claude → About Claude 를, Windows는 Help → About Claude 를 엽니다. 번호를 누르면 클립보드에 복사됩니다.
2. Windows라면 번호를 1.49585.0과 비교합니다. 2.x나 3.x는 새 버전입니다. 문서가 2.37337.0, 3.1623.0 같은 이후 버전을 언급하기 때문입니다. 1.x라면 두 번째 자리를 숫자로 비교해 49585 이상이면 새 버전이고(예: 2026년 9월에 나온 1.52386), 작으면 예전 버전입니다. 1.24012.9는 24012가, 1.5354.0은 5354가 49585보다 작으므로 둘 다 예전 버전입니다. Mac에는 문서에 나온 기준 번호가 없으므로, 아래 Mac 절차의 예전 문구나 macOS 26 사례에 해당하면 최신 버전으로 올린다고 보면 됩니다.
3. 업데이트가 필요하면 Mac은 Claude → Check for Updates… 를, Windows는 Help → Check for Updates… 를 실행하고, 업데이트가 끝나면 새 세션을 시작합니다.
4. 메뉴에 Check for Updates…가 보이지 않으면 조직에서 자동 업데이트를 꺼 둔 것이므로 관리자에게 최신 버전 배포를 요청합니다.

이때 보는 것은 데스크톱 앱 자체의 번호입니다. 세션 안의 /status나 터미널 claude가 보여 주는 Claude Code 버전(예: 2.1.286)은 앱이 따로 내려받는 구성 요소의 번호라서 기준이 되지 않습니다. 1.49585.0의 배포일은 공식 문서에 없고, GitHub 이슈에서 Windows 사용자들이 2026년 9월 9~10일에 이미 1.49585를 쓰고 있었던 것으로 보아 9월 초쯤 나온 것으로 추정됩니다. 업데이트한 뒤 Worktree를 끈 세션에서도 계속 뜬다면 세 번째 상황으로 넘어갑니다.

Windows: Git을 설치했는데도 계속 뜰 때

Git이 깔려 있는데도 대화 상자가 계속 뜨는 Windows 사례는 대부분 앱이 bash.exe를 찾지 못했거나, 고친 설정을 앱이 아직 읽지 않은 경우입니다. 아래 순서는 Windows에서 직접 실행해 본 것이 아니라 Claude Code 설치 문서와 GitHub 이슈 #72976 등의 사용자 보고를 정리한 것입니다.

1. bash.exe 위치를 확인합니다. 기본 설치라면 C:\Program Files\Git\bin\bash.exe입니다. 예전 대화 상자는 "your git executable"이라고 적었지만 설치 문서가 요구하는 값은 git.exe가 아니라 이 bash.exe의 전체 경로입니다. Git 폴더 안에는 usr\bin\bash.exe도 있는데, 외장 드라이브의 포터블 Git 사용자가 이 경로를 지정했을 때는 재부팅 후에도 대화 상자가 남았고 Git\bin\bash.exe로 바꾸자 사라졌다고 보고했습니다(이슈 #72976, 2026년 8월 18일).

2. 사용자 환경 변수를 만듭니다. Win + R로 sysdm.cpl을 열고 고급 탭 → 환경 변수에서 사용자 변수를 새로 만듭니다. 이름은 CLAUDE_CODE_GIT_BASH_PATH, 값은 1단계의 경로를 따옴표 없이 넣습니다. PowerShell 한 줄로 만들 수도 있습니다.

   powershell복사

   [Environment]::SetEnvironmentVariable("CLAUDE_CODE_GIT_BASH_PATH", "C:\Program Files\Git\bin\bash.exe", "User")

   마지막 "User"는 그대로 둡니다. 변수 이름의 대소문자는 상관없지만, 일부 YouTube 영상 설명처럼 GIT을 GET으로 쓴 CLAUDE_CODE_GET_BASH_PATH는 다른 이름이라 앱이 읽지 않습니다.

3. 앱을 완전히 종료합니다. 창의 ×를 눌러도 Claude는 작업 표시줄 오른쪽 아래 트레이에 남아 있고, 환경 변수는 앱 프로세스가 시작될 때만 읽힙니다. 트레이의 ^를 열어 Claude 아이콘을 오른쪽 클릭한 뒤 Quit을 고르거나, 확실하게 하려면 PC를 다시 시작합니다. Mac에서는 Cmd + Q로 종료하는 것이 같은 단계입니다.

4. 앱을 다시 열고 새 세션을 시작합니다.

5. 그래도 뜨면 로그를 봅니다. 사용자 보고에 따르면 로그는 %LOCALAPPDATA%\Claude\logs\main.log에 있지만, Microsoft Store(MSIX)로 설치했다면 위치가 다를 수 있습니다. 앱 버전과 이 로그를 GitHub 이슈에 함께 올리면 원인을 좁히는 데 쓰입니다.

이 순서는 최신 앱에서 Git 감지만 어긋난 경우를 위한 것입니다. 1.49585.0 이전 앱에서는 시스템 변수로 D:\Git\bin\bash.exe를 지정하고, 앱의 로컬 환경 업데이트 대화 상자를 쓰고, 설정 파일에 gitBashPath 키까지 넣었는데도 막혔다는 보고(이슈 #83178)가 있고, 관련 이슈는 모두 #72976으로 합쳐졌습니다. gitBashPath는 문서에 없는 키라서 넣어도 의미가 없습니다. #72976 작성자는 2026년 8월 28일 다시 로그인한 뒤 대화 상자가 사라졌다고 남겼지만 원인은 밝혀지지 않았으므로, 예전 버전이라면 설정을 더 만지기보다 업데이트하는 편이 확실합니다. Windows on ARM에서 ARM64용과 x64용 Git을 번갈아 설치해도 예전 앱에서는 풀리지 않았다는 보고(이슈 #73461)도 같은 경우입니다.

CLAUDE_CODE_GIT_BASH_PATH는 Windows 환경 변수에 넣습니다

데스크톱 앱의 대화 상자를 넘기려는 목적이라면 ~/.claude/settings.json보다 Windows 사용자 환경 변수가 먼저입니다. Claude Code 데스크톱 문서의 로컬 세션 환경 항목에 따르면 Windows 앱은 사용자·시스템 환경 변수를 물려받지만 PowerShell 프로필은 읽지 않으므로, 프로필에 $env:로 넣은 값은 앱에 닿지 않습니다. 반면 settings.json의 env 키는 세션 안에서 실행되는 Claude Code가 읽는 곳이고, 세션을 시작하기 전에 도는 Git 확인이 이 파일을 읽는지는 문서에 나와 있지 않습니다. 실제로 settings.json과 Windows 시스템 변수에 모두 넣었는데도 대화 상자가 사라지지 않았다는 보고(이슈 #72976)가 있습니다.

settings.json에 쓰는 것은 터미널 CLI나 세션 안에서 Git Bash를 못 찾을 때의 방법이며, 설치 문서의 형식은 다음과 같습니다. JSON 안에서는 백슬래시를 두 번씩 쓰고 따옴표가 문법의 일부입니다. Windows 환경 변수 값에 따옴표를 넣지 말라는 조언과 모순되지 않습니다. 같은 변수가 Windows 환경 변수에도 있으면 Claude Code는 settings.json의 값을 무시하고 환경에 있는 값을 씁니다.

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Mac: 명령줄 도구가 이미 설치됐다는데 계속 Git을 요구할 때

Mac에서 xcode-select --install이 이미 설치됐다고 답하는데도 대화 상자가 남는다면, Git은 있는데 앱이 실행에 실패하는 경우입니다. xcode-select --install은 설치 여부만 보고 라이선스 동의나 PATH 문제는 확인하지 않습니다. 아래 원인은 GitHub 이슈 #44297, #54754, #72588, #87762에 사용자들이 남긴 것입니다.

1. 앱 버전을 먼저 봅니다. macOS 26에서 1.32885.0 같은 예전 1.x 앱은 명령줄 도구 폴더에 xcrun이 없다는 이유로 정상인 Git을 거부했습니다(이슈 #87762). 이 경우는 업데이트로 해결되며, 같은 폴더 구성에서 최신 앱이 정상으로 열리는 것은 아래 확인 결과에 있습니다.
2. 터미널에서 git --version을 실행합니다. "You have not agreed to the Xcode license agreements"가 나오면 sudo xcodebuild -license로 라이선스에 동의합니다. macOS를 업그레이드한 뒤라면 Xcode를 한 번 열어 동의해야 하는 경우도 있습니다.
3. which -a git으로 첫 줄의 git을 확인합니다. Dock이나 Finder에서 연 앱은 ~/.zshrc 같은 셸 프로필에서 PATH를 가져오므로, PATH 앞쪽에 있는 빈 git 파일, ~/bin/git, git이라는 이름의 폴더가 진짜 Git보다 먼저 잡혀 실행이 실패(spawn EACCES)한 사례가 있습니다. Homebrew Git의 심볼릭 링크가 Cellar 폴더를 가리켜 같은 오류가 난 보고도 있습니다.
4. 로그에서 실제 원인을 찾습니다. grep 'error' ~/Library/Logs/Claude/main.log를 실행하면 Git command failed: git --version … 줄에 라이선스 미동의나 EACCES 같은 원인이 그대로 적혀 있습니다.
5. "Git is installed but isn't working"이 보이면 뒤의 안내를 읽습니다. 최신 앱은 이 문구 뒤에 원인을 덧붙이는데, Git 설정 파일을 읽을 권한이 없다는 안내라면 시스템 설정 → 개인정보 보호 및 보안 → 전체 디스크 접근 권한에서 Claude를 허용합니다.
6. 고친 뒤에는 Windows 절차 3단계와 같은 이유로 앱을 완전히 종료했다가 다시 엽니다.

2026년 10월 23일 Mac에서 확인한 결과: 최신 앱에는 예전 문구가 없음

2026년 10월 23일 Mac 한 대에서 확인한 결과, Claude 데스크톱 3.6556.2에서는 명령줄 도구만 깔린 macOS 26 환경에서도 로컬 세션이 정상으로 열렸고, 'Git is required for local sessions'라는 예전 문구는 앱에 아예 없었습니다. 환경은 macOS 26.1(25B78), Xcode 없이 명령줄 도구만 있는 상태이고, 명령줄 도구 폴더에는 usr/bin/git만 있고 usr/bin/xcrun은 없었습니다. 이슈 #87762에서 예전 앱이 Git을 거부한 바로 그 구성입니다. 정상일 때의 확인 출력은 다음과 같습니다.

$ git --version
git version 2.50.1 (Apple Git-155)
$ which -a git
/usr/bin/git
$ xcode-select -p
/Library/Developer/CommandLineTools

이 Mac에서 Code 탭 로컬 세션은 문제없이 돌았고, 2026년 10월 5일부터 10월 23일까지 남은 데스크톱 앱 로그(main.log~main4.log)에서 "Git is required"는 0건이었습니다. 앱 패키지 안의 문자열을 읽기 전용으로 검색해 보니 현재 Mac용 Git 안내는 "Git is required but was not found. Run xcode-select --install in Terminal…"과 "Git is installed but isn't working: …" 두 가지이고, 후자에는 전체 디스크 접근 권한을 주라는 안내가 붙습니다. 예전 문구 "Git is required for local sessions"와 "switch to a remote environment"는 0건이었으므로, Mac에서 이 문구가 보인다면 앱이 오래됐다고 판단할 근거가 됩니다.

확인 범위는 Mac 한 대, 앱 버전 하나, 계정 하나입니다. Git이 없는 Mac은 시험하지 않았고, Windows 앱은 실행하지도 패키지를 열어 보지도 않았습니다. 그래서 최신 Windows 앱이 Worktree 세션에서 띄우는 정확한 문구는 공개된 보고에서도 찾을 수 없고, 한국어 화면 문구도 '로컬 세션에는 Git이 필요합니다.'와 'Git 설치' 외에는 알려진 것이 없습니다.

재설치 반복을 멈출 때: 클라우드 세션·Remote Control·터미널 CLI

Windows 앱을 1.49585.0 이상(2.x·3.x 포함)으로, Mac 앱을 최신 버전으로 올리고 Worktree를 끈 뒤, Windows라면 bash.exe 경로를 지정하고 Mac이라면 라이선스와 PATH를 확인하고 나서 완전히 종료했다가 다시 열었는데도 같은 대화 상자가 뜬다면 Git 재설치를 반복하지 말고 다른 경로로 일을 계속합니다. 앱 버전, OS, main.log를 붙여 GitHub에 보고해 두고, 그동안은 클라우드 세션이나 터미널 CLI로 일을 이어 갈 수 있습니다.

로컬 Git 없이 바로 쓰고 싶다면 클라우드 세션이 있습니다. 클라우드 세션은 GitHub 저장소를 Anthropic의 가상 머신에 복제해 작업하므로 GitHub 계정 연결이 필요하고, 내 PC의 폴더 문제를 고쳐 주는 것은 아닙니다. 차이는 Claude Code 웹판이 있나요: 클라우드 Web, Remote Control, Desktop을 먼저 나눠야 합니다에 정리되어 있습니다.

내 PC의 파일과 도구가 꼭 필요하다면 터미널 CLI가 현실적입니다. Windows에서 터미널 CLI는 Git for Windows가 없어도 PowerShell로 명령을 실행하고, "Claude Code on Windows requires either Git for Windows (for bash) or PowerShell"은 둘 다 없을 때만 나옵니다. 설치는 Claude Code 설치 방법: 전 플랫폼 완벽 설정 가이드 (2026)를, 그 터미널 세션을 휴대폰이나 다른 기기에서 이어 조작하는 방법은 Claude Code Remote Control 완전 가이드: 모든 기기에서 코딩하기 (2026)를 보면 됩니다.

증상이 이 대화 상자가 아니라면 다른 문제입니다. 앱 자체가 열리지 않으면 클로드 데스크탑 실행 안됨: Windows·Mac 증상별 원인과 해결 순서를, 세션은 시작됐는데 곧바로 끊긴다면 Claude Code process exited with code 1 해결: 재설치 전에 분기부터 확인을 봅니다. "Git LFS is required by this repository but is not installed"가 뜨면 저장소가 Git LFS를 쓰는 것이므로 git-lfs.com에서 Git LFS를 설치하고 git lfs install을 실행한 뒤 앱을 다시 시작합니다.