claude-code-local

🧠⚡ Claude Code Local
Claude Code가 당신의 Mac에서 실행됩니다. 클라우드 없음. API 키 없음. 기다림 없음.
당신의 Mac 칩이 AI를 구동합니다 · Claude Code는 늘 하던 그대로 작동합니다 · 어떤 것도 당신의 컴퓨터를 떠나지 않습니다

이제 Linux와 Windows에서도 됩니다. 같은 Claude Code, 같은 프라이버시, 당신의 기계가 일을 합니다. 다음은 휴대폰입니다.

한 문장으로: 작은 Python 서버( proxy/server.py )가 Apple의 MLX로 당신의 Mac 칩에서 오픈 AI 모델을 실행하고, Anthropic 자체의 API 형식으로 Claude Code에 응답합니다. 그래서 Claude Code가 클라우드 모델도, API 키도 없이 작동합니다.

함께 제공되는 제가 만든 다른 것들은 local-first 패밀리 에 있습니다.

편집되지 않은 실제 세션. Claude Code가 파일을 읽고 편집하며, 응답하는 AI는 노트북에서 실행 중입니다.

Matt Macosko가 Claude Code 안에서 로컬 모델을 쓸 수 있게 만드는 접착제를 작성했습니다. 이 저장소의 구성 요소들:

⚡ proxy/server.py : MLX 서버. 스트리밍을 지원하는 Anthropic Messages API를 말하고, 각 모델 고유의 툴 호출 형식(Gemma 4, Qwen, Llama JSON)을 Claude Code 툴 호출로 변환하며, 깨진 툴 JSON을 복구하고, 턴 사이에 프롬프트 캐시를 재사용해 긴 세션이 모든 것을 다시 읽지 않게 합니다.
🧪 scripts/test_parse_tool_calls.py 와 scripts/test_mlx_server.py : 툴 호출 파서(모델 불필요)와 실행 중인 서버에 대한 다단계 툴 호출 테스트.
🏎️ agent/agent.py : Native Engine, 짧고 고정된 시스템 프롬프트를 가진 단일 파일 터미널 코딩 에이전트로, 매 턴마다 캐시가 살아남습니다. bench/agent_bench.py 가 그 캐시 수치를 재현합니다.
🔋 bin/keepgoing + bin/keepgoing.py : 이 폴더에서 마지막 Claude Code 대화를 찾아 무료 클라우드 또는 로컬 모델로 이어갑니다.
🚀 install.sh , setup.sh 그리고 scripts/doctor.sh : Mac을 점검하고, 메모리에 맞는 모델을 고르고, 모든 것을 설치하고, Desktop 런처를 만듭니다.
🩺 Doctor : 핵심(Claude Code, 모델 서버, 모델 파일, Python, llama.cpp)과 설치한 모든 애드온을 점검합니다. Mac 또는 Linux: bash scripts/doctor.sh . Windows: powershell -ExecutionPolicy Bypass -File scripts\doctor.ps1 . --fix / -Fix 를 추가하면 다운된 자신의 서비스를 재시작하거나 누락된 심볼릭 링크를 재생성합니다(아무것도 삭제하지 않음). --report / -Report 는 버그 리포트에 붙여넣을 프라이버시 안전 블록을 제공합니다.
🎮 launchers/ 와 공유 launchers/lib/claude-local-common.sh : 아래의 더블클릭 모드들.

업스트림, 제 것이 아님: Claude Code (Anthropic), MLX와 mlx-lm (Apple), 그리고 모델 자체(Google, Qwen, Nous Research 및 아래에 크레딧된 다른 이들 ). 문제를 고친 기여자들은 하단에 이름이 있습니다.

🛑 Claude 사용 한도에 도달했나요?
Claude Code가 방금 "you've reached your usage limit"라고 했고 리셋까지 몇 시간 남았나요? 계속 작업하세요:
같은 Claude Code, 같은 프로젝트, 하지만 응답하는 AI는 당신의 Mac에서 실행됩니다.

curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bash
그게 전부입니다. 16 GB MacBook 에서도 작동하며, Mac의 메모리가 많을수록 더 좋아집니다.

