claude-distill 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 parksubeom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# claude-distill
+
+> Claude한테 같은 함정을 세 번째 설명하고 계신가요?
+
+세션마다 트레이드오프 결정 (`A 대신 B 선택, 이유는…`), 환경 함정 (`Cursor webview는 confirm() 차단됨`), 같은 실수 (`Claude Code JSONL의 promptId는 항상 null`)가 쌓입니다. 그런데 세션이 끝나면 다 잊혀집니다. CLAUDE.md를 매번 갱신하면 좋겠지만 — 솔직히 안 하죠.
+
+`claude-distill`은 **Stop hook**입니다. 한 번 설치하면:
+
+1. 세션 끝날 때마다 transcript를 자동으로 분석
+2. confidence:high 판례 + 사고 보고서를 markdown에 자동 누적
+3. 다음 세션부터 Claude가 자동으로 참조 (CLAUDE.md `@reference` 통해)
+
+사용자가 하는 일: `claude-distill init` **한 번. 끝.**
+
+---
+
+## 어떤 게 자동으로 누적되나
+
+세션 한 번 했더니 이런 entry들이 알아서 추출돼서 `~/.claude/gotchas.md` / `knowledge.md`에 추가됐습니다 (모두 진짜 dogfood 결과, 편집 없음):
+
+```
+⚠️  npm link가 macOS 기본 prefix에서 sudo 없이 실패 — 절대경로로 우회
+⚠️  Claude Code JSONL의 promptId가 항상 null — uuid + parentUuid 체인 사용
+⚠️  Cursor 빌트인 Claude는 PATH에 `claude` 바이너리를 노출 안 함
+🧠  ffmpeg cropdetect의 limit은 어두운 padding에서 ≥32 필요
+🧠  Transcript를 마지막 user marker부터 slice하면 분석 prompt ~80% 감소
+🧠  CSP `connect-src 'none'`이 webview의 외부 fetch를 이중 차단
+```
+
+각 entry는 `Symptom → Trap → Cause → Workaround` 4단으로 자동 정리됩니다 — 다음 세션의 Claude가 그대로 읽고 참조 가능한 형태로. 분석기 prompt가 보수적이라 자명한 사실 / 프로젝트 internal trivia / 검증 안 된 추측은 제외됩니다.
+
+전체 markdown은 IDE에서 그냥 열어보면 됩니다.
+
+---
+
+## 비유
+
+| 파일 | 역할 |
+|---|---|
+| **`CLAUDE.md`** | 법률 — 변하지 않는 보편 규칙 (직접 작성) |
+| **`knowledge.md`** | 판례 — "이 상황엔 이렇게 했다" (자동 누적) |
+| **`gotchas.md`** | 사고 보고서 — "같은 실수 반복 금지" (자동 누적) |
+
+법률은 사람이 쓰지만, 판례와 사고 보고서는 매일 쌓이는 거니까 — 그건 자동화될 수 있습니다.
+
+---
+
+## 설치
+
+```bash
+npm install -g claude-distill
+claude-distill init
+```
+
+분석을 위한 LLM 호출 경로 둘 중 하나가 필요합니다:
+
+### 옵션 A — Claude Code CLI 사용자 (사전 설치 필요)
+
+```bash
+npm install -g @anthropic-ai/claude-code
+# 끝. distill이 자동으로 `claude --print` 호출.
+```
+
+### 옵션 B — Claude Code IDE 익스텐션 사용자 (Cursor / VS Code)
+
+빌트인 Claude는 PATH에 노출되지 않으니 **API key**를 사용:
+
+```bash
+# https://console.anthropic.com/ 에서 API key 발급 후
+echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.zshrc
+source ~/.zshrc
+# distill이 환경변수 감지 시 자동으로 API 호출.
+```
+
+(또는 옵션 A처럼 CLI 추가 설치도 가능 — IDE와 별개 동작.)
+
+---
+
+`init`이 idempotent하게 두 가지를 등록:
+
+1. `~/.claude/settings.json` 의 **Stop hook** — 세션마다 자동 분석 호출
+2. `~/.claude/CLAUDE.md` 끝의 **`@knowledge.md` / `@gotchas.md` 참조** — 다음 세션부터 Claude가 자동 참조
+
+끝입니다. 더 이상 손 안 댑니다.
+
+---
+
+## 어떻게 동작
+
+```
+세션 끝
+  └─ Stop hook이 `claude-distill analyze --quiet` 자동 실행
+     ├─ 마지막 user marker 이후 turn slice (보통 ~120 turns / ~85K chars)
+     ├─ `claude --print`로 analyzer prompt 전달
+     ├─ JSON 응답 파싱
+     ├─ confidence:high entry → ~/.claude/knowledge.md / gotchas.md 즉시 append
+     └─ medium / low → drop (사용자 손 안 가게)
+
+다음 세션 시작
+  └─ CLAUDE.md의 @reference로 누적된 markdown이 system prompt에 inject
+     └─ Claude가 자연스럽게 참조 — 같은 함정 안 빠짐
+```
+
+---
+
+## 카테고리
+
+분석기가 entry마다 다음 11개 중 하나로 분류합니다:
+
+**판례 (knowledge)**
+`trade_off_decision` · `environment_quirk` · `scale_transition` · `tooling_insight` · `performance_insight`
+
+**사고 (gotcha)**
+`api_quirk` · `type_shape` · `concurrency_race` · `build_deploy` · `privacy_security` · `ux_regression`
+
+---
+
+## 결과 보기
+
+별도 UI 없습니다. 두 markdown 파일을 그냥 IDE에서 열어보세요:
+
+```bash
+~/.claude/knowledge.md
+~/.claude/gotchas.md
+```
+
+마음에 안 드는 entry는 그 줄을 그냥 삭제하면 됩니다 (markdown이라 자유 편집). 다음 세션부터 그 entry는 더 이상 inject되지 않음.
+
+---
+
+## CLI 명령 (3개)
+
+| 명령 | 용도 | 빈도 |
+|---|---|---|
+| `claude-distill init` | hook + CLAUDE.md reference 등록 | **한 번** |
+| `claude-distill where` | path / 존재 여부 확인 (디버깅) | 가끔 |
+| `claude-distill analyze` | 수동 분석 | **거의 안 씀** (hook이 자동) |
+
+`analyze`의 옵션 (잘 안 쓸 것):
+- `--no-auto` — 자동 누적 대신 stdout에 JSON 출력
+- `--mock` — claude CLI 호출 없이 가짜 entry 1건 (파이프라인 검증용)
+- `--session=<file>` — 특정 jsonl 직접 지정
+- `--quiet` — 출력 억제 (hook이 사용)
+
+---
+
+## 프라이버시
+
+- 모든 추출이 사용자 머신에서 진행. transcript는 사용자가 (또는 hook이) 호출할 때만 Claude API로 전달.
+- 결과는 plain markdown. git ignore 규칙 그대로 따름 (전역 파일이라 default ignore).
+- hook은 `~/.claude/settings.json`에서 직접 비활성화 가능.
+- 같은 transcript를 두 번 분석하지 않도록 `~/.claude/.distill/analyzed.json`에 sha hash만 저장.
+
+---
+
+## FAQ
+
+**Q. CLAUDE.md를 직접 작성하면 안 되나?**
+A. 직접 작성 가능. `claude-distill`은 매일 쌓이는 자잘한 판례/사고를 자동으로 잡아내는 보조 도구. CLAUDE.md는 변하지 않는 보편 규칙용으로 그대로 쓰시면 됩니다.
+
+**Q. 토큰 비용은?**
+A. 세션당 1회 분석. 보통 prompt ~85K chars (~20K tokens) input, 응답 ~2K tokens output. Sonnet 기준 세션당 약 $0.10. 가벼운 세션은 더 적음.
+
+**Q. confidence:medium / low는 왜 drop?**
+A. 노이즈 누적이 가장 큰 실패 패턴이라 보수적으로 시작. 향후 `--keep-medium` 옵션 추가 가능.
+
+**Q. 프로젝트별 누적은?**
+A. 전역이 기본. 프로젝트별 원하면 `<project>/.claude/CLAUDE.md`에 직접 `@.claude/knowledge.md` 추가. v0.3+에서 `--scope=project` 옵션 자동화 예정.
+
+**Q. Cursor / VS Code Claude Code 익스텐션 사용자도 됨?**
+A. **됩니다.** transcript는 익스텐션도 같은 위치(`~/.claude/projects/`)에 저장. 분석을 위한 LLM 호출만 별도 경로가 필요한데, `ANTHROPIC_API_KEY`만 환경변수로 export하면 distill이 자동으로 Anthropic API 직접 호출 (Node 18+ 빌트인 fetch).
+
+**Q. 다른 LLM 백엔드?**
+A. 현재 `claude` CLI + Anthropic API 두 가지. `--backend=cli|api|auto` 옵션. 기본 `auto`는 `ANTHROPIC_API_KEY` 있으면 API 우선, 없으면 CLI fallback. OpenAI / 로컬 LLM 지원은 v0.3+.
+
+---
+
+## 상태
+
+v0.2 — 자동 누적 모델로 재정비. 실 사용 결과 알려주시면 prompt 튜닝 / 카테고리 조정 진행합니다.
+
+## License
+
+MIT © parksubeom

