IntelliJ에서 Claude Code 쓰는 법 — JetBrains 유저를 위한 완전 가이드

Claude Code 관련 글이 대부분 VSCode 기준이라, IntelliJ 쓰는 사람 입장에서는 좀 답답했다. 나처럼 백엔드 Java/Kotlin 개발하면서 IntelliJ를 메인으로 쓰는 사람들 많을 텐데. 그래서 JetBrains IDE에서 Claude Code를 어떻게 세팅하고 쓰는지 정리해봤다.

결론부터 말하면, IntelliJ에서도 Claude Code 잘 된다. VSCode랑 거의 똑같은 경험을 준다. diff를 IDE 안에서 보고, 선택한 코드를 자동으로 공유하고, 에러까지 실시간으로 Claude한테 넘겨준다.

---

시작하기 전에 알아둘 것

Claude Code의 JetBrains 플러그인은 단독으로 동작하는 게 아니다. Claude Code CLI가 먼저 설치돼 있어야 하고, 플러그인은 그 위에서 IDE 통합 기능을 추가해주는 역할이다.

그러니까 순서가 이렇다:

1. Claude Code CLI 설치
2. JetBrains 플러그인 설치
3. 둘을 연결

이 구조를 모르면 "플러그인 깔았는데 왜 안 되지?" 하면서 헤맨다. 나도 처음에 플러그인만 깔고 한참 삽질했다.

지원하는 IDE

JetBrains 계열은 대부분 지원한다.

- IntelliJ IDEA
- PyCharm
- WebStorm
- PhpStorm
- GoLand
- Android Studio
- RubyMine, CLion 등 기타 JetBrains IDE

필요한 것

• Claude Code CLI
• Anthropic 유료 계정 (Pro $20/월 이상)
• JetBrains IDE (가급적 최신 버전)

---

Step 1: Claude Code CLI 설치

플러그인보다 CLI가 먼저다.

macOS / Linux

curl -fsSL https://cli.claude.ai/install.sh | sh

# 설치 확인
claude --version

npm으로 설치

npm install -g @anthropic-ai/claude-code
claude --version

Windows (WSL)

Claude Code는 Windows 네이티브를 지원하지 않아서 WSL에서 돌려야 한다. WSL 안에서 위의 설치 과정을 그대로 진행하면 된다.

첫 로그인

# 프로젝트 폴더에서
cd ~/my-project
claude

# 브라우저가 열리면서 Anthropic 로그인 → 인증 완료

여기까지 하면 터미널에서 Claude Code를 쓸 수 있다. 이제 IntelliJ와 연결할 차례.

---

Step 2: JetBrains 플러그인 설치

1. IntelliJ 실행
2. Settings (Cmd+, / Ctrl+Alt+S) 열기
3. Plugins 메뉴
4. Marketplace 탭에서 "Claude Code" 검색
5. Anthropic 공식 플러그인 [Install]
6. IDE 완전히 재시작

⚠️ 중요: 설치 후에는 IDE를 완전히 재시작해야 한다. 그냥 창만 새로고침하는 게 아니라 IntelliJ를 완전히 종료했다가 다시 켜자. 이거 안 하면 기능이 안 나타나는 경우가 많다. 안 되면 두 번 재시작해보라는 게 공식 문서 권고일 정도다.

💡 마켓플레이스에 "Claude Code" 검색하면 비슷한 이름의 서드파티 플러그인이 여러 개 나온다(Claude Code Plus, Claude Code with GUI 등). 공식 플러그인은 Anthropic이 배포한 것이니 vendor를 확인하고 설치하자.

---

Step 3: CLI와 IDE 연결

플러그인을 설치했으면 이제 연결해야 한다. 방법이 두 가지다.

방법 A: IDE 내장 터미널에서 실행 (가장 간단)

IntelliJ의 내장 터미널(Alt+F12 / View → Tool Windows → Terminal)을 열고 claude를 실행하면, 통합 기능이 자동으로 활성화된다.

# IntelliJ 내장 터미널에서
claude

이게 제일 간단하다. 내장 터미널에서 실행했으니 IDE랑 자동으로 연결된다.

방법 B: 외부 터미널에서 /ide 명령어

별도 터미널에서 Claude Code를 돌리고 있다면, /ide 명령어로 JetBrains IDE에 연결할 수 있다.

claude

/ide

💡 팁: Claude가 IDE와 같은 파일에 접근하게 하려면, IDE 프로젝트 루트와 같은 디렉토리에서 Claude Code를 실행해야 한다. 엉뚱한 디렉토리에서 실행하면 다른 파일을 보게 된다.

