nicedreamzapp/claude-code-local

Claude Code Local – Mac에서 Anthropic 스타일의 코딩 AI 실행하기

개요

• Claude Code가 기대하는 Anthropic Messages API와 동일한 인터페이스를 갖춘 소형 Python 서버이지만, MLX 런타임을 통해 Apple Silicon Mac에서 로컬 LLM을 실행합니다.
• 서버는 Gemma 4, Qwen 3.8, Llama-JSON과 같은 모델의 도구 호출 형식을 Claude Code가 이해할 수 있는 형식으로 변환하고, 프롬프트를 캐싱하며, 에디터로 응답을 스트리밍합니다.

사용 이유

• 클라우드나 API 키가 필요 없으며, 소스 파일이 기기 외부로 나가지 않아 개인정보 보호가 중요한 코딩 작업에 적합합니다.
• 16 GB MacBook부터 128 GB M 시리즈까지 확장 가능하며, RAM에 적합한 모델을 자동으로 선택합니다.
• Claude Code의 기본 클라우드 백엔드를 그대로 대체하므로 UI와 워크플로우가 완전히 동일하게 유지됩니다.

주요 구성 요소

구성 요소	역할
proxy/server.py	MLX 기반 추론 서버. Anthropic 호환 엔드포인트를 구현하고 스트리밍, 도구 호출 변환, 프롬프트 캐시 재사용을 처리합니다.
agent/agent.py	경량 'Native Engine'. 짧은 시스템 프롬프트를 사용하여 턴 간에 캐시를 유지하는 단일 파일 터미널 코딩 에이전트입니다.
bin/keepgoing*	이전 Claude Code 세션을 찾아 Claude 크레딧이 소진되었을 때 무료 클라우드 모델이나 다른 로컬 모델로 세션을 이어갈 수 있게 합니다.
install.sh, setup.sh, scripts/doctor.sh	Mac의 메모리를 감지하고 적절한 모델(Gemma 4 E4B, Hermes 4, Gemma 12/31B, Qwen 3.8 등)을 다운로드하며, MLX Python 환경을 설치하고 데스크톱 런처를 생성합니다.
launchers/	로컬 서버를 가리키는 Claude Code를 시작하는 더블 클릭 가능한 스크립트. Native Engine, 브라우저 구동 에이전트, 음성 모드, 전화 제어용 변형도 포함됩니다.

작동 방식 (개요)

에디터 (Claude Code) → http://localhost:4000 (본 저장소의 서버)로 HTTP 요청 →
MLX 런타임이 Apple GPU에서 선택된 모델 실행 → Claude Code로 응답 스트리밍

이 서버는 Claude Code의 API를 직접 사용하므로, 다른 많은 로컬 AI 설정에서 사용하는 느린 'OpenAI 스타일' 변환기를 피할 수 있습니다.

시작하기

1. 원라인 설치 프로그램을 실행합니다:

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

2. 스크립트가 RAM에 따라 모델을 선택 및 다운로드하고, 바탕 화면에 Claude Local.command 바로가기를 생성합니다.
3. 바로가기를 더블 클릭하여 평소처럼 Claude Code를 실행하면 AI 응답이 로컬에서 생성됩니다.

지원 모델 (자동 선택되지만 변경 가능):

• Qwen 3.8 27B – 96 GB 이상 Mac에 최적, 8-bit MLX 빌드.
• Gemma 4 31B – 64-95 GB Mac에서 빠름.
• Gemma 4 12B – 32-63 GB Mac에 적합.
• Hermes 4 14B – 16 GB Mac에서 작동.
• 커뮤니티 제공 빌드(Muse Glimmer, Nemotron 3 Nano Omni)도 참고용으로 나열되어 있습니다.

확장 설정

• 초고속 터미널 전용 코딩 어시스턴트를 위해 Native Engine 런처를 사용하세요.
• 작성자의 다른 저장소(Trinidad Head 터미널, 브라우저 에이전트, 음성 모드, 전화 제어)와 결합하여 완전한 '로컬 우선' AI 워크스테이션을 구축할 수 있습니다.
• 다른 로컬 서버를 선호하는 경우, README에 Ollama, claude-code-router, claude-code-proxy와 같은 대안이 기재되어 있습니다.

개인정보 보호 및 보안

• 모든 트래픽은 localhost로 제한됩니다. lsof를 통해 로컬 포트만 사용 중임을 확인할 수 있습니다.
• 이 프로젝트는 환경 플래그를 통해 Claude Code의 백그라운드 원격 측정 및 마켓플레이스 자동 설치를 비활성화합니다.
• keep-going 메뉴를 통해 의도적으로 무료 클라우드 모델을 선택하지 않는 한 외부 네트워크 호출이 발생하지 않습니다.

라이선스

• MIT – 자유롭게 수정, 재배포하거나 자신의 워크플로우에 서버를 포함할 수 있습니다.

결론 Claude Code Local은 Claude Code의 코딩 어시스턴트 경험을 유지하면서, MLX를 통해 Apple Silicon의 GPU를 활용하여 무거운 LLM 추론을 기기 내에서 실행합니다. 이는 Anthropic 스타일의 도구와 성장하는 오픈 소스 로컬 모델 생태계 사이의 실용적이고 개인정보를 우선시하는 가교 역할을 합니다.