Show GN: Claude Code / Codex CLI의 무거운 코드 생성을 로컬 LLM으로 위임하는 tunaLlama 완벽 가이드

Claude Code / Codex CLI의 무거운 코드 생성을 로컬 LLM으로 위임하는 tunaLlama 완벽 가이드

바이브 코딩을 하다 보면 Claude Code나 Codex CLI의 정액제 사용 한도가 생각보다 빨리 닳는 경험을 해본 적이 있을 것이다. 특히 긴 코드 생성이 필요한 순간에는 토큰 소비가 급격하게 늘어나는데, 이런 무거운 작업을 로컬 LLM에 위임해서 비용을 절감할 수 있다면 얼마나 좋을까? 바로 이런 고민에서탄생한 도구가 바로 tunaLlama다.

tunaLlama란 무엇인가

tunaLlama은 Claude Code와 Codex CLI의 무거운 코드 생성 작업을 로컬 LLM에 위임하는 백엔드와 플러그인을 결합한 도구다. 핵심 아이디어는 역할별분공에 있다. 토큰을 가장 많이소비적 단계인 코드 생성, 파일 리뷰, 리팩터링은 결정적이라서 모델 품질의 차이가 크지 않으므로 비용이 저렴한 로컬 LLM으로 충분하다. 반면 요구사항을 작업 목록으로 분해하는 단계나 결과를 검증하는 단계는 짧지만 모델 품질 차이가 크므로 비싼 Claude나 Codex에 남겨두는 것이 효율적이다.

작동 흐름은 다음과 같다. 사용자가 작업을 요청하면 Architect 역할을 하는 상위 모델이 작업을 분해한다. 짧으면 바로 리뷰 도구를 호출하고, 길면 사양 문서를 작성한 후 백엔드가 코드 생성, 리뷰, 수정을 반복한다. 모든 호출은 SQLite에 기록되고 한국어 형태소 분석기인 Kiwi로 색인되어 나중에 검색할 수 있다.

설치 방법

tunaLlama의 가장 큰 장점 중 하나는 설치가 놀라울 정도로 간단하다는 것이다. Claude Code나 Codex CLI에서 다음 한 줄을 입력하면 설치가 완료된다.

https://github.com/hang-in/tunaLlama의 INSTALL.md 따라 설치해줘

에이전트가 알아서 의존성을 설치하고, 환경 설정을 구성하며, 플러그인 등록과 검증까지 단계별로 진행한다. 수동 설치를 선호한다면 GitHub 저장소의 README를 참고할 수 있다. 설치가 완료되면 Claude Code와 Codex CLI 양쪽에서 동일한 레포지토리를 사용할 수 있다.

13개 MCP 도구로 강력한 기능 제공

tunaLlama는 MCP 서버를 통해 13개의 도구를 제공한다. 이 도구들은 Claude Code나 Codex CLI가 필요할 때마다 자동으로 호출되며, 사용자가 매번 도구를 명시적으로 요청할 필요가 없다. 백엔드에서 generate, review, fix 루프를 반복하면서 bounded delegation 방식으로 종료 조건이 만족되면 자동으로 멈춘다.

모든 호출 내역은 SQLite에 영구적으로 기록되고, Kiwi 한국어 형태소 분석기를 통해 색인된다. 이를 통해 "이메일검증"처럼 띄어쓰기 없는 입력에 대해서도 "이메일"로 검색하면 매칭되는 등 자연스러운 한국어 검색이 가능하다. FTS5의 unicode61 토크나이저가 한국어를 음절이나 자모 단위로만 자르는 한계를 Kiwi가 보완하는 구조다.

성능 개선 데이터

tunaLlama 개발팀이 공개한 측정 결과에 따르면, mid-size 로컬 LLM 단독으로 돌렸을 때와 Architect가 컨텍스트를 적절히 정리해서 위임했을 때의 성능 차이가 눈에 띈다. 3개 모델로 검증한 결과, 컨텍스트를 잘 정리해서 넘기면 +0.58에서 +0.64까지 성능이 향상된 것으로 나타났다. 같은 로컬 LLM인데도 분해와 검증 단계를 상위 모델에 맡기고 코드 생성만 로컬로 처리하면 결과가 의미 있게 좋아진다는 뜻이다.