---

핵심 기능들

연결이 되면 VSCode 못지않은 통합 기능을 쓸 수 있다.

1. 빠른 실행 단축키

Cmd+Esc (Mac)
Ctrl+Esc (Windows/Linux)

에디터에서 바로 Claude Code를 열 수 있다. 또는 UI의 Claude Code 버튼을 클릭해도 된다.

2. IDE 안에서 diff 보기

Claude가 코드를 수정하면, 그 변경사항을 IntelliJ의 diff 뷰어에서 볼 수 있다. 터미널에서 텍스트로 보는 것보다 훨씬 편하다. IntelliJ의 diff 뷰어는 워낙 잘 만들어져 있어서, 변경 전후를 나란히 비교하면서 검토할 수 있다.

이 기능을 켜려면 설정에서:

1. claude 실행
2. /config 명령어 입력
3. diff tool을 "auto"로 설정 (IDE에서 diff 표시)
   - "terminal"로 하면 터미널에서 diff 표시

3. 선택 영역 컨텍스트 자동 공유

에디터에서 코드를 선택하거나 특정 탭을 열어두면, 그 내용이 자동으로 Claude한테 공유된다. "지금 보고 있는 이 코드 리팩토링해줘"라고 하면, Claude가 내가 선택한 코드를 알고 있다. 매번 코드를 복붙할 필요가 없다.

4. 파일 참조 단축키

Cmd+Option+K (Mac)
Alt+Ctrl+K (Windows/Linux)

이걸 누르면 파일 참조를 프롬프트에 삽입할 수 있다. 예를 들어 @src/auth.ts#L1-99 같은 형식으로 특정 파일의 특정 줄 범위를 정확히 가리킬 수 있다. 큰 파일에서 "이 부분만" 작업시킬 때 유용하다.

5. 진단 정보(에러) 자동 공유

IntelliJ가 잡아내는 lint 에러, 문법 에러 같은 진단 정보가 실시간으로 Claude한테 공유된다. 빨간 줄 쳐진 에러를 Claude가 알고 있으니까, "이 에러 고쳐줘"라고만 해도 어떤 에러인지 안다. 이게 은근 편하다.

---

플러그인 설정

Settings → Tools → Claude Code 에서 세부 설정을 만질 수 있다.

Claude 명령어 경로 지정

Claude를 실행하는 커스텀 명령어를 지정할 수 있다. CLI가 PATH에 안 잡히는 경우 직접 경로를 넣어주면 된다.

claude
/usr/local/bin/claude
npx @anthropic-ai/claude-code

WSL 사용자 설정

WSL에서 Claude Code를 쓴다면, 명령어를 이렇게 지정해야 한다:

wsl -d Ubuntu -- bash -lic "claude"

(Ubuntu는 본인의 WSL 배포판 이름으로 바꾸면 된다)

macOS에서 여러 줄 입력

기본적으로 Enter를 누르면 프롬프트가 전송된다. 여러 줄을 입력하고 싶으면 설정에서 Option+Enter로 줄바꿈하는 옵션을 켤 수 있다. (변경 후 터미널 재시작 필요)

---

ESC 키가 안 먹힐 때

JetBrains 터미널에서 ESC 키로 Claude Code 작업을 중단하려는데 안 되는 경우가 있다. 이건 IntelliJ의 기본 단축키 설정 때문이다.

해결 방법:

1. Settings → Tools → Terminal
2. 다음 중 하나:
   - "Move focus to the editor with Escape" 체크 해제
   - 또는 "Configure terminal keybindings"에서
     "Switch focus to Editor" 단축키 삭제
3. 변경사항 적용

이렇게 하면 ESC가 IntelliJ의 포커스 이동이 아니라 Claude Code 중단으로 제대로 동작한다.

---

원격 개발(Remote Development) 사용 시

JetBrains의 Remote Development 기능을 쓴다면 주의할 점이 있다. 플러그인을 로컬 클라이언트가 아니라 원격 호스트에 설치해야 한다.

Settings → Plugin (Host) 에서 플러그인 설치

로컬에 설치하면 안 된다. 원격 호스트에서 코드가 돌아가니까 플러그인도 거기 있어야 한다.

---

WSL에서 "No available IDEs detected" 에러

WSL2 + JetBrains 조합에서 흔히 겪는 문제다. claude 실행했더니 "사용 가능한 IDE를 찾을 수 없다"고 나오는 경우. 원인은 보통 WSL2의 NAT 네트워킹이나 Windows 방화벽이 WSL2와 IDE 간 연결을 막아서다.

