English | 한국어
Claude Code 세션에서 컨텍스트 창을 무엇이 채우는지, 같은 정보가 왜 다시 들어오는지, 컴팩션이 무엇을 남기고 잃었는지 보여 주는 mod. 관찰만 한다: 행·도구 호출·컴팩션을 바꾸지 않는다.
/plugin marketplace add YeonwooSung/my-claude-code-mods
/plugin install context-inspector@my-claude-code-mods
Claude Code 2.1.287 이상(mods 기본 활성화). 그보다 오래된 빌드는 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1.
| 명령 | 내용 |
|---|---|
/context-inspect [overview|occupants|rereads|similar|compactions|efficiency|advice] [--agents] |
텍스트 보고서. 기본은 main 컨텍스트의 overview, --agents는 서브에이전트 포함 |
/context-pane |
실시간 패널(터미널, 데스크톱 앱) |
/context-export |
원문 없이 메타데이터만 JSONL로 저장: <outputDir>/<sessionId>/context-<load>-<n>.jsonl |
상태줄: ctx 62% · waste≈8.1k (창 점유율은 측정값, 낭비는 추정). waste는 지금 창에 남아 있는 낭비다 — 컴팩션이 중복 사본을 지우면 줄어든다. 세션 전체의 재읽기 비용은 /context-inspect rereads의 session ≈…에 남는다.
| 등급 | 예 |
|---|---|
| measured | 요청마다 API가 보고한 입력 토큰(uncached + cache read + cache write), 컴팩션 전/후 토큰 |
| observed | 대화에 들어온 행의 문자 수·해시, 컴팩션 전/후 메시지 집합 |
estimated (≈) |
항목별 토큰 = 문자 수/4(이미지 1,500) × 보정 계수 k (측정된 입력 증가량으로 0.5–2.0 사이에서 보정; 한계에 걸리면 보고서에 (clamped)) |
모델 내부의 토큰별 주의(attention)나 정확한 점유율은 외부에서 보이지 않으므로 주장하지 않는다.
- 점유: 현재 창에 남은 항목을 범주(도구 이름,
attachment:<name>, prompt/response)와 대상(파일, 명령)별로. - 재읽기: 같은 파일의 두 번째 이후 읽기를 분류한다 —
engine-deduped(엔진이 "unchanged" 안내로 대신함),restored(컴팩션 후 엔진이 다시 붙임),different-range,after-edit,after-compaction,changed-externally,unchanged-live(이전 사본이 아직 창에 있음 = 순수 낭비). - 유사 출력: 같은 해시(정확) 또는 64비트 SimHash 해밍 거리 ≤ 3(근사). 단어 3-shingle 기반 어휘 유사도이며 의미(임베딩) 유사도가 아니다. 숫자는
#로 접어 실행 시간만 다른 테스트 출력도 묶인다. - 컴팩션: 컴팩션 전 대화에서 편집 파일·읽은 파일·오류·사용자 식별자를 뽑아, 요약과 유지된 메시지에 남았는지 본다. 잃은 편집 파일과, 컴팩션 때문에 다시 읽은 양(reflow)을 보고한다.
- 효율: 메인 턴별 측정 입력 증가량 대비 변경 라인 수(Edit/MultiEdit/Write/NotebookEdit). 편집 없이 커진 턴은 "탐색 턴"으로 표시만 한다(탐색은 결함이 아니다).
- 추천: 무변경 재읽기, 큰 파일 통째 읽기, 긴 명령 출력, 반복 출력, 컴팩션이 잃은 편집 파일, 컴팩션 후 재유입, 긴 서브에이전트 결과, 호출되지 않은 MCP 서버, 큰 메모리 파일. 각 추천에 근거와 ≈절감량이 붙는다.
| 키 | 기본 | 뜻 |
|---|---|---|
outputDir |
~/.claude/context-inspector |
/context-export 위치 |
toastAdvice |
true |
high 추천이 처음 생길 때 세션당 한 번 토스트 |
한 줄에 JSON 하나: meta, item(seq, ctx, turn, door, category, target, chars, est, hash, simhash, born, epoch, live …), edit, sample, compaction, summary.
원문은 없다. 파일 외 대상(명령·패턴·URL·에이전트 설명)은 알려진 비밀값 형식을 마스킹한 후 200자로 자른다. 비밀값 환경변수 할당, Authorization/Bearer 인증정보, --password·--token·--api-key·--secret 옵션, -key·-token·-secret으로 끝나는 헤더, URL 비밀번호, curl -u·--user 인증정보, mysql -p 비밀번호와 JSON의 일반적인 자격증명 필드를 마스킹한다. 셸 따옴표로 감싼 헤더의 이스케이프된 따옴표는 값의 일부로 처리한다. 파일 경로는 그대로 남는다. 모든 비밀값을 탐지하는 것은 아니므로 공유 전에 내보내기 파일을 검토해야 한다. 업데이트해도 기존 내보내기 파일은 소급 마스킹되지 않는다. 이전 파일을 검토하거나 삭제하고, 실제 인증정보가 노출됐다면 교체해야 한다.
컴팩션 엔티티 중 오류와 사용자 식별자, 그리고 항목 내용은 해시(솔트 없음, 짧은 값은 추측으로 확인 가능)로만 남는다 — 익명화가 아니다.
summary에는 wasteEst(지금 창), currentWasteEst·sessionRereadEst(재읽기 낭비: 지금 창 / 세션 누적)가 함께 들어간다.
| 환경 | 동작 |
|---|---|
| 터미널 | 상태줄, 패널, 토스트, 명령 모두 |
| VS Code 채팅 패널 | 훅과 명령 텍스트만(mod의 그림은 표시되지 않음) — /context-inspect가 기본 출력 |
claude -p |
기록만; 명령은 -p "/context-inspect"로 실행 가능 |
- 리로드·재개·
/clear시 원장을 비우고$.session.messages()로 메인 대화만 복구한다(attachment, 서브에이전트, 시간 정보 없음)./clear는session.start없이session.end(reasonclear)로 알아챈다. - 복구는 그 뒤 한 번, 지연 실행되며 아직 prompt/response가 기록되지 않았을 때만 돈다. 그 전에 먼저 들어온 도구 결과는 tool_use_id로 알아보고 다시 넣지 않는다.
- 복구된 prompt/response 항목에는 엔진 핸들이 없다(
$.session.messages()가 주지 않는다). 그래서 리로드 후 첫 컴팩션은 이들을 전부 "버려진 것"으로 센다. 도구 결과는 tool_use_id로 계속 대응된다. - 원장 상한 20,000 항목(넘치면 창 밖 항목부터 버림).
- 컴팩션 보존 판정은 문자열 포함 여부다(파일은 basename도 인정) — 요약이 다른 말로 바꿔 쓴 것은 잃은 것으로 센다.
- 유사도 버킷은 밴드 값마다 서로 다른 대표를 최대 256개까지만 보관·비교한다(수천 개의 거의 같은 출력도 대표끼리는 묶인다).
- 내보내기 파일 이름은 항상
-<n>으로 끝난다(파일 하나면context-<load>-1.jsonl). 같은 로드 안에서/context-export를 다시 실행하면 그 로드의 파일을 전체 새 스냅샷으로 덮어쓴다. - large-read·large-bash·agent-verbose·reread-unchanged 같은 추천은 세션에서 일어난 모든 일을 대상으로 하며(습관 추천), 이후 컴팩션이 지운 출력도 포함한다. 상태줄의 waste와는 다르다.
- 원장이 상한에 닿아 항목을 버리면, 버린 항목에 걸친 보정 구간은 k 계산에서 뺀다.
보고서·패널·표시 문자열은 지원하는 자격증명 형식을 마스킹한 뒤 자른다. 분석과 실제 재실행 입력은 보존하며, 기존 로그나 스냅샷 파일 내용은 소급 변경하지 않는다.
CLAUDE292=~/.vscode/extensions/anthropic.claude-code-2.1.292-darwin-arm64/resources/native-binary/claude
"$CLAUDE292" plugin test context-inspector
cp -R agent-profiler/.claude-plugin/types context-inspector/.claude-plugin/types # once, for tsc
npx -y -p typescript@5 tsc -p context-inspector --noEmit
"$CLAUDE292" plugin validate context-inspector중복 출력은 전체 내용의 해시로 exact를 판정하며, 컨텍스트별로 비교·낭비를 집계합니다. 262,144자 또는 정규화 후 20,000단어를 넘는 출력은 exact 비교만 수행합니다. 컴팩션의 문자열 보존은 관련 결정이나 제약의 의미까지 보존되었다는 뜻이 아닙니다.