다만 이 측정값은 합성 시드 기반 테스트 셋에서 나온 것이므로, 실제 사용자 워크플로우에서 동일하게 나타나는지는 별도 문제라는 점은 유의해야 한다. v0.5.7 이상에서는 4종류의 dogfooding 메트릭스를 ~/.tunallama/metrics.db에 자동 적재하고 있어서, 누적 데이터를 통한 재현성 검증이 진행 중이다.

Claude Code와 Codex CLI 동작 매트릭스

tunaLlama는 하나의 레포지토리로 Claude Code와 Codex CLI 양쪽 모두에서 작동하지만, 일부 기능은 한쪽에서만 검증된 상태다. v0.5.6 기준 실측 결과는 다음과 같다.

MCP 13개 도구 호출은 양쪽 모두 정상 작동한다. 데이터베이스 공유, state.md 공유, memory 관련 도구의 명시적 호출 역시 양쪽 모두 지원된다. Agents auto-discovery와 SessionStart 훅에 의한 state.md 자동 사전 탑재는 Claude Code에서만 자동 작동하고, Codex CLI에서는 사용자가 첫 번째 턴에 tuna_load_memory를 명시적으로 호출하거나 문서를 직접 가져와야 한다.

중요한 점은 MCP 도구 13개 호출이 양쪽 모두 정상 작동하므로 delegation 자체는 도구 레벨에서 완전히 가능하다는 것이다.

한계와 트레이드오프

tunaLlama가 만능은 아니다. 몇 가지 한계를 인식하고 사용해야 한다.

첫째, Anthropic과 OpenAI의 한도 계산식이 비공개라 절감 효과를 "X% 절약"처럼 정량적으로 표현할 수 없다. 개발팀은 "그냥 쓰는 것보다는 낫다"라고 표현한다. 둘째, MCP 도구의 system prompt 비용이 의도된 트레이드오프다. 13개 도구의 description과 schema가 매 conversation system prompt에 약 1,600 토큰을 소비한다. 이는 accidental context bloat가 아니라 Architect가 적절한 delegation 도구를 선택하기 위한 비용으로 설계된 것이다.

셋째, 로컬 LLM 환경이 필수다. Ollama, Ollama Cloud, LM Studio 등 로컬 추론 서버가 없다면 작동하지 않는다. 넷째, 검색 측정값은 앞서 언급한 합성 시드 기반 테스트 결과이므로 현실 환경과 차이가 있을 수 있다. 마지막으로, Codex CLI에서는 일부 기능이 아직 완전히 지원되지 않는다.

한국어 개발자에게 특히 유용한 이유

tunaLlama의 차별점 중 하나는 한국어 지원이다. Kiwi 형태소 분석기가 통합되어 있어서 한국어 작업자를 위한 검색 인덱싱이 가능하다. 한국어 소프트웨어 개발 환경에서 일하는 분이라면 이 통합의 가치를 체감할 수 있을 것이다.

누구에게 도움이 되는가

tunaLlama가 특히 유용한 사용자는 네 가지 그룹이다. Claude Code Pro나 Max 정액제 사용자는 한도 관리 동기에서 분명 도움받을 것이다. Codex CLI 사용자와 이미 Ollama 로컬 환경이나 Ollama Cloud, LM Studio를 사용 중인 분에게도 적합하다. 한국어로 된 작업을 다루는 분이라면 Kiwi 통합의 이점을 누릴 수 있다.

테스트 및 라이선스

현재 v0.5.x 기준으로 507개의 unit/plugin 테스트와 27개의 integration/search_quality 테스트가 포함되어 있으며, 90% 이상의 테스트 커버리지를 확보하고 있다. 측정 명령어는 README에 명시되어 있으므로 직접 검증해볼 수 있다. 라이선스는 MIT이며, 영문 README도 동기화 유지되고 있다.

GitHub 저장소에서 공식 문서를 확인할 수 있고, 피드백과 이슈, 풀 리퀘스트 모두 환영한다. 다른 AI CLI 호환 제안도 받고 있으니 관심이 있다면 참여해보자.

Claude Code와 Codex CLI의 한도 관리에 어려움을 겪고 있다면, tunaLlama는검토할 가치 있는 도구다. 로컬 LLM의 비용 효율성과 클라우드 모델의 높은추리 능력을 상황에 맞게 활용할 수 있는 유연한 구조가 매력적이다.

---

📚 출처

• https://news.hada.io/topic?id=29554