해결법 1: 방화벽 규칙 추가 (권장)

# WSL 셸에서 IP 확인
hostname -I
# 예: 172.21.123.45 → 172.21.0.0/16 서브넷

# PowerShell 관리자 모드에서 (서브넷은 본인 것에 맞게)
New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16

그리고 IDE와 Claude Code를 재시작.

해결법 2: 미러 네트워킹으로 전환

Windows 11 22H2 이상이면 미러 네트워킹을 쓸 수 있다.

# Windows 사용자 디렉토리의 .wslconfig 파일에 추가
[wsl2]
networkingMode=mirrored

# PowerShell에서 WSL 재시작
wsl --shutdown

Windows 10이면 미러 네트워킹이 안 되니까 해결법 1(방화벽)을 쓰자.

---

자주 겪는 문제 정리

플러그인은 깔았는데 기능이 안 보임

1. 프로젝트 루트 디렉토리에서 Claude Code를 실행했는지 확인
2. IDE 설정에서 플러그인이 활성화돼 있는지 확인
3. IDE 완전히 재시작 (여러 번 해야 할 수도 있음)
4. Remote Development면 원격 호스트에 플러그인 설치했는지 확인

"command not found"

Claude 아이콘 눌렀는데 command not found가 뜨면:

# CLI 설치 확인
claude --version

# 안 나오면 PATH 문제
# 플러그인 설정에서 Claude 명령어 경로 직접 지정

IDE가 감지 안 됨

1. 플러그인 설치/활성화 확인
2. IDE 완전 재시작
3. 내장 터미널에서 Claude Code 실행했는지 확인
4. WSL이면 위의 WSL 설정 참고

---

보안 관련 주의사항

이건 한번 짚고 넘어가야 한다. Claude Code가 JetBrains IDE에서 자동 편집(auto-edit) 권한으로 돌아갈 때, IDE 설정 파일을 수정할 수 있다. 그리고 IDE 설정 파일 중에는 자동으로 실행되는 것들이 있어서, 이게 보안 위험이 될 수 있다.

그래서 JetBrains에서 Claude Code를 쓸 때는:

• 수동 승인(manual approval) 모드를 쓰는 걸 고려하자
• Claude를 신뢰할 수 있는 프롬프트로만 사용하자
• Claude가 어떤 파일을 수정할 수 있는지 항상 인지하자

편하다고 무작정 auto-edit + 전체 권한으로 놓고 쓰면, 의도치 않은 설정 변경이 일어날 수 있다. 특히 잘 모르는 코드베이스에서 작업할 때는 조심하자.

---

VSCode vs IntelliJ, 뭐가 더 나은가

둘 다 써본 입장에서:

기능적으로는 거의 동일
- diff 뷰어, 선택 컨텍스트, 진단 공유, 파일 참조 다 됨
- 같은 CLI를 쓰니까 코드 작업 품질은 똑같다

차이점
- IntelliJ: diff 뷰어가 더 강력하고 정교함. 
  리팩토링 검토할 때 IntelliJ 쪽이 보기 편함.
- VSCode: 확장 프로그램 생태계가 더 풍부. 가벼움.

결국 평소 쓰던 IDE를 그대로 쓰면 된다. Java/Kotlin 백엔드면 IntelliJ, 프론트엔드면 VSCode를 쓰는 게 자연스러운데, 어느 쪽이든 Claude Code 경험은 비슷하다. 굳이 Claude Code 때문에 IDE를 바꿀 필요는 없다.

---

마무리

IntelliJ에서 Claude Code 쓰는 과정을 정리하면:

1. Claude Code CLI 설치 (curl 또는 npm)
2. JetBrains 마켓플레이스에서 플러그인 설치 → IDE 완전 재시작
3. 내장 터미널에서 claude 실행 (또는 외부 터미널에서 /ide)
4. 프로젝트 루트에서 실행하는 거 잊지 말기

핵심 팁:

• 플러그인만으로는 안 된다. CLI가 먼저 깔려 있어야 한다
• 설치 후 IDE 완전 재시작 (안 되면 두 번)
• /config에서 diff tool을 auto로 하면 IDE diff 뷰어를 쓸 수 있다
• 코드 선택하면 자동 공유되고, 에러도 실시간 공유된다
• ESC 안 먹히면 터미널 키바인딩 설정을 확인하자
• WSL이면 방화벽/네트워킹 설정이 필요할 수 있다
• 보안상 JetBrains에서는 수동 승인 모드를 권장한다