실행되면, local-first 패밀리가 키보드에서 손을 떼게 해줍니다: 당신의 브라우저, 당신의 목소리, 당신의 휴대폰, 모두 같은 기계 위에서.

🔋 Claude 크레딧이 떨어졌나요? 계속하세요.
Claude가 소진되면 Claude Code에서 exit 를 입력한 뒤 keep going 하세요. 짧은 메뉴가 나오고,
선택한 모델로 같은 대화가 이어집니다:

☁️ OpenRouter의 무료 클라우드 모델(무료 키 추가, 아래 참조)
💻 아래 라인업에서 당신의 Mac에 있는 모델, 메모리에 맞게 크기 조정

setup.sh 가 설치해 줍니다. 직접 추가하거나 무료 클라우드 모델을 켜려면:

echo ' source "$HOME/claude-code-local/scripts/keepgoing-shell.sh" ' >> ~ /.zshrc # the "keep going" command
mkdir -p ~ /.config/claude-code-local
echo ' OPENROUTER_API_KEY=your-free-key ' >> ~ /.config/claude-code-local/keepgoing.env # optional
모든 Claude 창 하단에 알림을 원하나요? 상태 줄을
scripts/statusline-keepgoing.sh 로 지정하세요. "💡 Out of Claude credits? Type exit, then keep going to
carry on with a free or local model."라고 표시됩니다.

자동으로도 가능합니다. Claude Code에 훅 하나를 추가하면, 사용 한도에 도달하는 순간
같은 폴더에서 새 창이 열리고 메뉴 없이 이어집니다. 무료 클라우드 모델 먼저,
그다음 당신의 Mac에 있는 모델. 설정과 한도는 Automatic keep going 에 있습니다.

💡 무료 클라우드 모델은 하루 늦게 붐빌 수 있습니다. 당신의 Mac에 있는 모델은 항상 있습니다.

🤔 이게 정말 뭔가요?
당신의 Mac에는 강력한 그래픽 칩이 내장되어 있습니다. 이 프로젝트는 그것을 사용해 큰 AI 모델을
당신의 컴퓨터에서 바로 실행하고 Claude Code에 연결합니다. 그래서 전체 코딩 경험이 오프라인으로 작동합니다:
파일 편집, 프로젝트 관리, 심지어 브라우저 구동이나 음성 대화까지.

비결: Claude Code는 한 언어(Anthropic의)를 말하고, 로컬 AI 서버는 보통
다른 언어(OpenAI의)를 말합니다. 대부분의 설정은 그 사이에 느린 번역기를 둡니다. 이 프로젝트의 서버는
Claude Code의 언어를 직접 말하므로, 중간에 아무것도 없습니다 , 그리고 그것이 빠르게 만드는 이유입니다.

📝 You ──▶ 🤖 Claude Code ──▶ ⚡ this server (on your Mac) ──▶ 🧠 local model ──▶ 🖥️ your Mac's chip

💻 필요한 것

🍎 Apple Silicon이 있는 Mac (M1 이상)
🐍 Python 3.12 (setup이 설치해 줍니다)
🤖 Claude Code : npm install -g @anthropic-ai/claude-code

설정은 Mac의 메모리를 보고 맞는 모델을 고릅니다:

Mac의 메모리
받는 모델

16 GB 미만 (8 GB)
🟡 Qwen 3.5 2B, 8-bit. 이미지 읽기, 16K 컨텍스트, 서버 피크 4.2 GB. 작은 Mac

16 GB (MacBook Air, 기본 모델)
🟡 Qwen 3.5 4B, bf16. 이미지 읽기, 16K 컨텍스트, 서버 피크 10.6 GB. 작은 Mac

32–63 GB (Pro)
🟢 Gemma 4 12B

64–95 GB (Max)
🟢 Gemma 4 31B

96 GB 이상 (Max, Ultra)
🟣 Qwen 3.8 27B, 8-bit. Claude Code 테스트(파일 작성, 실행, 보고)를 38초에 통과