package/bin/distill.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// claude-distill — zero-effort knowledge accumulator for Claude Code.
+//
+// 명령은 단 3개:
+//   init    — Stop hook + CLAUDE.md @reference 한 번 등록
+//   analyze — 자동 분석 (Hook이 호출, 직접 호출 불필요)
+//   where   — 모든 경로 sanity check
+//
+// 그 외(review/list/search/archive)는 의도적으로 없습니다. markdown 파일을
+// 그냥 IDE에서 열어 보시면 됩니다.
+
+const cmd = process.argv[2];
+const args = process.argv.slice(3);
+
+const help = `claude-distill — Knowledge + Gotchas auto-accumulator for Claude Code
+
+설치:
+  claude-distill init       Stop hook + CLAUDE.md reference 등록 (한 번만)
+
+확인:
+  claude-distill where      모든 파일 경로 / 존재 여부
+
+수동 분석 (보통 Hook이 자동으로 함):
+  claude-distill analyze [--no-auto] [--mock] [--quiet]
+
+결과는 plain markdown:
+  ~/.claude/knowledge.md    판례 (전역)
+  ~/.claude/gotchas.md      사고 보고서 (전역)
+또는 프로젝트별:
+  <project>/.claude/knowledge.md
+  <project>/.claude/gotchas.md
+
+editor에서 직접 열어보시면 됩니다 — review UI 없습니다.`;
+
+const dispatch = {
+  init:    () => require('../lib/init').run(args),
+  analyze: () => require('../lib/analyze').run(args),
+  where:   () => require('../lib/where').run(args),
+  '--help': () => console.log(help),
+  '-h':     () => console.log(help),
+};
+
+if (!cmd || !dispatch[cmd]) {
+  console.log(help);
+  process.exit(cmd ? 1 : 0);
+}
+
+Promise.resolve(dispatch[cmd]()).catch((err) => {
+  console.error('claude-distill: ' + (err && err.message ? err.message : err));
+  process.exit(1);
+});

