chocks/locode

Alpha Software — 사용 시 주의 사항
Locode는 현재 활발히 개발 중이며, 운영 환경(production use)에서의 사용에 대해 검증되지 않았습니다. 인터페이스, 설정 형식 및 동작 방식은 릴리스 간에 예고 없이 변경될 수 있습니다. 본 소프트웨어는 어떠한 종류의 보증 없이 있는 그대로(as-is) 제공됩니다. 현 단계에서는 중요하거나 운영 중인 환경에서의 사용을 권장하지 않습니다.

Local-first AI 코딩 CLI (명령줄 인터페이스). 간단한 작업은 로컬 LLM (Ollama)으로, 복잡한 작업은 Claude로 라우팅(routing)합니다. 토큰을 절약할 수 있습니다.

⭐ 이 아이디어가 흥미롭다면, 저장소(repo)에 스타(star)를 눌러주세요. 큰 도움이 됩니다!

npm install -g @chocks-dev/locode
locode setup # Ollama 설치, 모델 선택, API 키 저장
locode # 채팅 시작

User CLI
│
▼
...

명령어	설명
locode	대화형 REPL (기본값)
locode run "<prompt>"	단발성 작업 실행
locode setup	첫 실행 위저드 (Ollama + 모델 + API 키)
locode install [model]	특정 Ollama 모델 다운로드 (pull)
locode update	locode를 최신 버전으로 업데이트
locode benchmark	라우팅 모드별 토큰 비용 비교
locode eval-local-models	도구 호출(tool-calling) 신뢰도에 따른 로컬 모델 비교
locode recommend-local-model	현재 머신에 가장 적합한 평가된 로컬 모델 선택

locode chat --claude-only # 로컬을 건너뛰고 모든 것을 Claude로 전송
locode chat --local-only # Claude를 건너뛰고 Ollama만 사용
locode chat --config ./custom.yaml # 사용자 정의 설정 파일 사용
...

ANTHROPIC_API_KEY가 설정되어 있지 않으면, locode는 자동으로 로컬 전용(local-only) 모드로 실행됩니다.

라우팅 규칙(routing rules), 모델 및 임계값(thresholds)을 설정하려면 locode.yaml을 편집하세요:

local_llm.model — Ollama 모델 (기본값: llama3.1:8b)
routing.rules — 작업을 로컬 또는 Claude로 라우팅하는 정규 표현식(regex) 패턴
routing.escalation_threshold — 이 값보다 신뢰도가 낮으면 Claude로 에스컬레이션(escalation)

REPL에서 stats를 입력하면 토큰 사용량과 예상 절감액을 확인할 수 있습니다.

현재 기본값: llama3.1:8b

는 보수적인 도구 호출 (tool-calling) 기준점입니다.
단일하게 권장되는 대체 모델은 없습니다. 사용자의 하드웨어에 적합한 모델들을 평가한 후, 본인의 결과에서 승자를 선택하십시오.

실제로 비교하고자 하는 모델들을 평가하는 것부터 시작하십시오:

locode eval-local-models \
--variant llama3.1:8b \
--variant gemma4:e4b \
...

머신이 지원할 수 있다면 더 큰 옵션들을 포함할 수 있습니다:

locode eval-local-models \
--variant llama3.1:8b \
--variant qwen2.5-coder:14b \
...

컨텍스트 (context) 또는 사고 모드 (thinking mode)를 조정하고 싶을 때는 구조화된 변형 (Structured variants)도 작동합니다:

locode eval-local-models \
--variant "label=llama-baseline,model=llama3.1:8b,num_ctx=8192" \
--variant "label=gemma-thinking,model=gemma4:27b,thinking=true,num_ctx=16384"

보고서는 기본적으로 .locode/evals/local-model-eval.json에 작성됩니다. 비교를 실행한 후, Locode에게 현재 머신에 가장 적합한 옵션을 추천하도록 요청하십시오:

locode recommend-local-model

다른 보고서 파일을 사용하려면:

locode recommend-local-model --report /path/to/local-model-eval.json

추천 명령어는 다음을 수행합니다:

• 플랫폼, CPU 개수 및 총 RAM 감지
• 머신의 메모리 예산을 초과할 가능성이 높은 모델 필터링
• 남은 모델들을 평가 신뢰도 (eval reliability) 순으로 먼저 순위를 매긴 후, 지연 시간 (latency) 및 토큰 비용 순으로 정렬

텔레메트리 (Telemetry)는 기본적으로 꺼져 있습니다. 참여하려면 셸 프로필 (shell profile)에 다음을 내보내기 (export) 하십시오:

export SENTRY_DSN="https://your-key@o123.ingest.sentry.io/456"

활성화 시: 처리되지 않은 예외 (unhandled exceptions)를 캡처하고 성능 트레이스 (performance traces)의 20%를 샘플링합니다.
절대 전송되지 않는 항목: 프롬프트 (prompts), API 키, 파일 내용. 비활성화하려면 SENTRY_DSN을 해제하십시오.

git clone https://github.com/chocks/locode && cd locode
npm install
npm run dev # ts-node로 실행
...

src/
cli/ # REPL, 설정 (setup), 설치 (install), 업데이트 (update), 벤치마크 (benchmark)
config/ # Zod 스키마 (schema) + YAML 로더 (loader)
...

엔드 투 엔드 테스트 (End-to-end tests)는 Ollama 및 Anthropic API를 모방하는 경량 HTTP 스텁 서버 (stub servers)를 대상으로 locode를 실행하여 전체 CLI 파이프라인을 검증합니다. 외부 서비스는 필요하지 않습니다.

사전 요구 사항 (Prerequisites): 프로젝트를 먼저 빌드하십시오 — E2E 테스트는 컴파일된 CLI를 실행합니다.

npm run build
npm run test:e2e

테스트 검증 항목:

• 단순 프롬프트 (예: grep)는 로컬 LLM으로 라우팅됩니다.

• 복잡한 프롬프트 (예: refactor)는 Claude로 라우팅됩니다.

• API 키가 누락되면 로컬 전용 폴백 (fallback)이 트리거됩니다.

• main 브랜치에서 포크 (Fork) 및 브랜치 생성 — 절대 직접 커밋하지 마십시오.

• TDD (테hd-Driven Development) — 실패하는 테스트를 먼저 작성한 다음, PR (Pull Request)을 열기 전에 npm test && npm run build를 실행하십시오.

• 하나의 PR에는 하나의 기능 또는 수정 사항만 포함하십시오.

릴리스는 태그 기반으로 이루어집니다 — CI (지속적 통합)는 v* 태그 푸시 시 npm에 게시합니다.

git checkout -b release/vX.Y.Z
npm run release:patch # package.json 버전 업그레이드
git add package.json package-lock.json
...