← 보드로 돌아가기

hang-in/tunaLlama

tunaLlama: using local llm on claude, codex

GitHub에서 열기 ↗
41
GitHub 스타
1
포크
Python
언어
MIT
라이선스
2026.07.04
최근 푸시
2026.06.16
별표한 날

AI 분석

설치 난이도: 보통
큐레이터 노트
tunaLlama는 Claude Code/Codex CLI 사용자가 로컬 LLM을 활용해 토큰 사용량을 줄이고자 할 때 유용한 도구입니다. 특히 한국어 작업을 자주 다루고, Ollama/LM Studio 환경을 이미 갖춘 사용자에게 적합합니다. 다만 아직 초기 단계이므로, 실험적 도입을 고려할 만합니다.

강점

  • Claude Code와 Codex CLI 모두 지원하며, MCP 기반으로 로컬 LLM에 코드 생성을 위임해 상위 모델 사용량을 줄일 수 있는 구조를 제공합니다.
  • 설치가 5분 이내로 간단하고, 에이전트에게 설치를 위임할 수도 있어 편리합니다.
  • 한국어 형태소 분석기(Kiwi)를 통합하여 한국어 작업에 특화되어 있습니다.
  • 검색 및 메모리 기능을 SQLite에 기록하고, context boost 효과(+0.58~+0.64)가 측정되었습니다.

약점

  • 아직 v0.5.x 단계로, organic dogfooding 측정과 외부 사용자 재현성 데이터가 수집 중입니다.
  • 로컬 LLM(Ollama/LM Studio/Ollama Cloud)에 의존하므로, 해당 환경이 없으면 사용할 수 없습니다.
  • MCP 도구 system prompt 비용(약 1.6k tokens)이 발생하며, 이는 의도된 trade-off입니다.
  • Codex CLI에서 subagent 자동 인식 및 SessionStart hook이 작동하지 않아 일부 기능이 제한됩니다.

주의사항

  • 사용 한도 절약 효과는 정량적으로 보장되지 않으며, 사용자 작업 유형에 따라 달라집니다.
  • state.md auto-extract에서 false positive가 발생할 수 있으므로, 의심되는 entry는 수동으로 정리해야 합니다.
  • Architect가 자동으로 도구를 호출하지 않을 수 있으므로, 첫 사용 시 명시적 호출을 권장합니다.
  • 검색 품질(R@5 < 0.8)이 낮을 수 있으며, auto_recall=always 사용 시 노이즈가 섞일 가능성이 있습니다.

시작 가이드

  • README와 INSTALL.md를 꼼꼼히 읽고, Python 3.11+ 및 Ollama/LM Studio 환경을 준비합니다.
  • 레포를 클론하고 `mise install` 또는 `pip install -e .`로 의존성을 설치합니다.
  • `tunallama init`과 `tunallama doctor`로 설정을 완료하고, Claude Code 또는 Codex CLI에 플러그인을 등록합니다.
  • 첫 호출로 간단한 코드 생성 위임을 테스트해보고, 필요시 docs/workflow.md와 docs/internals.md를 참고합니다.
  • 실제 워크플로우에 적용하기 전에 한계와 주의사항을 숙지하고, organic dogfooding metric을 수집하며 평가합니다.

README 한국어 번역

이 번역은 AI가 원문 README를 옮긴 것입니다. 원문이 항상 우선합니다.

tunaLlama

Claude Code / Codex CLI 쓰면서 토큰 빨리 닳는 사용자를 위한 위임 도구입니다.

무거운 코드 생성을 로컬 Ollama / LM Studio / Ollama Cloud 에 위임하고, 분해 / 검증만 Claude (또는 Codex) 가 같은 세션 안에서 수행합니다. **한 레포로 Claude Code 와 Codex CLI 둘 다 작동** (둘 다 .claude-plugin/marketplace.json 인식).

tunaLlama 는 프롬프트 시드나 AGENTS.md 템플릿이 아닙니다. 상위 모델 세션이 모든 문서와 긴 코드를 직접 끌어안는 대신, **긴 코드 생성을 로컬/저비용 LLM 에 위임하고 Architect 는 분해와 검증에 집중하도록 만드는 MCP 기반 delegation runtime** 입니다.