package/lib/analyze.js

@@ -0,0 +1,273 @@
+// `claude-distill analyze [--no-auto] [--mock] [--quiet] [--session=X]`
+//
+// SessionEnd hook이 자동 호출. 사용자가 직접 부를 일은 거의 없음.
+//
+// 동작 (기본):
+//   1. 가장 최근 세션 jsonl을 slice
+//   2. claude CLI에 분석 prompt 전달
+//   3. confidence:high entry만 markdown에 자동 append
+//   4. medium/low entry는 그냥 drop (사용자 손 가지 않게)
+//
+// 옵션:
+//   --no-auto      추출만 하고 stdout에 JSON 출력 (디버깅용)
+//   --mock         claude CLI 호출 없이 fake entry 1건 생성
+//   --quiet        Hook용 — 아무 출력 안 함
+//   --session=X    특정 jsonl 직접 지정
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const crypto = require('crypto');
+const cfg = require('./config');
+const transcript = require('./transcript');
+const store = require('./store');
+
+function parseFlags(args) {
+  const flags = {
+    quiet: false,
+    session: null,
+    dryRun: false,
+    mock: false,
+    auto: true,        // 기본값 — 자동 누적 (CLI 핵심)
+    backend: 'auto',   // 'auto' | 'cli' | 'api' — auto는 ANTHROPIC_API_KEY 있으면 api, 없으면 cli
+  };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--quiet') flags.quiet = true;
+    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.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];
+  }
+  return flags;
+}
+
+function log(flags, ...a) { if (!flags.quiet) console.log(...a); }
+
+// 기존 markdown 파일을 dedup 컨텍스트로 분석기에 전달.
+// 같은 lesson을 두 번 추출하지 않도록.
+function existingForDedup() {
+  const out = { knowledge: '', gotchas: '' };
+  try { out.knowledge = fs.readFileSync(cfg.GLOBAL_KNOWLEDGE, 'utf8'); } catch {}
+  try { out.gotchas = fs.readFileSync(cfg.GLOBAL_GOTCHAS, 'utf8'); } catch {}
+  return out;
+}
+
+function buildAnalyzerPrompt(promptText, existing, t) {
+  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.`;
+}
+
+function mockExtract() {
+  return [{
+    type: 'gotcha',
+    category: 'api_quirk',
+    title: 'Sample mock gotcha — replace with real run',
+    context: 'Mock entry from --mock so you can verify the pipeline without an LLM call.',
+    insight: 'Real entries come from `claude-distill analyze` against an actual session.',
+    basis: 'Generated by lib/analyze.js mockExtract().',
+    application: 'Run `claude-distill analyze` after a real session to replace this.',
+    tags: ['mock', 'sample'],
+    confidence: 'high',
+  }];
+}
+
+function callClaudeCli(promptText) {
+  try {
+    return execFileSync('claude', ['--print'], {
+      input: promptText,
+      timeout: 120000,
+      maxBuffer: 16 * 1024 * 1024,
+      encoding: 'utf8',
+    });
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      const hint = [
+        '`claude` CLI를 PATH에서 찾을 수 없습니다.',
+        '',
+        '두 가지 해결 옵션:',
+        '  1) CLI 설치:  npm install -g @anthropic-ai/claude-code',
+        '  2) API key 사용:  export ANTHROPIC_API_KEY=sk-ant-...',
+        '                    claude-distill analyze --backend=api',
+        '',
+        'IDE 빌트인 Claude(Cursor / VS Code 익스텐션)는 PATH에 노출되지 않습니다 —',
+        '그래서 별도 CLI 설치 또는 API key가 필요합니다. transcript 자체는',
+        '익스텐션도 ~/.claude/projects/에 저장하므로 distill이 읽을 수 있습니다.',
+      ].join('\n');
+      throw new Error(hint);
+    }
+    throw new Error('claude CLI 실행 실패: ' + (e.stderr || e.message || String(e)));
+  }
+}
+
+// Anthropic API 직접 호출 — Claude Code CLI 없는 환경 (Cursor / VS Code
+// 익스텐션 사용자) 용. Node 18+의 빌트인 fetch 사용.
+async function callClaudeApi(promptText) {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    throw new Error('ANTHROPIC_API_KEY 환경변수 미설정. https://console.anthropic.com/ 에서 키 발급 후 export.');
+  }
+  const model = process.env.CLAUDE_DISTILL_MODEL || 'claude-sonnet-4-6';
+  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: 4096,
+        messages: [{ role: 'user', content: promptText }],
+      }),
+    });
+  } catch (e) {
+    throw new Error('Anthropic API 네트워크 호출 실패: ' + e.message);
+  }
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error('Anthropic API ' + res.status + ': ' + body.slice(0, 400));
+  }
+  const data = await res.json();
+  const block = (data.content || []).find((c) => c.type === 'text');
+  if (!block) throw new Error('Anthropic API 응답에 text block 없음');
+  return block.text;
+}
+
+// backend 결정: 'auto'면 환경변수 보고 결정. CLI 없는 사용자 (익스텐션
+// 전용)도 API key만 있으면 자동으로 api 백엔드.
+async function callBackend(promptText, backend) {
+  if (backend === 'cli') return callClaudeCli(promptText);
+  if (backend === 'api') return await callClaudeApi(promptText);
+  // 'auto'
+  if (process.env.ANTHROPIC_API_KEY) return await callClaudeApi(promptText);
+  return callClaudeCli(promptText);
+}
+
+function tryParseJson(s) {
+  let t = s.trim()
+    .replace(/^```json\s*/i, '')
+    .replace(/^```\s*/, '')
+    .replace(/```\s*$/, '')
+    .trim();
+  const start = t.indexOf('[');
+  const end = t.lastIndexOf(']');
+  if (start === -1 || end === -1 || end <= start) return null;
+  try { return JSON.parse(t.slice(start, end + 1)); } catch { return null; }
+}
+
+function transcriptHash(t) {
+  const h = crypto.createHash('sha1');
+  h.update(JSON.stringify(t.turns));
+  return h.digest('hex').slice(0, 12);
+}
+
+// 같은 세션 같은 슬라이스면 중복 분석 방지 (Hook이 여러 번 호출돼도 안전).
+function readDedupLog() {
+  const f = path.join(cfg.STATE_DIR, 'analyzed.json');
+  if (!fs.existsSync(f)) return new Set();
+  try { return new Set(JSON.parse(fs.readFileSync(f, 'utf8'))); } catch { return new Set(); }
+}
+function writeDedupLog(set) {
+  cfg.ensureStateDir();
+  const f = path.join(cfg.STATE_DIR, 'analyzed.json');
+  fs.writeFileSync(f, JSON.stringify([...set], null, 2) + '\n');
+}
+
+async function run(args) {
+  const flags = parseFlags(args);
+  cfg.ensureStateDir();
+
+  let file = flags.session || transcript.latestSessionFile();
+  let t;
+  let sessionId;
+  if (flags.mock && !file) {
+    file = '<mock-session>';
+    t = { source: file, turns: [], totalLines: 0, sliceFrom: 0, commandMarkers: [] };
+    sessionId = 'mock-' + Date.now();
+    log(flags, 'Mock 모드 — 실제 세션 없이 진행');
+  } else {
+    if (!file) { log(flags, '세션 jsonl을 찾을 수 없음 (' + cfg.PROJECTS_DIR + ')'); return; }
+    if (!fs.existsSync(file)) { log(flags, '세션 파일 없음: ' + file); return; }
+    t = transcript.extractRelevant(file);
+    if (!t.turns.length && !flags.mock) { log(flags, '분석할 turn 없음'); return; }
+    log(flags, '분석: ' + path.basename(file) + ' · ' + t.turns.length + ' turns');
+    sessionId = path.basename(file, '.jsonl');
+  }
+
+  const dedupKey = sessionId + ':' + transcriptHash(t);
+  const seen = readDedupLog();
+  if (seen.has(dedupKey)) {
+    log(flags, '이 세션 슬라이스는 이미 분석됨 — 새로 추가할 것 없음');
+    return;
+  }
+
+  // LLM 호출
+  let candidates;
+  if (flags.mock) {
+    candidates = mockExtract();
+  } else {
+    const prompt = fs.readFileSync(cfg.PROMPT_FILE, 'utf8');
+    const existing = existingForDedup();
+    const fullPrompt = buildAnalyzerPrompt(prompt, existing, t);
+    if (flags.dryRun) {
+      log(flags, '[--dry-run] prompt 준비됨 (' + fullPrompt.length + ' chars). LLM 호출 생략.');
+      return;
+    }
+    let raw;
+    try { raw = await callBackend(fullPrompt, flags.backend); }
+    catch (e) { log(flags, '분석 실패: ' + e.message); return; }
+    candidates = tryParseJson(raw) || [];
+  }
+
+  if (!Array.isArray(candidates) || !candidates.length) {
+    log(flags, '추출할 만한 entry 없음 (빈 배열도 정상 응답)');
+    seen.add(dedupKey);
+    writeDedupLog(seen);
+    return;
+  }
+
+  // 자동 누적 (기본 동작) — confidence:high만, 나머지는 drop
+  if (flags.auto) {
+    const cwd = process.cwd();
+    let appended = 0;
+    let dropped = 0;
+    for (const c of candidates) {
+      if (c.confidence !== 'high') { dropped++; continue; }
+      const annotated = {
+        id: crypto.randomUUID(),
+        ...c,
+        scope: 'global',
+        source: {
+          sessionId,
+          project: path.basename(cwd),
+          cwd,
+          timestamp: new Date().toISOString(),
+          relatedCommands: c.related_commands || [],
+        },
+      };
+      try {
+        const dest = store.appendEntry(annotated);
+        appended++;
+        log(flags, '  ✓ ' + (c.title || c.id) + ' → ' + dest);
+      } catch (err) {
+        log(flags, '  실패: ' + (c.title || c.id) + ' — ' + err.message);
+      }
+    }
+    log(flags, `자동 추가 ${appended}건${dropped ? ` · 신뢰도 부족 ${dropped}건 drop` : ''}`);
+  } else {
+    // --no-auto — JSON 그대로 stdout (디버깅 용도)
+    process.stdout.write(JSON.stringify(candidates, null, 2) + '\n');
+  }
+
+  seen.add(dedupKey);
+  writeDedupLog(seen);
+}
+
+module.exports = { run };

