Claude Code CLI가 CPU 100%를 점유할 때 — 원인과 해결법
발견
전날 작업 중 Claude Code가 갑자기 멈춰서 강제 종료한 적이 있었다. 그리고 다음 날 아침, 맥북이 평소보다 뜨거웠다. 활성 상태 보기(Activity Monitor)를 열어보니 Claude Code v2.1.27 프로세스가 **CPU 100%**를 점유하고 있었다.
경로: ~/.local/share/claude/versions/2.1.27
명령어: claude --continue
CPU: 99.5%
메모리: ~600MB
실행시간: 약 8시간이전에 Claude Code가 스킬(Skill)로 실행한 개발 서버 프로세스가 종료되지 않고 좀비처럼 남아서 CPU를 갉아먹고 있었다.
pkill claude로 시도했지만 죽지 않았고, kill -9 <PID>로 강제 종료해야 했다.
결국 세션 파일 정리 + claude install 2.1.22로 안정 버전에 다운그레이드해서 해결했다. 이후 CPU 점유 재발 없음.
원인
Claude Code CLI v2.1.27에서 보고된 알려진 버그다. GitHub에 동일 증상 이슈가 다수 등록되어 있다.
1. 세션 파일 비대화 (가장 유력)
~/.claude/projects/ 하위에 쌓이는 .jsonl 세션 파일이 커지면, 파싱 중 무한 CPU 루프에 진입한다.
claude --continue는 이전 세션 파일을 로드하기 때문에 이 문제에 직접적으로 영향받는다.
- v2.1.25에서는 정상 동작, v2.1.27에서 재현 확인
- 세션 파일 삭제 시 즉시 해결
참고: #22041 — CLI hangs at 99% CPU on startup with large session .jsonl files
2. Hooks + 병렬 인스턴스 충돌
v2.1.23 이후 hooks가 활성화된 상태에서 복수의 Claude Code 인스턴스를 실행하면 100% CPU hang이 발생한다.
참고: #22172 — v2.1.23+ causes 100% CPU hang with multiple parallel instances and hooks
3. Idle 상태 busy-wait
setImmediate() 호출이 yield 없이 반복 스케줄링되어, 아무 작업을 안 해도 CPU를 점유한다.
참고: #17148 — Claude Code consumes 100%+ CPU when idle in terminal
해결법
1단계: 좀비 프로세스 찾기
ps aux | grep claude | grep -v grep출력에서 claude 관련 프로세스와 PID를 확인한다.
2단계: 프로세스 종료
pkill claude는 이 좀비 프로세스에 먹히지 않는다. PID를 직접 지정해서 종료해야 한다.
# pkill은 안 됨
pkill claude # ← 무반응
# PID 직접 지정해서 강제 종료
kill -9 <PID>3단계: 비대해진 세션 파일 정리
# 세션 파일 크기 확인
du -sh ~/.claude/projects/*/
# 문제되는 세션 파일 삭제
rm ~/.claude/projects/<project-path>/*.jsonl세션 파일을 삭제하면 claude --continue로 이전 대화를 이어갈 수 없다. 필요하면 백업 후 삭제할 것.
4단계: 버전 다운그레이드 (hooks 사용자)
hooks를 사용 중이라면 이전 안정 버전으로 다운그레이드.
claude install 명령어로 특정 버전을 지정 설치할 수 있다.
# 특정 버전으로 다운그레이드 (v prefix 없이)
claude install 2.1.22
# 확인
claude --version주의:
claude install stable또는claude update실행 시 다시 최신 안정 버전으로 올라간다.
예방법
v2.1.23 이상을 사용할 경우:
| 방법 | 설명 |
|---|---|
| 세션 파일 주기적 정리 | ~/.claude/projects/ 하위 .jsonl 파일이 10MB 넘으면 정리 |
| 종료 확인 습관 | claude 종료 후 ps aux | grep claude로 프로세스가 실제로 죽었는지 확인 |
--continue 남발 금지 |
세션이 길어질수록 .jsonl이 비대해진다. 새 세션으로 시작하는 게 안전 |
| hooks + 병렬 실행 주의 | hooks 활성 상태에서 여러 인스턴스 동시 실행 금지 |
| 업데이트 추적 | anthropics/claude-code Issues에서 관련 fix 확인 |
/clear는 대화 컨텍스트만 초기화할 뿐,.jsonl파일 자체를 삭제하지는 않는다. 세션 파일 비대화 방지에는 직접적 효과가 없다.
관련 이슈 모음
- #22041 — CLI hangs at 99% CPU on startup with large session .jsonl files
- #22172 — v2.1.23+ causes 100% CPU hang with parallel instances and hooks
- #17148 — Claude Code consumes 100%+ CPU when idle in terminal
- #11122 — Multiple Claude CLI processes accumulate causing high CPU usage
- #11377 — Memory leak: 23GB RAM and 143% CPU after 14 hours
AI에게 바로 시키기
아래 상황에 맞는 프롬프트를 복사해서 AI(Claude, ChatGPT 등)에 붙여넣으면 알아서 진단하고 정리해준다.
Claude Code가 멈춰서 터미널만 종료했을 때
Claude Code를 사용하다가 멈춰서 터미널을 강제 종료했다.
백그라운드에 좀비 프로세스가 남아있을 수 있으니 확인하고 정리해줘.
1. `ps aux | grep claude | grep -v grep`으로 남아있는 프로세스 확인
2. 발견되면 `kill -9 <PID>`로 강제 종료 (pkill은 안 먹힘)
3. `du -sh ~/.claude/projects/*/`로 비대해진 세션 파일 확인 → 10MB 넘는 .jsonl 삭제
각 단계마다 실행 결과를 보여주고, 뭘 했는지 설명해줘.맥북이 평소보다 뜨거워졌을 때
맥북이 평소보다 뜨겁다. Claude Code 좀비 프로세스가 CPU를 점유하고 있을 수 있다.
진단하고 해결해줘.
1. `ps aux | grep claude | grep -v grep`으로 좀비 프로세스 확인
2. 발견되면 `kill -9 <PID>`로 강제 종료 (pkill은 안 먹힘)
3. `du -sh ~/.claude/projects/*/`로 비대해진 세션 파일 확인 → 10MB 넘는 .jsonl 삭제
4. hooks를 사용 중이면 `claude install 2.1.22`로 안정 버전 다운그레이드 검토
각 단계마다 실행 결과를 보여주고, 뭘 했는지 설명해줘.나는 claude install 2.1.22로 다운그레이드한 상태다. 같은 이슈가 수정된 버전이 나오면 그때 업데이트할 예정.