상태: v0.5.x usable dogfooding release (2026-05-11). Claude Code + Codex CLI 양쪽에서 MCP tool 호출은 검증됐지만, organic dogfooding 측정과 외부 사용자 재현성은 계속 수집 중입니다. 라이선스: MIT. English: README.en.md.

누가 쓰면 도움 될 가능성

  • Claude Code Pro/Max 정액제 사용자 (한도 관리 동기)
  • Codex CLI 사용자 (OpenAI 정액제 / API quota 관리)
  • Ollama 로컬 / Ollama Cloud / LM Studio 환경 있는 사용자
  • 한국어 작업 다루는 사용자 (Kiwi 형태소 토크나이저 통합)

실제 한도 절약 효과는 사용자의 작업 유형, 모델, provider latency, Architect 의 검증 방식에 따라 달라집니다. Anthropic / OpenAI 의 정액제 한도 계산식이 공개되어 있지 않으므로, tunaLlama 는 "정량 절감 보장" 이 아니라 **긴 생성 작업을 위임해 상위 모델 사용량을 줄일 수 있는 구조** 를 제공합니다. 실 가치 는 본인 dogfooding 으로 확인 권장.

기술적 요구사항

  • Python 3.11+
  • Ollama / LM Studio / Ollama Cloud 중 하나
  • Claude Code (MCP 플러그인 지원 버전) 또는 Codex CLI

어떻게 작동하는가

역할 모델 책임
Architect Claude / Codex (정액제) 분해 / 사양 / 검증 / 통합
Developer 로컬 LLM (Ollama / Cloud / LM Studio) 코드 생성 / 자체 리뷰 / 자체 수정
Reviewer Architect 같은 세션 최종 판정

전형적인 호출 흐름:

  1. 사용자가 작업 요청 (한국어 / 영어).
  2. Architect 가 작업 분해 - 짧으면 tunadevreview, 길면 spec 문서 작성 후
  1. 백엔드가 generate → review → fix 루프를 반복 (bounded delegation - 종료
  1. 검색의 진짜 가치: **mid-size 로컬 LLM 의 컨텍스트 한계를 architect 가
  1. Architect 가 결과 검증 후 사용자에게 반환.

tunadevreviewfromspec. 조건은 review pass 또는 max iter). 모든 호출은 SQLite 에 기록되고 한국어 형태소로 색인됩니다. 보완 (Opus + Sonnet subagent 패턴과 동일). Phase 7-2 합성 시드 기반 측정** 에서 context boost +0.58 ~ +0.64 관측. 실사용 효과 확정 수치는 아니며, organic dogfooding metric 은 별도 수집 중입니다.

자세한 워크플로우: docs/workflow.md. 내부 구조: docs/internals.md.

5분 설치

에이전트에게 한 줄로 위임 가능: Claude Code / Codex CLI 세션에서

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

→ 에이전트가 INSTALL.md 읽고 의존성 / .env / 플러그인

등록 / 검증까지 단계별 실행. 5분 안에 사용 가능.

수동 설치는 아래 단계:

1. Clone + 의존성 설치

git clone https://github.com/hang-in/tunaLlama
cd tunaLlama

# uv 권장 (mise.toml 에 정의됨)
mise install                   # python 3.11 + uv
mise run install               # editable + dev 의존성

# 또는 pip 직접
pip install -e.

2. 환경변수 (Ollama Cloud 쓸 경우)

cp.env.example.env
echo "OLLAMA_CLOUD_API_KEY=발급받은_키" >>.env

3. tunallama init / doctor

tunallama init                 # 대화식 - provider/모델 자동 발견
tunallama doctor               # Python / config / provider / DB / Kiwi 검사

doctor 통과 못 하면 Troubleshooting 참조.

4-A. Claude Code 사용자

플러그인으로 설치:

claude plugin marketplace add /path/to/tunaLlama
claude plugin install tunaLlama@tunallama-local

또는 ~/.claude/settings.json 의 mcpServers 에 직접 등록:

{
  "mcpServers": {
    "tunallama": {
      "command": "python",
      "args": ["-m", "plugin.mcp_server"],
      "cwd": "/path/to/tunaLlama"
    }
  }
}

4-B. Codex CLI 사용자

Codex CLI 가 .claude-plugin/marketplace.json 직접 읽음 (4개 인식 위치 중 하나로 명시 지원):

codex plugin marketplace add /path/to/tunaLlama
codex plugin install tunaLlama@tunallama-local