package/lib/config.js

@@ -0,0 +1,55 @@
+// Resolved paths and constants used across every subcommand.
+// Keeps the rest of lib/ free of path string-building.
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const HOME = os.homedir();
+const CLAUDE_DIR = process.env.CLAUDE_CONFIG_DIR
+  ? path.resolve(process.env.CLAUDE_CONFIG_DIR)
+  : path.join(HOME, '.claude');
+
+// 유일한 state file은 analyzed.json (같은 슬라이스 중복 분석 방지).
+// pending/archive/stats 같은 review-driven state 시스템은 v0.2부터 모두 제거.
+const STATE_DIR = path.join(CLAUDE_DIR, '.distill');
+
+const SETTINGS_FILE = path.join(CLAUDE_DIR, 'settings.json');
+
+const PROJECTS_DIR = path.join(CLAUDE_DIR, 'projects');
+
+// Knowledge / gotchas live in two scopes — global (always) and per-project
+// (under <project>/.claude/). globalStore() and projectStore() in lib/store.js
+// pick the right one based on entry.scope.
+const GLOBAL_KNOWLEDGE = path.join(CLAUDE_DIR, 'knowledge.md');
+const GLOBAL_GOTCHAS   = path.join(CLAUDE_DIR, 'gotchas.md');
+
+// Where the package keeps its bundled prompt + templates after install.
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const PROMPT_FILE = path.join(PACKAGE_ROOT, 'prompts', 'extract.md');
+const TEMPLATE_DIR = path.join(PACKAGE_ROOT, 'templates');
+
+function ensureStateDir() {
+  fs.mkdirSync(STATE_DIR, { recursive: true });
+}
+
+// `cwd` → project slug used in JSONL paths (~/.claude/projects/<slug>/).
+// Mirrors Claude Code's own slugging: absolute path with separators replaced.
+function cwdToProjectSlug(cwd) {
+  return cwd.replace(/[\\\/]/g, '-');
+}
+
+module.exports = {
+  HOME,
+  CLAUDE_DIR,
+  STATE_DIR,
+  SETTINGS_FILE,
+  PROJECTS_DIR,
+  GLOBAL_KNOWLEDGE,
+  GLOBAL_GOTCHAS,
+  PACKAGE_ROOT,
+  PROMPT_FILE,
+  TEMPLATE_DIR,
+  ensureStateDir,
+  cwdToProjectSlug,
+};