💻 8 GB 또는 16 GB Mac인가요?
setup.sh 가 이를 감지하고 작은 Mac 티어를 설정합니다: 파일을 읽고, 편집하고,
명령을 실행하고 이미지를 보는 모델로, 컨텍스트는 Mac이 감당할 수 있는 만큼으로 제한됩니다.

당신의 Mac
모델
서버 메모리, 피크
속도 (M4 Pro)

16 GB
Qwen 3.5 4B, bf16
10.6 GB
22 tok/s

8 GB
Qwen 3.5 2B, 8-bit
4.2 GB
92 tok/s

둘 다 Claude Code 테스트(파일 읽기, Edit로 버그 수정, 스크립트 실행, 이미지 설명)를 통과했습니다. 요청은 한 번에 한 가지 명확한 단계로 유지하세요. 측정된 수치, 설정, 한도:
docs/SMALL-MACS.md . 실행 중인가요? #57 에서 어떻게 되는지 알려주세요.

🚀 시작하기
명령 하나:

curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bash
또는 스크립트를 먼저 읽어보세요:

git clone https://github.com/nicedreamzapp/claude-code-local
cd claude-code-local
bash setup.sh
설정이 모델을 고르고, 다운로드하고, 서버를 설치하고, Desktop에 Claude Local.command 를 둡니다. 더블클릭하면 로컬 코딩 중입니다. 🎉

🧰 전체 키트
로컬 모델이 두뇌입니다. 애드온은 귀, 목소리, 손, 도달 범위를 주며, 명령 하나로
모두 설치됩니다:

curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bash -s -- --with all

애드온
제공하는 것
Mac
Windows

voice
NarrateClaude : Claude Code와 대화하고 응답을 듣기
✅
✅

moonstone
Moonstone : 모든 기계의 모든 세션을 한 창에서, 푸시 투 토크
✅
✅

browser
browser-agent : 에이전트가 당신의 실제 로그인된 브라우저를 사용, 각자 자기 탭에서
✅
✅

phone
claude-screen-to-phone : iMessage로 iPhone에서 Claude Code 구동
✅

remote
FiaOS : 어떤 브라우저에서든 당신의 화면과 실제 터미널
✅
✅

failover
claude-failover : Claude 한도에 도달하면 백그라운드 에이전트가 로컬 모델로 계속 작업
✅

terminal
Trinidad Head : 창마다 색이 있는 빛나는 터미널

✅

각 조각은 자체 원라인 설치 프로그램과 제거 프로그램이 있는 자체 저장소이므로, 하나를 가져가고
나머지는 두어도 됩니다.

애드온 (macOS). 모델이 설정된 후 setup이 애드온 메뉴를 제공합니다. 각각 자체 저장소이며,
그 저장소의 자체 원라인 설치 프로그램으로 설치됩니다: voice ( NarrateClaude ),
browser ( browser-agent ), phone ( claude-screen-to-phone ),
remote ( FiaOS ), moonstone ( Moonstone )
그리고 failover ( claude-failover ). 메뉴 건너뛰기:

curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bash -s -- --with voice,browser,phone
curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bash -s -- --with all
bash ~ /claude-code-local/scripts/addons.sh menu # add more later
물어볼 터미널이 없고 --with 도 없으면, 애드온은 설치되지 않습니다.

제거: bash ~/claude-code-local/uninstall.sh (애드온도 제거하려면 --with phone,remote 또는 --all 추가, 데이터를 삭제하려면 --purge).

🐛 Claude 계정 로그인을 요구받나요? 당신의 claude 가 너무 오래되었습니다. 업데이트하세요:
npm install -g @anthropic-ai/claude-code

🛠️ 직접 하는 편이 좋나요?
# 1. Set up the MLX environment
python3.12 -m venv ~ /.local/mlx-server
~ /.local/mlx-server/bin/pip install mlx-lm

# 2. Pick a model and download it (one time)
bash scripts/download-and-import.sh gemma # or 'qwen', 'gemma12', 'hermes'

# 3. Start the server (MLX_SERVER points at the repo copy, since setup.sh didn't install one)
MLX_MODEL=divinetribe/gemma-4-31b-it-abliterated-4bit-mlx \
MLX_SERVER= " $PWD /proxy/server.py " \
bash scripts/start-mlx-server.sh