호환 상세: docs/specs/phase8codex.md.

첫 호출 해보기

설치 후 Claude Code / Codex 세션에서. Architect 가 자동 호출할 수 있지만, 첫 사용과 재현 가능한 워크플로우에서는 명시 호출 경로를 권장 합니다.

권장 호출 흐름 - 코드 생성 위임

사용자: "json 파싱하는 함수 작성해줘.
        먼저 tuna_load_memory 로 프로젝트 컨벤션 확인하고
        tuna_dev_review 로 위임해줘."

Architect:
1. tuna_load_memory()  ← 프로젝트 컨벤션 fetch
2. tuna_recall(query="json parsing")  ← 과거 비슷 작업 surface (옵션)
3. tuna_dev_review(requirements="...", language="python")
   → 로컬 LLM 이 generate → review → fix 루프 수행
4. Architect 가 결과 검증 후 사용자에게 반환

큰 작업 - spec 기반

사용자가 docs/specs/foo.md 에 작업 spec 작성 후:

사용자: "tuna_dev_review_from_spec 으로 docs/specs/foo.md 진행해줘"

→ 백엔드가 bounded generate → review → fix 루프 수행
→ 최종 코드 + iteration 로그 반환

메모리 검색

사용자: "tuna_recall 로 이 프로젝트의 BGE-M3 임베딩 사용 검색해줘"

→ 과거 5 개 호출 결과 surface

자세한 도구 list 13 개: docs/internals.md.

한계

v0.5.x usable dogfooding release. Claude Code + Codex CLI 양쪽에서 MCP tool 호출 검증, 단 organic dogfooding (실 일상 사용) 측정 자산은 수집 중입니다. 아래 한계는 카테고리별 정리:

1. 사용 한도 / 비용 관련

  • 사용 한도 절약은 체감 데이터. Anthropic / OpenAI 정액제 한도 계산식이
  • MCP 도구 system prompt 비용은 의도된 trade-off 입니다. 13 도구

비공개라 정량 측정 불가능. description + schema 가 매 conversation 의 system prompt 에 prepend 되며 추정치는 약 1.6k tokens. 이는 accidental context bloat 가 아니라, Architect 가 적절한 delegation 도구를 선택하기 위한 affordance 비용입니다. tunaLlama 는 이 비용을 제거하기보다 도구 수와 description 품질을 관리해 호출 적중률과 검증 품질을 유지하는 쪽을 선택합니다. 자세한 측정: docs/measurements/phase7-mcp-audit.md.

2. 측정 관련

  • 검색 측정값 (R@5, P@1 등) 은 합성 시드 기반. 실 사용자 워크플로우
  • organic dogfooding metric 수집 (v0.5.7+). 매 delegation 후 4 종
  • 테스트 커버리지 90% (CI 가 통과시키는 unit/plugin 507 tests +

검증은 별개 자리. 자세한 측정: docs/measurements/. (standalonetoyrate / conventionadherencerate / astexcessscore / syntacticallyvalid) 가 ~/.tunallama/metrics.db 에 적재. tunallama metrics show 로 조회. 비활성: TUNAORGANICMETRICS=0. 누적 baseline 까지 외부 사용자 재현성은 측정 진행 중입니다. integration/searchquality 마커 27 tests = 총 534 collected). 미커버 10% 의 대부분은 외부 서비스 의존 path (llm/ollama.py 62% / llm/lmstudio.py 58% - pytest -m integration 실행 시 추가 커버). token_count.py 34% 는 Phase 5-4 보류 모듈 (Anthropic API 미보유라 unit test 없음).

3. MCP / 클라이언트 호환성

  • Architect 호출 의존. tuna_* 도구는 Architect 가 작업 컨텍스트 보고
  • Subagent 자동 인식 미작동 (Codex 0.128.0 실측): `plugin/agents/
  • MCP resource auto-attach + SessionStart hook 미작동 (Codex):

호출하는 구조 - 도구 description 품질이 호출 적중률을 결정합니다. 첫 사용 과 재현 가능한 워크플로우에서는 명시 호출 권장. tuna-developer.toml 가 캐시되지만 Codex 의 spawnagent 가능 type 에 tuna-developer 등록 안 됨 (default / explorer / worker 만). Claude Code 측은 미실측. MCP tools 13 개는 양쪽 모두 정상 작동 - delegation 은 도구 레벨에서 가능. tunallama://memory/state resource 는 양 클라이언트 모두 세션 시작 시 attach 안 됨. v0.5.2 의 SessionStart hook (plugin/hooks/sessionstart.py) 은 Claude Code v0.5.5+ 에서만 작동 - Codex 는 미인식. 실제 권장 운영: Claude Code 는 hook 으로 state.md auto-prepend, Codex 는 사용자가 tunaloadmemory` 명시 호출.