package/lib/init.js

@@ -0,0 +1,114 @@
+// `claude-distill init [--no-claude-md]`
+//
+// 두 가지를 한 번에 등록:
+//   1. ~/.claude/settings.json 의 Stop hook (자동 분석)
+//   2. ~/.claude/CLAUDE.md 끝에 @knowledge.md / @gotchas.md 참조 라인
+//      → 다음 세션부터 Claude가 누적된 판례/사고를 자연스럽게 참조
+//
+// idempotent — 두 번 실행해도 중복 등록 안 함.
+//
+// --no-claude-md 옵션: CLAUDE.md 자동 편집 건너뛰기 (사용자가 직접 추가)
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const cfg = require('./config');
+
+// PATH에 `claude-distill`이 있으면 그대로, 없으면 자기 자신의 절대 경로 사용.
+// npm 글로벌 install 없이도 init 한 번으로 끝나게 만드는 핵심.
+function resolveHookCommand() {
+  try {
+    execSync('which claude-distill', { stdio: 'ignore' });
+    return 'claude-distill analyze --quiet';
+  } catch {
+    const binPath = path.join(cfg.PACKAGE_ROOT, 'bin', 'distill.js');
+    return `node ${binPath} analyze --quiet`;
+  }
+}
+
+const HOOK_COMMAND = resolveHookCommand();
+const CLAUDE_MD = path.join(cfg.CLAUDE_DIR, 'CLAUDE.md');
+const REFERENCE_BLOCK = `
+<!-- claude-distill auto-references — accumulated lessons from past sessions -->
+@~/.claude/knowledge.md
+@~/.claude/gotchas.md
+`;
+
+function readSettings() {
+  if (!fs.existsSync(cfg.SETTINGS_FILE)) return {};
+  try { return JSON.parse(fs.readFileSync(cfg.SETTINGS_FILE, 'utf8')); }
+  catch { return {}; }
+}
+
+function writeSettings(s) {
+  fs.mkdirSync(path.dirname(cfg.SETTINGS_FILE), { recursive: true });
+  fs.writeFileSync(cfg.SETTINGS_FILE, JSON.stringify(s, null, 2) + '\n');
+}
+
+function hookAlreadyInstalled(s) {
+  const stop = (s.hooks && s.hooks.Stop) || [];
+  for (const matcher of stop) {
+    for (const h of (matcher.hooks || [])) {
+      if (h.command && h.command.includes('claude-distill')) return true;
+    }
+  }
+  return false;
+}
+
+function ensureHook(quiet) {
+  const s = readSettings();
+  if (hookAlreadyInstalled(s)) {
+    if (!quiet) console.log('· Hook 이미 등록됨 — 건너뜀');
+    return false;
+  }
+  s.hooks = s.hooks || {};
+  s.hooks.Stop = s.hooks.Stop || [];
+  s.hooks.Stop.push({
+    matcher: '*',
+    hooks: [{ type: 'command', command: HOOK_COMMAND }],
+  });
+  writeSettings(s);
+  if (!quiet) console.log('✓ Stop hook 등록 → ' + cfg.SETTINGS_FILE);
+  return true;
+}
+
+function ensureClaudeMdReference(quiet) {
+  let body = '';
+  if (fs.existsSync(CLAUDE_MD)) {
+    body = fs.readFileSync(CLAUDE_MD, 'utf8');
+  }
+  if (body.includes('claude-distill auto-references')) {
+    if (!quiet) console.log('· CLAUDE.md @reference 이미 등록됨 — 건너뜀');
+    return false;
+  }
+  // 빈 파일이면 헤더부터, 있으면 뒤에 append
+  const trailer = body.endsWith('\n') || body === '' ? '' : '\n';
+  fs.mkdirSync(path.dirname(CLAUDE_MD), { recursive: true });
+  fs.appendFileSync(CLAUDE_MD, trailer + REFERENCE_BLOCK);
+  if (!quiet) console.log('✓ ' + CLAUDE_MD + ' 끝에 @reference 추가');
+  return true;
+}
+
+function parseFlags(args) {
+  const flags = { noClaudeMd: false, quiet: false };
+  for (const a of args) {
+    if (a === '--no-claude-md') flags.noClaudeMd = true;
+    if (a === '--quiet') flags.quiet = true;
+  }
+  return flags;
+}
+
+function run(args) {
+  const flags = parseFlags(args);
+  cfg.ensureStateDir();
+  ensureHook(flags.quiet);
+  if (!flags.noClaudeMd) ensureClaudeMdReference(flags.quiet);
+  if (!flags.quiet) {
+    console.log('');
+    console.log('이제 끝입니다. 세션 끝낼 때마다 알아서 분석 + 누적합니다.');
+    console.log('확인하고 싶으면:  ' + cfg.GLOBAL_KNOWLEDGE);
+    console.log('              :  ' + cfg.GLOBAL_GOTCHAS);
+  }
+}
+
+module.exports = { run };

