Context Inspector: Claude Code 컨텍스트 낭비 찾기

Context Inspector는 Claude Code 컨텍스트 낭비를 찾아 주는 커뮤니티 모드로, 작성자는 YeonwooSung(my-claude-code-mods)입니다. 대화에 들어오는 모든 것(프롬프트, 응답, 도구 결과, 첨부)의 장부를 만들어 세 가지 질문에 답합니다. 지금 창을 무엇이 채우고 있는지, 같은 정보가 왜 계속 다시 들어오는지, 압축이 무엇을 남기고 무엇을 잃었는지입니다.

ctx 62% · waste≈8.1k 같은 상태 줄을 추가하며, 퍼센트는 실측값이고 낭비는 추정값입니다. 명령도 세 개 추가합니다. /context-inspect는 개요, 점유 항목, 재읽기, 유사 출력, 압축, 효율, 조언 섹션이 있는 텍스트 보고서를 출력합니다. /context-pane은 실시간 패널을 엽니다. /context-export는 장부를 메타데이터만 담은 JSONL로 저장합니다.

분석은 구체적입니다. 파일 재읽기는 이전 사본이 아직 창에 남아 있는 경우(순수한 낭비), 편집 뒤, 압축 뒤 등으로 분류됩니다. 거의 같은 도구 출력은 의미가 아니라 단어 기반 SimHash로 묶습니다. 압축 뒤에는 편집하거나 읽은 파일, 오류, 사용자 식별자가 요약에 아직 나오는지 확인합니다. 작성자의 README는 Claude Code 2.1.287 이상을 요구합니다.

녹화에서는 작은 데모 프로젝트에서 이 모드를 불러온 Claude Code를 실행하고, Claude에게 README.md를 읽고 프로젝트가 무엇인지 한 문장으로 말해 달라고 요청합니다. 턴이 끝나면 하단에 context-inspector: ctx 4% · waste≈0이 표시됩니다. 그런 다음 /context-inspect를 실행합니다. 보고서에는 살아 있는 토큰(17개 항목에 약 6.2k), 카테고리별 주요 점유 항목(스킬 목록, MCP 안내, 지연 로드 도구 첨부), 재읽기, 유사 출력, 압축, 효율, 조언이 나옵니다. 이 짧은 세션에서는 두 번 읽힌 파일이 없으므로 낭비는 0이고 조언란에는 눈에 띄는 것이 없다고 표시됩니다.

설치 블록의 방법 중 아무거나 사용하세요. 모두 작성자 자신의 마켓플레이스에서 바로 설치합니다. 상태 줄은 다음 세션 시작 후 첫 턴이 끝나면 나타납니다.

모듈은 hooks/register.tsx의 register 함수 하나로, 이벤트를 감싸서 그대로 다음으로 넘깁니다. 모든 기록 단계는 자체 오류를 삼키는 도우미를 거치므로 인스펙터가 세션을 망가뜨릴 수 없습니다. 도구 호출은 실행 전후에 기록되고 결과는 받은 그대로 반환됩니다.

on('tool.call', async ($, e, next) => {
  const id = e.tool_use_id
  if (id !== undefined) safe(() => ingestToolCall(ledger, id, String(e.tool), e.agentId, e as unknown as Record<string, unknown>))
  const answer = await next(e)
  if (id !== undefined) safe(() => ingestToolResult(ledger, id, answer))
  return answer
}).catch(($, e, next) => next(e))

이 발췌는 hooks/register.tsx에서 가져왔습니다. 행은 session.append로, 실측 요청 크기는 turn.step으로, 압축은 session.compact로 들어옵니다. 매 턴이 끝나면 turn.complete가 다시 그리기를 하나 큐에 넣고, $.session.usage()를 읽어 상태 줄을 씁니다. hooks/core/의 분석 코드는 로컬 import만 쓰는 순수 TypeScript이며 장부는 20,000개 항목으로 제한됩니다.

/config에 옵션이 두 개 있습니다. outputDir은 /context-export가 쓰는 위치이며 비워 두면 ~/.claude/context-inspector입니다. toastAdvice(기본 켜짐)는 심각도 높은 권장 사항이 처음 나타날 때 세션마다 한 번 토스트를 보여 줍니다. 명령은 인자를 받습니다. /context-inspect advice는 한 섹션만 보여 주고 --agents는 서브에이전트를 포함합니다.

실행하기 전에 플러그인이 실행할 수 있는 모든 파일을 읽었습니다. 매니페스트, hooks/hooks.json, hooks/register.tsx, 그리고 마스킹 규칙을 포함한 hooks/core/ 전체입니다. package.json, 설치 스크립트, 바이너리, 번들된 코드는 없고 import는 로컬 파일뿐입니다.

• 네트워크, 프로세스, 데몬, 텔레메트리: 모두 없습니다. fetch도 셸 명령도, Claude Code가 종료된 뒤 계속 실행되는 것도 없습니다.
• UI 변경: 상태 줄, 토스트, 패널. 명령 추가: 위의 세 가지.
• 모든 도구 호출과 행을 관찰합니다(tool.call, session.append, turn.step, session.compact). 게이트형 훅이지만 각각 다음 핸들러의 결과를 그대로 반환하고 .catch 대비책이 있어, 아무것도 차단하거나 바꾸지 않습니다. 또한 validate는 조직이 Claude Code를 관리하는 환경에서 개인이 설치한 플러그인의 session.compact 훅은 조직이 관리 설정에 올리지 않는 한 실행되지 않는다고 알려 줍니다.
• 파일 쓰기: /context-export를 실행할 때만 $.fs.write로 <outputDir>/<세션 id>/context-<load>-<n>.jsonl에 씁니다. 기본 위치는 ~/.claude 안의 플러그인 전용 하위 폴더입니다. ~를 풀기 위해 HOME을 읽습니다. 파일 경로는 그대로 내보내지고 다른 대상은 가능한 범위에서 마스킹됩니다. 작성자는 공유하기 전에 내보낸 파일을 검토하라고 안내합니다.
• 프롬프트 영향: 발견하지 못했습니다. 프롬프트나 도구 결과에 텍스트를 주입하지 않으며, 조언은 사용자에게만 표시됩니다.
• 외부 요구 사항: 없음. 라이선스: Apache-2.0, 저장소 루트에 LICENSE 파일이 있습니다.

claude plugin validate는 오류와 경고 없이 위의 참고 사항만 보고했습니다. 작성자의 테스트 102개가 Claude Code 2.1.303에서 통과했습니다.

macOS의 Claude Code 2.1.303에서 확인했습니다(validate와 테스트). 상태 줄이 보이지 않으면:

• claude --version이 2.1.287 이상인지 확인하세요.
• 턴이 한 번 끝났는지 확인하세요. 상태 줄은 turn.complete 뒤에 그려집니다.
• 상태 줄이 없어도 /context-inspect는 보고서를 출력하므로, 모드가 로드되었는지 확인하는 데 쓸 수 있습니다.
• VS Code 채팅 패널에서는 훅과 명령 텍스트만 동작하므로 /context-inspect를 사용하세요.

README에 적힌 알려진 한계: 다시 불러오기, 재개, /clear 뒤에는 장부가 처음부터 시작되며, 압축 뒤 생존 여부는 부분 문자열 일치로 판단하므로 바꿔 쓴 내용은 사라진 것으로 셉니다.