4. 로컬 LLM / provider

  • 로컬 LLM 의존. Ollama / LM Studio / Ollama Cloud 중 하나 없으면 작동 X.

5. 검색 / 메모리 품질

  • 한국어 형태소 분석 = Kiwi 의존. Kiwi 가 못 처리하는 도메인 단어

(신조어, 전문용어) 검색 품질 영향 가능.

6. state.md auto-extract

  • state.md auto-extract false positive 위험. v0.5.1 에서 코드 블록

안 텍스트 skip + meaningful 토큰 검증으로 완화 - 단 100% 제거는 어려움. 의심 entry 발견 시 tunallama state clean (auto entry 삭제) 또는 직접 편집 (tunallama state path 로 경로 확인).

양 환경 동작 매트릭스 (v0.5.6 실측 - Claude Code 2.1.138 + Codex CLI 0.128.0)

항목 Claude Code Codex CLI
MCP tools 13 개 (도구 호출) ✓ ✓
DB 공유 (~/.tunallama/memory.db) ✓ ✓
state.md 공유 (~/.tunallama/projects/<hash>/state.md) ✓ ✓
tunaloadmemory / tuna_recall 명시 호출 ✓ ✓
Agents auto-discovery (tuna-developer) ✓ ✗
Skills auto-load (delegate-to-ollama) ✓ ?
Hooks 등록 (SessionStart / PreToolUse) ✓ ?
SessionStart hook 실 실행 + state.md auto-prepend ✓ (v0.5.5 schema fix + 실측) ✗
MCP resource auto-attach (tunallama://memory/state) ✗ ✗

권장 운영 모델

  • state.md auto-prepend 가 SessionStart hook 으로 작동 - architect 가 첫
  • 별도 명시 호출 불필요. 단 사용자가 state.md 의도적 수정 후 effect 빨리

Claude Code (v0.5.5+): turn 부터 conventions / decisions / constraints / anti-patterns 자동 인지. 보고 싶으면 새 세션 시작.

  • SessionStart hook 인식 안 됨 - architect 가 첫 turn 에 tunaloadmemory
  • DB 공유 / state.md 공유 / MCP tools 호출은 모두 작동.

Codex CLI 0.128.0: 명시 호출 또는 docs 직접 fetch.

왜 프롬프트 시드가 아닌가

tunaLlama 는 에이전트에게 더 많은 문서를 읽히는 방식으로 컨텍스트 한계를 해결하려 하지 않습니다. 대신 작업 단위를 작게 잘라 MCP 도구로 로컬/저비용 LLM 에 넘기고, 상위 Architect 모델은 짧은 spec, review 결과, 최종 diff 판단 에 집중합니다.

문서 기반 운영 규칙은 시간이 지나면 stale state, drift, lost-in-the-middle 문제를 만들 수 있습니다. tunaLlama 는 이를 피하기 위해 delegation call 을 SQLite 에 기록하고, 필요할 때 검색 / 리콜하는 실행 계층을 둡니다.

무엇이 아닌가

  • tunaFlow 의 멀티 에이전트 라운드테이블 아님.
  • OllamaClaude 포크 아님 (패턴 참고).
  • 단일 모델 데모 / 연구 노트북 아님.
  • 자동 weakness 감지 / 동적 tool 작성 아님 - Architect 판단으로

tunaloglimitation 호출.

측정 자료

검색 알고리즘 / context boost / MCP audit 측정 결과:

  • 전체 인덱스
  • methodology.md - 시드 / LOPO /
  • phase4-search.md - 검색 품질
  • phase5-hyde-kure.md - HyDE
  • phase5e-corpus-scaling.md -
  • phase7-mcp-audit.md - MCP
  • phase7-context-boost.md -

metric 정의 / 한계 / KURE / Adaptive (524 record) rerank pool sweep + 984 record LOPO (rerank P@1 0.77 / R@5 0.59 cloud 0) 도구 system prompt size mid-size LLM context boost +0.58~+0.64 (3 모델 검증)

합성 시드 기반이라 실 사용 데이터 검증은 별개 자리입니다.

Troubleshooting / FAQ

tunallama doctor 실패

Python 버전: 3.11+ 필요. python --version 확인.

provider 미감지: Ollama / LM Studio 가 실행 중인지 확인.

curl http://localhost:11434/api/tags  # Ollama
curl http://localhost:1234/v1/models  # LM Studio

Ollama Cloud 키 미감지: .env 파일이 cwd 에 있는지 + OLLAMACLOUDAPI_KEY=... 행이 첫 줄에 있는지 확인.

Kiwi 형태소 분석기 실패: pip install kiwipiepy 재설치. macOS 의 경우 Xcode CLI tools 필요 (xcode-select --install).

MCP 도구가 Claude/Codex 컨텍스트에서 안 보임 / 새 세션에서 server fail

증상: /plugin 화면에서 tunaLlama MCP Server Status: ✘ failed. 또는 도구 list 에 tuna_* 가 안 보임.

원인 1 - venv 의존성 미해결 (v0.5.8 이하): plugin 의 .mcp.json 이 command: "python" 으로 system python 을 spawn 함. mise / pyenv / direnv 같은 shell hook 은 Claude Code 의 child process 에서 활성 안 돼서 venv 의 fastmcp / anthropic SDK 등 deps 못 잡고 ImportError. **v0.5.9+ 부터 wrapper script (plugin/bin/tunallama-mcp) 가 .venv/bin/python 자동 fallback** - 업데이트 권장.

원인 2 - .mcp.json cwd 잘못된 경우: claude plugin install 한 위치 확인. 직접 등록한 경우 cwd 가 tunaLlama 레포 절대경로인지 확인.

원인 3 - Python venv 부재: .venv/bin/python 자체가 없으면 wrapper 도 system python 으로 fallback - deps 부재로 fail. mise run install 또는 uv venv && uv pip install -e. 로.venv 생성.

tuna_* 도구가 호출 안 됨

Architect 가 자동 호출하지 않음: SKILL.md 또는 tunallama://memory/state resource 미attach 가능. tunaloadmemory 명시 호출 시도.

도구 description 품질: 일부 task 가 너무 추상적이면 Architect 가 도구 선택 못 함. 명시적으로 "tunadevreview 사용해서 작성해줘" 같이 지시.

LLM 호출 timeout

기본 timeout 600 초 (tunallama_core/config/models.py). cloud LLM 응답 지연 시 retry 3 회. 그래도 실패하면 logger.warning 으로 기록됨 - dev 환경에서 stderr 확인.

자주 timeout 발생 시: 로컬 LLM 으로 swap 또는 모델 크기 줄이기 (qwen3-coder-next 등 latency 최적화 모델).

검색 품질이 낮은 것 같음

현재 측정 (cloud 0 path, 984 record LOPO / 792 query): rerank P@1 0.77 / R@5 0.59 / σR@5 0.31. HyDE+KURE path (24 leader sample, cloud 1): P@1 0.92 / σR@5 0.14. 자세히: phase5e-corpus-scaling.md.

R@5 < 0.8 의 의미: 자동 prepend (auto_recall=always) 시 noise 섞임 가능. 단 Phase 4-4 + 5-3 측정에서 cloud LLM 이 무관 prefix 자동 무시 - 실 코드 품질 영향 작음 검증.

default onrequest 유지 권장. autorecall=always 는 risk 인지하고 사용.

state.md auto-extract 의도치 않은 entry

원인: LLM 출력의 코드 블록 / 주석 / 일반 단어 가 false positive 로 auto-extract 됨 (v0.5.1 부터 코드 블록 안 텍스트 + meaningful 토큰 검증 필터 추가, 단 100% X).

CLI 명령 (v0.5.1+):

tunallama state show    # 내용 출력
tunallama state path    # 파일 경로 출력
tunallama state clean   # (auto) 태그 entry 삭제, manual/verified 보존

파일 위치: ~/.tunallama/projects/<hash>/state.md. 직접 편집도 가능.

(manual) 또는 (verif

원본 저장소: hang-in/tunaLlama

라이선스: MIT

게재 제외를 원하시면 삭제 요청을 보내주세요.