package/lib/store.js

@@ -0,0 +1,77 @@
+// Resolves the destination markdown file for an entry (global vs project)
+// and appends a formatted block. Files are pure markdown so users can edit
+// them by hand any time.
+
+const fs = require('fs');
+const path = require('path');
+const cfg = require('./config');
+
+function resolveTarget(entry) {
+  const isGotcha = entry.type === 'gotcha';
+  if (entry.scope === 'project' && entry.source && entry.source.cwd) {
+    const projectClaudeDir = path.join(entry.source.cwd, '.claude');
+    fs.mkdirSync(projectClaudeDir, { recursive: true });
+    return path.join(projectClaudeDir, isGotcha ? 'gotchas.md' : 'knowledge.md');
+  }
+  return isGotcha ? cfg.GLOBAL_GOTCHAS : cfg.GLOBAL_KNOWLEDGE;
+}
+
+function ensureHeader(file, isGotcha) {
+  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).
+
+`;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, header);
+}
+
+function formatEntry(e) {
+  const title = e.title || '(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(', ')
+    : '';
+  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';
+
+  return [
+    `## ${title}`,
+    `**Category**: \`${e.category}\`  · **Confidence**: ${conf}  · **Date**: ${date}`,
+    `**Source**: session \`${sessionId.slice(0, 8)}\` · project \`${project}\`${cmds}`,
+    '',
+    `**${symptomLabel}**: ${e.context || ''}`,
+    '',
+    `**${insightLabel}**: ${e.insight || ''}`,
+    '',
+    `**Basis**: ${e.basis || ''}`,
+    '',
+    `**Application**: ${e.application || ''}`,
+    '',
+    `**Tags**: ${tags}`,
+    '',
+    '---',
+    '',
+  ].join('\n');
+}
+
+function appendEntry(entry) {
+  const file = resolveTarget(entry);
+  const isGotcha = entry.type === 'gotcha';
+  ensureHeader(file, isGotcha);
+  fs.appendFileSync(file, formatEntry(entry));
+  return file;
+}
+
+module.exports = { resolveTarget, appendEntry, formatEntry };

package/lib/transcript.js

