claude-distill 0.2.0 → 0.3.0

package/README.md

@@ -90,9 +90,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 +104,8 @@ source ~/.zshrc
      └─ Claude가 자연스럽게 참조 — 같은 함정 안 빠짐
 ```
 
+게이트 두 단계는 "대부분의 세션은 인사이트가 없다" 가정으로 본 추출 호출을 ~10× 줄입니다. 게이트가 차단된 세션은 dedup에 마킹돼 같은 슬라이스로 다시 호출돼도 즉시 종료.
+
 ---
 
 ## 카테고리
@@ -141,15 +146,28 @@ 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_CHILD` — distill이 spawn한 자식 claude 표식. 수동 설정 불필요 (hook 무한 재귀 차단용 내부 플래그)
 
 ---
 
-## 프라이버시
+## 프라이버시 / 보안
+
+**별도 서버 없음.** 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 +177,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 +194,24 @@ 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.3 — 게이트 도입 (휴리스틱 + Haiku) + Stop 훅 무한 재귀 가드. 본 추출 호출 ~10× 감소.
+v0.2 — 자동 누적 모델로 재정비.
 
 ## License
 

package/lib/analyze.js

@@ -21,6 +21,10 @@ const crypto = require('crypto');
 const cfg = require('./config');
 const transcript = require('./transcript');
 const store = require('./store');
+const gate = require('./gate');
+
+// 자식 claude 프로세스 표식. distill→claude→Stop 훅→distill 무한 재귀 차단용.
+const CHILD_ENV_KEY = 'CLAUDE_DISTILL_CHILD';
 
 function parseFlags(args) {
   const flags = {
@@ -30,6 +34,7 @@ function parseFlags(args) {
     mock: false,
     auto: true,        // 기본값 — 자동 누적 (CLI 핵심)
     backend: 'auto',   // 'auto' | 'cli' | 'api' — auto는 ANTHROPIC_API_KEY 있으면 api, 없으면 cli
+    noGate: false,     // 게이트 우회 (디버깅 / 강제 분석)
   };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -37,6 +42,7 @@ 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);
@@ -83,6 +89,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 +191,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 +227,33 @@ async function run(args) {
     return;
   }
 
+  // ── 게이트 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) {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-distill",
-  "version": "0.2.0",
+  "version": "0.3.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",