# 4. Launch Claude Code against it
ANTHROPIC_BASE_URL=http://localhost:4000 \
ANTHROPIC_API_KEY=sk-local \
claude --model claude-sonnet-4-6
setup.sh 는 서버를 이 저장소의 proxy/server.py 로 향하는 심볼릭 링크로 설치하므로, 편집하면
서버를 재시작하기만 하면 됩니다.

🐧🪟 Linux 또는 Windows PC에서
Apple Silicon의 MLX는 여전히 이 프로젝트의 심장이며 항상 그럴 것입니다. 우리가 매일 실행하는 것입니다.
우리는 아무도 소외되지 않도록 그것을 다른 모든 것으로 확장했습니다: 같은 Claude Code가, 당신의
기계에서, 이제 Linux와 Windows에서도 작동합니다. Mac이 아니면 MLX가 없으므로, AI는
대신 llama.cpp에서 실행되고, 설치 프로그램이 "다운로드하고 가기" 전체를 해줍니다: 하드웨어(NVIDIA, AMD, 또는 그냥 CPU)를 보고, 올바른 고정 llama.cpp 빌드를 가져오고, 메모리에 맞는 최고의 모델을
가능한 가장 높은 정밀도로 고르고, 다운로드하고, 그것을 향한 Claude Code를 실행합니다. 휴대폰이 다음 개척지이며, 작업 중입니다.

고를 수 있는 모든 모델은 이미지를 볼 수 있으므로 , Claude Code에 붙여넣는 스크린샷이
클라우드에서와 똑같이 작동합니다.

Linux (명령 하나):

curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bash
Windows (PowerShell):

irm https: // raw.githubusercontent.com / nicedreamzapp / claude - code - local / main / install.ps1 | iex
git , Python 3 , 그리고 Claude Code가 설치되어 있어야 합니다. 완료되면 claude-local 을 실행하거나
(Linux) Desktop의 Claude Local 을 더블클릭하세요 (Windows).

Windows에서 설치 프로그램은 그곳에서 실행되는 애드온을 제공하며, 각각 자체 저장소의
설치 프로그램으로 설치됩니다: moonstone ( Moonstone ), browser
( browser-broker ), remote
( FiaOS ), terminal
( Trinidad Head ) 그리고 voice
( NarrateClaude ). 메뉴를 건너뛰려면 원라이너 전에
$env:CCL_WITH = "all" (또는 "moonstone,terminal" , 또는 "none" )을 설정하세요. 제거
(애드온도 제거하려면 먼저 $env:CCL_WITH = "all" 설정; 모델과 사용자 데이터는
$env:CCL_PURGE = "1" 이 아니면 유지됨):
irm https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/uninstall.ps1 | iex

맞는 가장 강력한 비전 모델을 고르고 이유를 알려줍니다. 예를 들어:

당신의 하드웨어
받는 것

24 GB NVIDIA 카드
Qwen 3.5 9B 전체 BF16

12 GB NVIDIA 카드
Qwen 3.5 4B 전체 BF16

AMD 또는 Vulkan GPU
VRAM에 맞는 가장 큰 것

GPU 없음 (CPU만)
4B 또는 9B 비전 모델, RAM에 맞게 크기 조정

특정 모델을 원하나요? CCL_MODEL_ID=gemma-4-12b claude-local . 카탈로그는
portable/catalog.json 에 있습니다.

무엇에 의존하는가 (그리고 우리가 어떻게 대체할 것인가)
우리는 의도적으로 독립성을 유지합니다. 포터블 경로는 정확히 두 가지 외부 요소에 기댑니다:

llama.cpp (MIT 라이선스)가 모델을 실행합니다. 우리는 정확한 릴리스를 버전으로 고정하고
체크섬을 검증하므로, 업스트림 변경이 우리 밑에서 움직일 수 없습니다. 만약 그것이 사라진다면 우리는 이미
Mac 엔진( proxy/server.py )을 제공하고 있으며, 그…