@@ -0,0 +1,148 @@
+// Transcript reader — given a session JSONL, return a compact "relevant
+// turns" array suitable for sending to the analyzer. Two strategies:
+//
+//   1. Find the latest <command-name> marker and take from there to end.
+//      (Cleanest signal — that's "what the user asked for".)
+//   2. Fallback: take the last N turns (default 30).
+//
+// Either way we strip large fields (full tool_result content, big diffs)
+// to keep the analyzer prompt under a sensible token budget.
+
+const fs = require('fs');
+const path = require('path');
+const cfg = require('./config');
+
+const DEFAULT_TAIL_TURNS = 30;
+const MAX_TURNS_HARD_CAP = 120;          // Even if a single command marker stretches 800 turns,
+                                          // we only send the last 120 to the analyzer.
+const MAX_CONTENT_CHARS = 1500;          // per-turn cap (reduced — long tool outputs were dominating)
+const MAX_TOOL_RESULT_CHARS = 400;
+const COMMAND_RE = /<command-name>\/?([\w.\-:]+)<\/command-name>/;
+
+function listSessionsForCwd(cwd) {
+  const slug = cfg.cwdToProjectSlug(cwd);
+  const dir = path.join(cfg.PROJECTS_DIR, slug);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => f.endsWith('.jsonl'))
+    .map((f) => path.join(dir, f));
+}
+
+function listAllSessions() {
+  if (!fs.existsSync(cfg.PROJECTS_DIR)) return [];
+  const out = [];
+  for (const proj of fs.readdirSync(cfg.PROJECTS_DIR)) {
+    const projDir = path.join(cfg.PROJECTS_DIR, proj);
+    let stat;
+    try { stat = fs.statSync(projDir); } catch { continue; }
+    if (!stat.isDirectory()) continue;
+    let entries;
+    try { entries = fs.readdirSync(projDir); } catch { continue; }
+    for (const f of entries) if (f.endsWith('.jsonl')) out.push(path.join(projDir, f));
+  }
+  return out;
+}
+
+function latestSessionFile() {
+  const all = listAllSessions();
+  if (!all.length) return null;
+  let best = all[0];
+  let bestM = 0;
+  for (const f of all) {
+    try {
+      const m = fs.statSync(f).mtimeMs;
+      if (m > bestM) { bestM = m; best = f; }
+    } catch {}
+  }
+  return best;
+}
+
+// Read entire jsonl, return parsed lines (skip malformed).
+function readLines(file) {
+  const txt = fs.readFileSync(file, 'utf8');
+  const out = [];
+  for (const line of txt.split('\n')) {
+    if (!line) continue;
+    try { out.push(JSON.parse(line)); } catch {}
+  }
+  return out;
+}
+
+// Trim a turn's content for the analyzer. Keeps the shape but caps long
+// strings; keeps tool_use names and tool_result first ~600 chars; drops
+// raw images.
+function compactTurn(obj) {
+  const out = {
+    type: obj.type,
+    uuid: obj.uuid,
+    parentUuid: obj.parentUuid,
+    timestamp: obj.timestamp,
+  };
+  const m = obj.message || {};
+  if (typeof m.content === 'string') {
+    out.content = m.content.length > MAX_CONTENT_CHARS
+      ? m.content.slice(0, MAX_CONTENT_CHARS) + ' …[truncated]'
+      : m.content;
+  } else if (Array.isArray(m.content)) {
+    out.content = m.content.map((c) => {
+      if (c.type === 'text') {
+        const t = c.text || '';
+        return { type: 'text', text: t.length > MAX_CONTENT_CHARS ? t.slice(0, MAX_CONTENT_CHARS) + ' …[truncated]' : t };
+      }
+      if (c.type === 'tool_use') return { type: 'tool_use', name: c.name, input_keys: Object.keys(c.input || {}) };
+      if (c.type === 'tool_result') {
+        const txt = typeof c.content === 'string'
+          ? c.content
+          : (Array.isArray(c.content) ? c.content.filter((x) => x.type === 'text').map((x) => x.text).join('\n') : '');
+        return { type: 'tool_result', text_preview: txt.slice(0, MAX_TOOL_RESULT_CHARS) };
+      }
+      if (c.type === 'image') return { type: 'image', omitted: true };
+      return { type: c.type };
+    });
+  }
+  if (m.usage) out.usage = m.usage;
+  return out;
+}
+
+function extractRelevant(file, opts) {
+  const lines = readLines(file);
+  if (!lines.length) return { source: file, turns: [], commandMarkers: [] };
+  const tailTurns = (opts && opts.tail) || DEFAULT_TAIL_TURNS;
+  // Find the last command marker — start from there.
+  let startIdx = -1;
+  const commandMarkers = [];
+  for (let i = 0; i < lines.length; i++) {
+    const obj = lines[i];
+    if (obj.type === 'user' && obj.message && typeof obj.message.content === 'string') {
+      const m = COMMAND_RE.exec(obj.message.content);
+      if (m) {
+        startIdx = i;
+        commandMarkers.push({ index: i, command: m[1], timestamp: obj.timestamp });
+      }
+    }
+  }
+  if (startIdx === -1) startIdx = Math.max(0, lines.length - tailTurns);
+  // Hard cap — protect the analyzer from a single command marker that
+  // stretches across hundreds of turns (long-running session). We keep
+  // the most recent ones since they're closest to the lessons learned.
+  if (lines.length - startIdx > MAX_TURNS_HARD_CAP) {
+    startIdx = lines.length - MAX_TURNS_HARD_CAP;
+  }
+  const slice = lines.slice(startIdx);
+  return {
+    source: file,
+    turns: slice.map(compactTurn),
+    commandMarkers,
+    totalLines: lines.length,
+    sliceFrom: startIdx,
+  };
+}
+
+module.exports = {
+  listSessionsForCwd,
+  listAllSessions,
+  latestSessionFile,
+  readLines,
+  compactTurn,
+  extractRelevant,
+};

package/lib/where.js

