claude-distill 0.2.0 → 0.4.0

package/README.md

@@ -12,6 +12,13 @@
 
 사용자가 하는 일: `claude-distill init` **한 번. 끝.**
 
+부담 없는 이유:
+- **별도 서버 / 계정 없음** — 본인 머신 → Anthropic API 직통. distill 운영자한테도 transcript 안 감
+- **의존성 0개, 50KB 미만** — [GitHub](https://github.com/parksubeom/claude-distill)에서 코드 그대로 검수
+- **세션당 비용 ~$0** — 4단 게이트로 본 추출 호출 ~10× 컷 (휴리스틱 → Haiku → dedup hash → 재귀 가드)
+- **Plain markdown 결과** — 마음에 안 드는 entry는 그 줄 삭제. UI / DB / 락인 없음
+- **한국어 / 영어 자동 누적** — transcript 언어 자동 감지, 별도 설정 불필요
+
 ---
 
 ## 어떤 게 자동으로 누적되나
@@ -90,9 +97,12 @@ source ~/.zshrc
 ```
 세션 끝
   └─ Stop hook이 `claude-distill analyze --quiet` 자동 실행
+     ├─ [재귀 가드] 자식 claude 세션이면 즉시 종료 (CLAUDE_DISTILL_CHILD)
+     ├─ [중복 방지] 같은 슬라이스 이미 분석됐으면 종료
+     ├─ [게이트 1 — 휴리스틱] 짧은 세션 / 도구 사용 0 / 에러 키워드 0 → 종료
+     ├─ [게이트 2 — Haiku] (API key 있을 때) yes/no 1토큰 응답, no면 종료
      ├─ 마지막 user marker 이후 turn slice (보통 ~120 turns / ~85K chars)
-     ├─ `claude --print`로 analyzer prompt 전달
-     ├─ JSON 응답 파싱
+     ├─ Sonnet/Opus로 analyzer prompt 전달, JSON 응답 파싱
      ├─ confidence:high entry → ~/.claude/knowledge.md / gotchas.md 즉시 append
      └─ medium / low → drop (사용자 손 안 가게)
 
@@ -101,6 +111,8 @@ source ~/.zshrc
      └─ Claude가 자연스럽게 참조 — 같은 함정 안 빠짐
 ```
 
+게이트 두 단계는 "대부분의 세션은 인사이트가 없다" 가정으로 본 추출 호출을 ~10× 줄입니다. 게이트가 차단된 세션은 dedup에 마킹돼 같은 슬라이스로 다시 호출돼도 즉시 종료.
+
 ---
 
 ## 카테고리
@@ -141,15 +153,48 @@ source ~/.zshrc
 - `--mock` — claude CLI 호출 없이 가짜 entry 1건 (파이프라인 검증용)
 - `--session=<file>` — 특정 jsonl 직접 지정
 - `--quiet` — 출력 억제 (hook이 사용)
+- `--no-gate` / `--force` — 휴리스틱/Haiku 게이트와 재귀 가드 모두 우회 (강제 분석)
+
+환경변수:
+- `ANTHROPIC_API_KEY` — 설정 시 Haiku 게이트 자동 활성 (~$0 가까이 게이트 비용)
+- `CLAUDE_DISTILL_GATE_MODEL` — 게이트 모델 (기본 `claude-haiku-4-5-20251001`)
+- `CLAUDE_DISTILL_MODEL` — 본 추출 모델 (기본 `claude-sonnet-4-6`)
+- `CLAUDE_DISTILL_LANG` — 누적 언어 강제 (`ko` / `en`). 미설정 시 transcript 한글 비율로 자동 감지
+- `CLAUDE_DISTILL_CHILD` — distill이 spawn한 자식 claude 표식. 수동 설정 불필요 (hook 무한 재귀 차단용 내부 플래그)
+
+---
+
+## 언어 (i18n) — 한국어 / 영어
+
+`knowledge.md` / `gotchas.md`는 한국어 또는 영어로 누적할 수 있습니다. 헤더 / 필드 라벨 (`상황` / `함정` / `근거` … vs `Context` / `Trap` / `Basis` …) 과 entry 본문이 모두 해당 언어로 작성됩니다. 카테고리 키 (`api_quirk`, `trade_off_decision` 등) 는 머신 식별자라 영어 enum 그대로 유지.
+
+**우선순위**:
+1. `claude-distill analyze --lang=ko|en` (명시)
+2. `CLAUDE_DISTILL_LANG=ko|en` 환경변수
+3. **transcript 자동 감지** — 세션 turn에서 한글 음절 비율이 5% 넘으면 `ko`, 아니면 `en`
+4. `process.env.LANG` (예: `ko_KR.UTF-8` → `ko`)
+5. fallback: `en`
+
+대부분의 사용자는 **3번 자동 감지로 충분** — 한국어로 코딩하는 세션은 한국어로, 영어 세션은 영어로 자연스럽게 누적됩니다. 별도 설정 없이.
+
+영어 위주로 쓰다 한국어 entry가 섞이는 게 싫다면 `~/.zshrc`에 `export CLAUDE_DISTILL_LANG=en` 으로 고정.
+
+> **혼재 주의**: 기존 markdown이 영어로 쌓여있을 때 locale을 `ko`로 바꾸면, 같은 파일에 영/한 entry가 섞입니다. plain markdown이라 사용자가 직접 정리 가능 (헤더 / 라벨 일괄 치환). v0.4 첫 cut은 단일 파일 정책 — 언어별 파일 분리 (`knowledge.ko.md`)는 추후 검토.
 
 ---
 
-## 프라이버시
+## 프라이버시 / 보안
+
+**별도 서버 없음.** distill은 본인 머신 → Anthropic API 직통입니다. 중간에 어떤 third-party 서버도 없음 — 코드도 50KB 미만, [GitHub](https://github.com/parksubeom/claude-distill)에서 그대로 검수 가능.
 
-- 모든 추출이 사용자 머신에서 진행. transcript는 사용자가 (또는 hook이) 호출할 때만 Claude API로 전달.
-- 결과는 plain markdown. git ignore 규칙 그대로 따름 (전역 파일이라 default ignore).
-- hook은 `~/.claude/settings.json`에서 직접 비활성화 가능.
-- 같은 transcript를 두 번 분석하지 않도록 `~/.claude/.distill/analyzed.json`에 sha hash만 저장.
+- **transcript 전송 범위**: 본인의 `ANTHROPIC_API_KEY`로 본인 계정의 Claude API에만 전달. distill 운영자(저)에게도 안 감.
+- **API key 저장**: distill은 key를 절대 파일에 안 씀. 본인이 `~/.zshrc` 등에 export한 환경변수만 읽음.
+- **권한 범위**: transcript는 read-only, 결과 markdown 2개만 append. 코드/repo는 절대 안 건드림.
+- **잔존물**: `~/.claude/.distill/analyzed.json`에는 transcript 내용이 아니라 SHA hash 12자만 저장 (중복 분석 방지용).
+- **결과는 plain markdown**: 마음에 안 드는 entry는 줄 째로 삭제. 다음 세션부터 inject 안 됨.
+- **완전 비활성화**: `~/.claude/settings.json`의 `hooks.Stop` 항목 삭제 또는 `npm uninstall -g claude-distill`.
+
+**시크릿 우려**: transcript에 API key / 패스워드를 평문으로 입력한 적 있다면 분석 prompt에도 그게 들어갑니다. Anthropic API의 데이터 처리 정책 그대로 따르며, distill 자체는 그걸 디스크에 저장하지 않음. 민감한 transcript가 있는 세션은 `claude-distill analyze` 실행 전 `~/.claude/projects/<project>/`에서 해당 jsonl을 직접 삭제하면 됩니다.
 
 ---
 
@@ -159,7 +204,10 @@ source ~/.zshrc
 A. 직접 작성 가능. `claude-distill`은 매일 쌓이는 자잘한 판례/사고를 자동으로 잡아내는 보조 도구. CLAUDE.md는 변하지 않는 보편 규칙용으로 그대로 쓰시면 됩니다.
 
 **Q. 토큰 비용은?**
-A. 세션당 1회 분석. 보통 prompt ~85K chars (~20K tokens) input, 응답 ~2K tokens output. Sonnet 기준 세션당 약 $0.10. 가벼운 세션은 더 적음.
+A. 게이트가 본 추출의 90% 가량을 사전에 컷합니다 (v0.3+). 통과한 세션만 prompt ~85K chars (~20K tokens) input + 응답 ~2K tokens output → Sonnet 기준 세션당 약 $0.10. 그 외 세션은 휴리스틱(무료) / Haiku 게이트(1토큰 응답, 사실상 0원)에서 종료. `ANTHROPIC_API_KEY` 설정 시 Haiku 게이트가 켜져 비용 효율이 가장 좋음.
+
+**Q. 게이트 때문에 인사이트를 놓치는 거 아닌가?**
+A. 휴리스틱이 보수적이라 false negative 가능 (예: 도구 사용 0인 토론 세션). 그런 세션은 `claude-distill analyze --no-gate`로 강제 분석 가능. 게이트가 차단하는 패턴이 본인 워크플로와 안 맞으면 README의 [issue tracker](https://github.com/parksubeom/claude-distill/issues)에 알려주세요.
 
 **Q. confidence:medium / low는 왜 drop?**
 A. 노이즈 누적이 가장 큰 실패 패턴이라 보수적으로 시작. 향후 `--keep-medium` 옵션 추가 가능.
@@ -173,11 +221,25 @@ A. **됩니다.** transcript는 익스텐션도 같은 위치(`~/.claude/project
 **Q. 다른 LLM 백엔드?**
 A. 현재 `claude` CLI + Anthropic API 두 가지. `--backend=cli|api|auto` 옵션. 기본 `auto`는 `ANTHROPIC_API_KEY` 있으면 API 우선, 없으면 CLI fallback. OpenAI / 로컬 LLM 지원은 v0.3+.
 
+**Q. 잠시 멈추거나 완전히 제거하려면?**
+A. 일시 정지: `~/.claude/settings.json`의 `hooks.Stop` 배열에서 distill entry만 빼면 됨. 완전 제거: `npm uninstall -g claude-distill` 후 `~/.claude/CLAUDE.md` 끝의 `<!-- claude-distill auto-references -->` 블록 삭제. 누적된 `knowledge.md` / `gotchas.md`는 유지하고 싶으면 그대로 두거나, 완전 초기화하려면 삭제.
+
+**Q. 잘못 누적된 entry는 어떻게 지워?**
+A. `~/.claude/knowledge.md` 또는 `gotchas.md`에서 그 entry의 `### ...` 블록만 텍스트로 삭제. 다음 세션부터 inject 안 됨. plain markdown이라 자유 편집.
+
+**Q. 회사 코드 / 시크릿이 transcript에 있어도 괜찮나?**
+A. 분석은 본인의 Anthropic 계정으로만 흘러가지만 (별도 서버 없음 — 위 보안 섹션 참조), API 호출 자체가 회사 정책에 막혀있다면 distill도 못 씀. 의심되는 세션은 `~/.claude/projects/<project>/<session>.jsonl`을 직접 삭제하거나, 해당 세션은 `claude-distill analyze`가 실행되기 전에 hook을 잠시 끄면 됨.
+
+**Q. 어떤 OS에서 됨?**
+A. macOS / Linux / Windows (Node 18+ 설치돼있으면). 경로는 전부 `os.homedir()`로 동적 결정 — 하드코딩 없음. 테스트는 macOS 위주지만 OS-specific 코드는 없음.
+
 ---
 
 ## 상태
 
-v0.2 — 자동 누적 모델로 재정비. 실 사용 결과 알려주시면 prompt 튜닝 / 카테고리 조정 진행합니다.
+v0.4 — i18n. `knowledge.md` / `gotchas.md`를 한국어 / 영어로 자동 누적 (transcript 언어 감지 또는 `CLAUDE_DISTILL_LANG`).
+v0.3 — 게이트 도입 (휴리스틱 + Haiku) + Stop 훅 무한 재귀 가드. 본 추출 호출 ~10× 감소.
+v0.2 — 자동 누적 모델로 재정비.
 
 ## License
 

package/bin/distill.js

@@ -21,7 +21,12 @@ const help = `claude-distill — Knowledge + Gotchas auto-accumulator for Claude
   claude-distill where      모든 파일 경로 / 존재 여부
 
 수동 분석 (보통 Hook이 자동으로 함):
-  claude-distill analyze [--no-auto] [--mock] [--quiet]
+  claude-distill analyze [--no-auto] [--mock] [--quiet] [--lang=ko|en]
+
+언어 (knowledge.md / gotchas.md 누적 언어):
+  --lang=ko|en              명시 (가장 우선)
+  CLAUDE_DISTILL_LANG=...   환경변수
+  (없으면) transcript 한글 비율로 자동 감지 → process.env.LANG → 'en'
 
 결과는 plain markdown:
   ~/.claude/knowledge.md    판례 (전역)

package/lib/analyze.js

@@ -21,6 +21,11 @@ const crypto = require('crypto');
 const cfg = require('./config');
 const transcript = require('./transcript');
 const store = require('./store');
+const gate = require('./gate');
+const localeMod = require('./locale');
+
+// 자식 claude 프로세스 표식. distill→claude→Stop 훅→distill 무한 재귀 차단용.
+const CHILD_ENV_KEY = 'CLAUDE_DISTILL_CHILD';
 
 function parseFlags(args) {
   const flags = {
@@ -30,6 +35,8 @@ function parseFlags(args) {
     mock: false,
     auto: true,        // 기본값 — 자동 누적 (CLI 핵심)
     backend: 'auto',   // 'auto' | 'cli' | 'api' — auto는 ANTHROPIC_API_KEY 있으면 api, 없으면 cli
+    noGate: false,     // 게이트 우회 (디버깅 / 강제 분석)
+    lang: null,        // 'ko' | 'en' | null — null이면 env / transcript 자동 감지
   };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -37,10 +44,13 @@ function parseFlags(args) {
     else if (a === '--dry-run') flags.dryRun = true;
     else if (a === '--mock') flags.mock = true;
     else if (a === '--no-auto') flags.auto = false;
+    else if (a === '--no-gate' || a === '--force') flags.noGate = true;
     else if (a.startsWith('--backend=')) flags.backend = a.slice('--backend='.length);
     else if (a === '--backend') flags.backend = args[++i];
     else if (a.startsWith('--session=')) flags.session = a.slice('--session='.length);
     else if (a === '--session') flags.session = args[++i];
+    else if (a.startsWith('--lang=')) flags.lang = a.slice('--lang='.length);
+    else if (a === '--lang') flags.lang = args[++i];
   }
   return flags;
 }
@@ -56,10 +66,11 @@ function existingForDedup() {
   return out;
 }
 
-function buildAnalyzerPrompt(promptText, existing, t) {
+function buildAnalyzerPrompt(promptText, existing, t, locale) {
   const exBlock = `<existing>\n# knowledge.md\n${existing.knowledge}\n\n# gotchas.md\n${existing.gotchas}\n</existing>`;
   const txBlock = `<transcript file="${t.source}" total_lines="${t.totalLines}" slice_from="${t.sliceFrom}">\n${JSON.stringify(t.turns, null, 2)}\n</transcript>`;
-  return `${promptText}\n\n---\n\n${exBlock}\n\n${txBlock}\n\nReturn the JSON array now. No prose, no markdown fences.`;
+  const langDirective = localeMod.promptDirective(locale);
+  return `${promptText}\n\n---\n\n${exBlock}\n\n${txBlock}${langDirective}\n\nReturn the JSON array now. No prose, no markdown fences.`;
 }
 
 function mockExtract() {
@@ -83,6 +94,9 @@ function callClaudeCli(promptText) {
       timeout: 120000,
       maxBuffer: 16 * 1024 * 1024,
       encoding: 'utf8',
+      // 자식 claude 세션이 끝나며 발사하는 Stop 훅이 또 distill을 부르는
+      // 무한 재귀를 차단. run() 시작부에서 이 env를 보고 즉시 종료.
+      env: { ...process.env, [CHILD_ENV_KEY]: '1' },
     });
   } catch (e) {
     if (e.code === 'ENOENT') {
@@ -182,6 +196,16 @@ function writeDedupLog(set) {
 
 async function run(args) {
   const flags = parseFlags(args);
+
+  // ── 재귀 가드 ──────────────────────────────────────────────
+  // distill이 spawn한 자식 claude 프로세스가 끝나면 Stop 훅이 또 발사돼
+  // distill을 부른다. 그 자식 세션은 분석 대상이 아니므로 즉시 종료.
+  // (--force는 가드도 무시 — 진짜 자식 세션 디버깅용 escape hatch)
+  if (process.env[CHILD_ENV_KEY] === '1' && !flags.noGate) {
+    if (!flags.quiet) console.log('child claude session — analyze 스킵 (재귀 방지)');
+    return;
+  }
+
   cfg.ensureStateDir();
 
   let file = flags.session || transcript.latestSessionFile();
@@ -208,6 +232,38 @@ async function run(args) {
     return;
   }
 
+  // Locale 결정 — transcript가 로드된 뒤(자동 감지에 필요). flag → env →
+  // transcript Hangul 비율 → process.env.LANG → 'en'.
+  const locale = localeMod.resolveLocale({ flag: flags.lang, transcript: t });
+  log(flags, 'locale: ' + locale + (flags.lang ? ' (--lang)' : process.env.CLAUDE_DISTILL_LANG ? ' (env)' : ' (auto)'));
+
+  // ── 게이트 1: 휴리스틱 (로컬, 무료) ───────────────────────
+  // 짧은 세션 / 도구 사용 0 / 에러 키워드 0 → 인사이트 후보 거의 없음.
+  // mock 모드와 --no-gate 는 우회.
+  if (!flags.mock && !flags.noGate) {
+    const h = gate.heuristicGate(t);
+    if (!h.pass) {
+      log(flags, 'heuristic 게이트 차단 (' + h.reason + ') — LLM 호출 스킵');
+      seen.add(dedupKey);
+      writeDedupLog(seen);
+      return;
+    }
+  }
+
+  // ── 게이트 2: Haiku LLM yes/no (API 백엔드 한정, 매우 저렴) ─
+  // ANTHROPIC_API_KEY 있을 때만 동작. CLI 백엔드는 Haiku 호출이 또
+  // 새 세션을 만들어 무의미하므로 스킵.
+  if (!flags.mock && !flags.noGate && process.env.ANTHROPIC_API_KEY) {
+    const g = await gate.llmGate(t, { apiKey: process.env.ANTHROPIC_API_KEY });
+    if (!g.pass) {
+      log(flags, 'haiku 게이트 차단 (' + g.reason + ') — LLM 호출 스킵');
+      seen.add(dedupKey);
+      writeDedupLog(seen);
+      return;
+    }
+    log(flags, 'haiku 게이트 통과 (' + g.reason + ')');
+  }
+
   // LLM 호출
   let candidates;
   if (flags.mock) {
@@ -215,7 +271,7 @@ async function run(args) {
   } else {
     const prompt = fs.readFileSync(cfg.PROMPT_FILE, 'utf8');
     const existing = existingForDedup();
-    const fullPrompt = buildAnalyzerPrompt(prompt, existing, t);
+    const fullPrompt = buildAnalyzerPrompt(prompt, existing, t, locale);
     if (flags.dryRun) {
       log(flags, '[--dry-run] prompt 준비됨 (' + fullPrompt.length + ' chars). LLM 호출 생략.');
       return;
@@ -253,7 +309,7 @@ async function run(args) {
         },
       };
       try {
-        const dest = store.appendEntry(annotated);
+        const dest = store.appendEntry(annotated, locale);
         appended++;
         log(flags, '  ✓ ' + (c.title || c.id) + ' → ' + dest);
       } catch (err) {

package/lib/gate.js

@@ -0,0 +1,110 @@
+// Two-stage gate that decides whether a transcript is worth analyzing.
+// Cuts main-LLM calls by ~10× — most sessions never reach extract.
+//
+//   1. heuristicGate(t)  — pure local checks (turn count, tool_use, error keywords)
+//   2. llmGate(t, opts)  — Haiku yes/no, only if API key available
+//
+// Both fail-open: if anything goes wrong they return pass:true so we don't
+// silently lose insights to a flaky filter.
+
+const ERROR_RE = /\b(error|failed|EACCES|EPERM|ENOENT|exception|cannot|undefined is not|null is not|panic:|fatal:|FATAL|throw |throws |traceback|stack trace|denied|forbidden|EADDRINUSE|EBUSY|timed out|timeout)\b/i;
+
+const MIN_TURNS = 8;
+
+function stringifyContent(c) {
+  if (typeof c === 'string') return c;
+  if (Array.isArray(c)) {
+    return c.map((x) => {
+      if (x.type === 'text') return x.text || '';
+      if (x.type === 'tool_use') return `[tool:${x.name}]`;
+      if (x.type === 'tool_result') return x.text_preview || '';
+      return `[${x.type}]`;
+    }).join(' ');
+  }
+  return '';
+}
+
+function heuristicGate(t) {
+  if (!t || !Array.isArray(t.turns) || t.turns.length < MIN_TURNS) {
+    return { pass: false, reason: `too_short(${t && t.turns ? t.turns.length : 0})` };
+  }
+
+  let toolUseCount = 0;
+  let textBlob = '';
+
+  for (const turn of t.turns) {
+    if (Array.isArray(turn.content)) {
+      for (const c of turn.content) {
+        if (c.type === 'tool_use') toolUseCount++;
+        if (c.type === 'tool_result' && typeof c.text_preview === 'string') textBlob += '\n' + c.text_preview;
+        if (c.type === 'text' && typeof c.text === 'string') textBlob += '\n' + c.text;
+      }
+    } else if (typeof turn.content === 'string') {
+      textBlob += '\n' + turn.content;
+    }
+  }
+
+  if (toolUseCount === 0) return { pass: false, reason: 'no_tool_use' };
+  if (!ERROR_RE.test(textBlob)) return { pass: false, reason: 'no_error_keywords' };
+
+  return { pass: true, reason: 'ok', toolUseCount };
+}
+
+function buildGateSample(t) {
+  const lines = [];
+  lines.push(`Total turns: ${t.turns.length}`);
+  const firstUser = t.turns.find((x) => x.type === 'user');
+  if (firstUser) {
+    lines.push(`First user request: ${stringifyContent(firstUser.content).slice(0, 500)}`);
+  }
+  const last = t.turns.slice(-5);
+  for (const x of last) {
+    lines.push('---');
+    lines.push(`[${x.type}] ${stringifyContent(x.content).slice(0, 400)}`);
+  }
+  return lines.join('\n');
+}
+
+// Haiku gate. Returns { pass, reason }. Fail-open on network/HTTP errors.
+async function llmGate(t, opts) {
+  const apiKey = (opts && opts.apiKey) || process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) return { pass: true, reason: 'no_api_key_skip_gate' };
+  const model = (opts && opts.model) || process.env.CLAUDE_DISTILL_GATE_MODEL || 'claude-haiku-4-5-20251001';
+
+  const sample = buildGateSample(t);
+  const prompt = [
+    'Below is the tail of a developer coding session with Claude Code.',
+    'Does it contain a non-trivial lesson, gotcha, judgment call, or insight worth recording for future sessions?',
+    'Skip routine work, simple Q&A, and trivial fixes.',
+    'Reply with exactly "yes" or "no" — nothing else.',
+    '',
+    sample,
+  ].join('\n');
+
+  let res;
+  try {
+    res = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: 4,
+        messages: [{ role: 'user', content: prompt }],
+      }),
+    });
+  } catch (e) {
+    return { pass: true, reason: 'gate_network_error' };
+  }
+  if (!res.ok) return { pass: true, reason: 'gate_http_' + res.status };
+  let data;
+  try { data = await res.json(); } catch { return { pass: true, reason: 'gate_bad_json' }; }
+  const block = (data.content || []).find((c) => c.type === 'text');
+  const text = ((block && block.text) || '').toLowerCase().trim();
+  return { pass: text.startsWith('y'), reason: 'haiku:' + (text || 'empty').slice(0, 16) };
+}
+
+module.exports = { heuristicGate, llmGate, MIN_TURNS };

package/lib/locale.js

@@ -0,0 +1,141 @@
+// Locale resolution + label tables for ko / en.
+//
+// 우선순위:
+//   1. --lang=ko|en 플래그
+//   2. CLAUDE_DISTILL_LANG 환경변수
+//   3. transcript 자동 감지 (Hangul 비율)
+//   4. process.env.LANG
+//   5. fallback 'en'
+//
+// 지원 범위는 의도적으로 ko / en 둘로만 제한. 추가 언어는 LABELS 테이블 + detector
+// 분기만 늘리면 되지만 v0.4 첫 cut에선 두 언어로 시작.
+
+const SUPPORTED = ['ko', 'en'];
+const DEFAULT = 'en';
+
+const LABELS = {
+  en: {
+    knowledgeHeader:
+      '# Knowledge — case law\n\n' +
+      '> Judgment calls worth remembering. Maintained by [claude-distill](https://github.com/parksubeom/claude-distill).\n\n',
+    gotchasHeader:
+      '# Gotchas — incident reports\n\n' +
+      '> Mistakes worth not repeating. Maintained by [claude-distill](https://github.com/parksubeom/claude-distill).\n\n',
+    category: 'Category',
+    confidence: 'Confidence',
+    date: 'Date',
+    source: 'Source',
+    sessionWord: 'session',
+    projectWord: 'project',
+    cmdsWord: 'cmds',
+    contextLabel: 'Context',
+    symptomLabel: 'Symptom',
+    insightLabel: 'Insight',
+    trapLabel: 'Trap',
+    basisLabel: 'Basis',
+    applicationLabel: 'Application',
+    tagsLabel: 'Tags',
+    untitled: '(untitled)',
+  },
+  ko: {
+    knowledgeHeader:
+      '# 판례 — Knowledge\n\n' +
+      '> 다음에도 기억할 만한 결정. [claude-distill](https://github.com/parksubeom/claude-distill)이 자동 누적합니다.\n\n',
+    gotchasHeader:
+      '# 사고 보고서 — Gotchas\n\n' +
+      '> 다시 빠지지 말아야 할 함정. [claude-distill](https://github.com/parksubeom/claude-distill)이 자동 누적합니다.\n\n',
+    category: '카테고리',
+    confidence: '신뢰도',
+    date: '날짜',
+    source: '출처',
+    sessionWord: '세션',
+    projectWord: '프로젝트',
+    cmdsWord: '명령',
+    contextLabel: '상황',
+    symptomLabel: '증상',
+    insightLabel: '인사이트',
+    trapLabel: '함정',
+    basisLabel: '근거',
+    applicationLabel: '적용',
+    tagsLabel: '태그',
+    untitled: '(제목 없음)',
+  },
+};
+
+function normalize(v) {
+  if (!v) return null;
+  const s = String(v).toLowerCase().trim();
+  if (s.startsWith('ko')) return 'ko';
+  if (s.startsWith('en')) return 'en';
+  return null;
+}
+
+// transcript의 turns를 stringify해서 한글 음절 (U+AC00–U+D7A3) 비율을 계산.
+// 시그널이 약하면 (글자 자체가 적으면) null 반환 — 호출자가 다음 우선순위로.
+function detectFromTranscript(t) {
+  if (!t || !Array.isArray(t.turns) || t.turns.length === 0) return null;
+  let kor = 0;
+  let letters = 0;
+  for (const turn of t.turns) {
+    const s = JSON.stringify(turn);
+    for (let i = 0; i < s.length; i++) {
+      const code = s.charCodeAt(i);
+      const isHangul = code >= 0xAC00 && code <= 0xD7A3;
+      const isLatin = (code >= 0x41 && code <= 0x5A) || (code >= 0x61 && code <= 0x7A);
+      if (isHangul) kor++;
+      if (isHangul || isLatin) letters++;
+    }
+  }
+  if (letters < 200) return null;
+  // 한글 음절은 글자 하나당 정보량이 라틴 알파벳보다 크므로 5%만 넘어도
+  // 실제로는 한국어 위주의 세션. 임계값 보수적으로 0.05.
+  return kor / letters > 0.05 ? 'ko' : 'en';
+}
+
+function resolveLocale({ flag, transcript } = {}) {
+  const fromFlag = normalize(flag);
+  if (fromFlag) return fromFlag;
+  const fromEnv = normalize(process.env.CLAUDE_DISTILL_LANG);
+  if (fromEnv) return fromEnv;
+  const fromTranscript = detectFromTranscript(transcript);
+  if (fromTranscript) return fromTranscript;
+  const fromSysLang = normalize(process.env.LANG);
+  if (fromSysLang) return fromSysLang;
+  return DEFAULT;
+}
+
+function labels(locale) {
+  return LABELS[SUPPORTED.includes(locale) ? locale : DEFAULT];
+}
+
+// LLM에 출력 언어를 강제하는 directive. JSON 식별자 필드는 enum 그대로
+// 유지하라고 명시 — 카테고리 키가 번역되면 store.js의 isGotcha 분기 등이 깨짐.
+function promptDirective(locale) {
+  if (locale === 'ko') {
+    return [
+      '',
+      '---',
+      '',
+      'OUTPUT LANGUAGE: 모든 entry의 자연어 필드(title, context, insight, basis, application)와 tags 배열은 **한국어**로 작성하세요.',
+      '단, 식별자 필드(type, category, confidence)는 명세된 영어 enum 값 그대로 유지 — 번역 금지.',
+      'JSON 키 이름과 구조도 그대로. 한국어로 표현하기 어려운 기술 용어는 영어 그대로 두어도 됩니다.',
+    ].join('\n');
+  }
+  return [
+    '',
+    '---',
+    '',
+    'OUTPUT LANGUAGE: Write the natural-language fields (title, context, insight, basis, application) and tags array in **English**.',
+    'Keep identifier fields (type, category, confidence) as their specified English enum values — do not translate.',
+    'Do not change JSON key names or structure.',
+  ].join('\n');
+}
+
+module.exports = {
+  SUPPORTED,
+  DEFAULT,
+  resolveLocale,
+  detectFromTranscript,
+  labels,
+  promptDirective,
+};

package/lib/store.js

@@ -5,6 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const cfg = require('./config');
+const locale = require('./locale');
 
 function resolveTarget(entry) {
   const isGotcha = entry.type === 'gotcha';
@@ -16,61 +17,53 @@ function resolveTarget(entry) {
   return isGotcha ? cfg.GLOBAL_GOTCHAS : cfg.GLOBAL_KNOWLEDGE;
 }
 
-function ensureHeader(file, isGotcha) {
+function ensureHeader(file, isGotcha, lang) {
   if (fs.existsSync(file)) return;
-  const header = isGotcha
-    ? `# Gotchas — incident reports
-
-> Mistakes worth not repeating. Maintained by [claude-distill](https://github.com/parksubeom/claude-distill).
-
-`
-    : `# Knowledge — case law
-
-> Judgment calls worth remembering. Maintained by [claude-distill](https://github.com/parksubeom/claude-distill).
-
-`;
+  const L = locale.labels(lang);
+  const header = isGotcha ? L.gotchasHeader : L.knowledgeHeader;
   fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(file, header);
 }
 
-function formatEntry(e) {
-  const title = e.title || '(untitled)';
+function formatEntry(e, lang) {
+  const L = locale.labels(lang);
+  const title = e.title || L.untitled;
   const date = (e.source && e.source.timestamp) ? e.source.timestamp.slice(0, 10) : new Date().toISOString().slice(0, 10);
   const sessionId = (e.source && e.source.sessionId) || 'unknown';
   const project = (e.source && e.source.project) || 'unknown';
   const cmds = (e.source && e.source.relatedCommands && e.source.relatedCommands.length)
-    ? ' · cmds: ' + e.source.relatedCommands.join(', ')
+    ? ' · ' + L.cmdsWord + ': ' + e.source.relatedCommands.join(', ')
     : '';
   const tags = (e.tags || []).map((t) => '`' + t + '`').join(' · ');
   const conf = e.confidence || 'medium';
-  const symptomLabel = e.type === 'gotcha' ? 'Symptom' : 'Context';
-  const insightLabel = e.type === 'gotcha' ? 'Trap' : 'Insight';
+  const symptomLabel = e.type === 'gotcha' ? L.symptomLabel : L.contextLabel;
+  const insightLabel = e.type === 'gotcha' ? L.trapLabel : L.insightLabel;
 
   return [
     `## ${title}`,
-    `**Category**: \`${e.category}\`  · **Confidence**: ${conf}  · **Date**: ${date}`,
-    `**Source**: session \`${sessionId.slice(0, 8)}\` · project \`${project}\`${cmds}`,
+    `**${L.category}**: \`${e.category}\`  · **${L.confidence}**: ${conf}  · **${L.date}**: ${date}`,
+    `**${L.source}**: ${L.sessionWord} \`${sessionId.slice(0, 8)}\` · ${L.projectWord} \`${project}\`${cmds}`,
     '',
     `**${symptomLabel}**: ${e.context || ''}`,
     '',
     `**${insightLabel}**: ${e.insight || ''}`,
     '',
-    `**Basis**: ${e.basis || ''}`,
+    `**${L.basisLabel}**: ${e.basis || ''}`,
     '',
-    `**Application**: ${e.application || ''}`,
+    `**${L.applicationLabel}**: ${e.application || ''}`,
     '',
-    `**Tags**: ${tags}`,
+    `**${L.tagsLabel}**: ${tags}`,
     '',
     '---',
     '',
   ].join('\n');
 }
 
-function appendEntry(entry) {
+function appendEntry(entry, lang) {
   const file = resolveTarget(entry);
   const isGotcha = entry.type === 'gotcha';
-  ensureHeader(file, isGotcha);
-  fs.appendFileSync(file, formatEntry(entry));
+  ensureHeader(file, isGotcha, lang);
+  fs.appendFileSync(file, formatEntry(entry, lang));
   return file;
 }
 

package/lib/where.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const cfg = require('./config');
+const localeMod = require('./locale');
 
 const CLAUDE_MD = path.join(cfg.CLAUDE_DIR, 'CLAUDE.md');
 
@@ -21,6 +22,11 @@ function run() {
   console.log('  analyzed.json   ' + exists(path.join(cfg.STATE_DIR, 'analyzed.json')) + '  중복 분석 방지 로그');
   console.log('');
   console.log('extract prompt    ' + exists(cfg.PROMPT_FILE)       + '  ' + cfg.PROMPT_FILE);
+  console.log('');
+  const envLang = process.env.CLAUDE_DISTILL_LANG || '(unset)';
+  const resolved = localeMod.resolveLocale();
+  console.log('locale (env)      ·  CLAUDE_DISTILL_LANG=' + envLang);
+  console.log('locale (resolved) ·  ' + resolved + '  (transcript 자동 감지가 우선 — 세션 분석 시점에 결정)');
 }
 
 module.exports = { run };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-distill",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Distill knowledge and gotchas from Claude Code session transcripts. Hook-based feedback loop: session → extract → review → accumulate.",
   "bin": {
     "claude-distill": "bin/distill.js",
@@ -39,7 +39,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/parksubeom/claude-distill.git"
+    "url": "git+https://github.com/parksubeom/claude-distill.git"
   },
   "files": [
     "bin",