@@ -0,0 +1,26 @@
+// `claude-distill where` — 모든 path / 존재 여부 한 번에.
+
+const fs = require('fs');
+const path = require('path');
+const cfg = require('./config');
+
+const CLAUDE_MD = path.join(cfg.CLAUDE_DIR, 'CLAUDE.md');
+
+function exists(p) { return fs.existsSync(p) ? '✓' : '·'; }
+
+function run() {
+  console.log('CLAUDE_DIR        ' + exists(cfg.CLAUDE_DIR)        + '  ' + cfg.CLAUDE_DIR);
+  console.log('settings.json     ' + exists(cfg.SETTINGS_FILE)     + '  ' + cfg.SETTINGS_FILE);
+  console.log('CLAUDE.md         ' + exists(CLAUDE_MD)             + '  ' + CLAUDE_MD);
+  console.log('projects/         ' + exists(cfg.PROJECTS_DIR)      + '  ' + cfg.PROJECTS_DIR);
+  console.log('');
+  console.log('knowledge.md      ' + exists(cfg.GLOBAL_KNOWLEDGE)  + '  ' + cfg.GLOBAL_KNOWLEDGE);
+  console.log('gotchas.md        ' + exists(cfg.GLOBAL_GOTCHAS)    + '  ' + cfg.GLOBAL_GOTCHAS);
+  console.log('');
+  console.log('.distill/         ' + exists(cfg.STATE_DIR)         + '  ' + cfg.STATE_DIR);
+  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);
+}
+
+module.exports = { run };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "claude-distill",
+  "version": "0.2.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",
+    "distill": "bin/distill.js"
+  },
+  "main": "lib/index.js",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node test/smoke.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "claude-code-hook",
+    "anthropic",
+    "ai-coding",
+    "ai-assistant",
+    "knowledge-management",
+    "session-transcript",
+    "post-mortem",
+    "developer-tools",
+    "productivity",
+    "hook",
+    "meta-tooling",
+    "learning-tool",
+    "markdown",
+    "cli"
+  ],
+  "author": "parksubeom",
+  "license": "MIT",
+  "homepage": "https://github.com/parksubeom/claude-distill#readme",
+  "bugs": {
+    "url": "https://github.com/parksubeom/claude-distill/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/parksubeom/claude-distill.git"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "prompts",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {}
+}

package/prompts/extract.md

@@ -0,0 +1,66 @@
+# Knowledge / Gotcha Extractor
+
+You are reading a developer's session transcript with Claude Code. Your job is to extract a small set of high-signal entries that the developer will want to remember next time.
+
+There are two extraction targets, with hard rules.
+
+## KNOWLEDGE — judgment calls worth remembering
+
+A *knowledge* entry captures a *deliberate decision* the user (or you) made, with reasoning that would still be relevant the next time the same situation comes up. Pick from:
+
+- `trade_off_decision` — picked option A over B with a stated reason
+- `environment_quirk` — discovered a tool / runtime / IDE behavior that affects future choices
+- `scale_transition` — found a threshold (lines of code, traffic, dataset size) where the right answer changes
+- `tooling_insight` — figured out a tool flag, command, or workflow that solves a recurring problem
+- `performance_insight` — measured a number and identified the cause
+
+## GOTCHAS — mistakes worth not repeating
+
+A *gotcha* entry captures a *trap* the user fell into or narrowly avoided, with enough context that future sessions can avoid it. Pick from:
+
+- `api_quirk` — undocumented or counter-intuitive library / API / format behavior
+- `type_shape` — a data shape that broke an assumption
+- `concurrency_race` — async / ordering / lifecycle bug
+- `build_deploy` — build pipeline, packaging, or deploy step that bit you
+- `privacy_security` — a security issue you spotted or fixed
+- `ux_regression` — a UX pattern that regressed unexpectedly
+
+## HARD RULES
+
+1. **Bar is high.** Most sessions produce 0 entries. Empty array is a fine answer.
+2. **Exclude self-evident facts.** "JSON.parse can throw" is not a gotcha.
+3. **Exclude project-internal trivia with no transferable lesson.** "We renamed `foo` to `bar`" is not knowledge.
+4. **Exclude speculation.** Every entry must reference behavior you actually saw in the transcript. If the user said "I think X", that's not enough — there must be a confirming command output, error, or observation.
+5. **Exclude duplicates of existing entries.** Existing `knowledge.md` and `gotchas.md` content is provided as `<existing>`. If a candidate restates an existing entry, drop it.
+6. **Confidence: high / medium / low.** `high` requires a directly observed test/output. `medium` is a strong inference. `low` is a pattern you suspect but haven't fully validated.
+7. **Be specific.** "Use the right ffmpeg flags" is useless. "ffmpeg cropdetect needs `limit=32` or higher when padding RGB is dim grey, otherwise it returns the source dimensions unchanged" is useful.
+
+## OUTPUT FORMAT
+
+Strict JSON array. Each entry has these fields exactly:
+
+```json
+{
+  "type": "knowledge" | "gotcha",
+  "category": "trade_off_decision" | "environment_quirk" | "scale_transition" | "tooling_insight" | "performance_insight" | "api_quirk" | "type_shape" | "concurrency_race" | "build_deploy" | "privacy_security" | "ux_regression",
+  "title": "≤80 chars, single sentence, imperative or descriptive",
+  "context": "the situation / symptom (2-4 sentences)",
+  "insight": "the decision / trap (2-4 sentences)",
+  "basis": "the evidence — quote a command output or filename if you saw one",
+  "application": "when this applies / how to handle it next time (1-2 sentences)",
+  "tags": ["3-6 tags, lowercase-with-hyphens"],
+  "confidence": "high" | "medium" | "low",
+  "related_commands": ["/command-name", ...]   // optional
+}
+```
+
+Limit: at most 5 entries total. If there's nothing meeting the bar, return `[]`.
+
+## INPUT
+
+You will receive:
+
+1. `<existing>` — current knowledge.md + gotchas.md content (for de-duplication)
+2. `<transcript>` — relevant turns from the session
+
+Read both, then output the JSON array. No commentary, no markdown, only the JSON.