Claude Code Mods 사용법: context와 편집 replay를 보되 신호를 검수로 착각하지 않기

Claude Code session이 길어지면 서로 다른 두 질문이 생깁니다. 방금 turn에서 context가 얼마나 늘었는지, 그리고 Claude가 어떤 file-edit operation을 호출했는지입니다. Anthropic playground에는 각 질문에 맞는 sample이 있습니다. **Token Weather**는 main session의 context usage를 표시하고, **Replay Theater**는 마지막 편집 turn에서 발생한 file-edit call을 순서대로 보여 줍니다.

가장 중요한 경계는 두 도구가 관측 도구이지 acceptance test가 아니라는 점입니다. Context percentage는 남은 quota, 비용, task 완료를 뜻하지 않습니다. Replay에 edit가 보인다고 해서 사용자가 승인했고, tool이 성공했으며, final file에 그대로 남았다는 뜻도 아닙니다.

지금 답하려는 질문에 따라 Mod를 고르기

질문	먼저 load할 Mod	알 수 있는 것	증명하지 못하는 것
Main context window가 얼마나 찼고 최근 turn에서 급격히 늘었는가?	Token Weather	Context tokens, window size, percentage, 12-turn trend	구독 잔여량, 실제 charge, 남은 request 수, task 완료
마지막 편집 turn에서 어떤 Edit, Write, MultiEdit가 호출됐는가?	Replay Theater	File, tool, 국소적인 before/after text, 짧은 diff	승인, tool 성공, final disk state, test 통과

진단할 때는 한 번에 하나만 load하세요. 두 sample 모두 AbovePrompt에 그릴 수 있습니다. README는 이 band가 공유되므로 다른 Mod도 사용하면 하나만 보일 수 있다고 설명합니다.

실행 전에 version과 신뢰 경계를 확인하기

현재 sample README는 Claude Code 2.1.287 이상과 terminal을 요구합니다. 먼저 client version을 확인합니다.

claude --version

이 Mods는 Anthropic DevRel playground의 examples입니다. Repository는 이를 현재 상태 그대로 제공하며, Claude Code, API, model 변화 뒤에도 계속 동작한다는 지원이나 보장을 하지 않습니다. 실행 전에 선택한 directory의 README.md, .claude-plugin/plugin.json, hooks/hooks.json, hooks module을 최소한 읽으세요.

Mod는 사용자 권한으로 실행됩니다. “UI만 그린다”는 보안 경계가 아닙니다. 첫 시도는 --plugin-dir로 한 session에만 load하는 편이 좋습니다. 해당 Claude Code process를 닫으면 실험이 끝나므로 진단용 sample이 영구 설치로 바뀌지 않습니다.

Official sample을 clone하고 선택한 Mod를 validate하기

git clone https://github.com/anthropics/claude-code-playground.git
cd claude-code-playground/claude-code/mods

Repository를 내려받았다고 구조가 valid한 것은 아닙니다. Session을 시작하기 전에 정확한 directory를 검증합니다.

Token Weather:

claude plugin validate ./token-weather
claude --plugin-dir ./token-weather

Replay Theater:

claude plugin validate ./replay-theater
claude --plugin-dir ./replay-theater

validate가 error를 내면 멈추고 지정된 manifest, hooks configuration, module을 복구하세요. Claude Code가 잘못된 package를 안전하게 무시할 것이라고 가정하고 진행하지 마세요. 새 session에서는 /plugin으로 무엇이 load됐는지 확인할 수 있습니다. 실제 동작 신호는 그다음입니다. Token Weather는 main-loop turn이 끝난 뒤 업데이트돼야 하고, Replay Theater는 실제 file edit call이 있었던 turn이 끝난 뒤 entry가 나타나야 합니다.

Token Weather는 context telemetry이지 청구서가 아니다

Token Weather는 각 main-loop turn이 끝난 뒤 $.session.usage()를 호출하고 context의 tokens, window, percent를 읽습니다. Prompt 위에 한 줄을 그리고 최근 12개 reading과 마지막 turn의 증가량을 표시합니다.

각 field의 의미는 다음과 같습니다.

• tokens: 마지막 response가 참조한 input context로, uncached, cache-written, cache-read input tokens를 모두 포함;
• window: session model의 context window;
• percent: tokens / window.

첫 response 전 0%는 정상입니다. 아직 usage를 보고한 response가 없기 때문입니다. 표시는 turn 실행 중 계속 변하지 않고 완료 뒤 한 번 업데이트됩니다. Subagent turn은 별도의 main-loop reading을 만들지 않습니다.

Compaction 알림과 percentage가 다른 이유

Token Weather는 전체 context window를 분모로 사용합니다. Claude Code의 auto-compact 알림은 더 낮은 compaction point를 기준으로 하므로 두 percentage가 다를 수 있습니다. Official sample screenshot에서는 Token Weather가 81%, client 알림이 90%였습니다. 이는 sample 조건에서 두 scale이 다름을 보여 주는 예일 뿐, 자신의 session에서 숫자를 일치시켜야 한다는 뜻이 아닙니다.

History bar는 현재 표시된 값 중 가장 큰 reading을 기준으로 한 상대값입니다. Absolute percentage가 낮아도 bar 변화가 크게 보일 수 있습니다. 절대값은 percentage와 token count로 판단하세요. Session 시작이나 plugin reload 시 history가 reset됩니다.

Token Weather로 내릴 수 있는 결론

“최근 몇 turn 동안 main session의 input context가 크게 증가했다”라고 말할 수 있습니다. “계정에 19%가 남았다”, “이 turn 비용은 얼마다”, “task가 끝났다”라고는 말할 수 없습니다. Cache는 billing 처리를 바꾸지만 cached input도 context 공간을 차지합니다. Balance, charge, request status는 provider record에서 확인하세요.

Replay Theater로 편집 시도를 확인하기

Load한 뒤 실제로 files를 바꾸는 task를 요청하고 turn이 끝날 때까지 기다립니다. Hint가 나타나면 replay를 엽니다.

/replay

또는 ctrl+x, Tab으로 band에 focus한 뒤 r을 누릅니다. Panel에서는:

Key	동작
n	다음 step
p	이전 step
c 또는 Escape	닫기

각 step은 file, tool, 추가/삭제 line 수, 짧은 diff를 보여 줍니다. Sample은 step당 표시를 12 lines로 제한합니다. Edit는 전체 file이 아니라 old_string과 new_string을 비교하며 line number를 보여 주지 않습니다. Write는 호출 직전 disk의 기존 내용을 읽지만 400 lines를 넘는 file은 완전한 line matching을 하지 않습니다.

Replay에 나온 edit가 final file에 없을 수 있는 이유

Replay Theater는 call을 전달하기 전에 기록합니다. 사용자가 거부한 edit나 실패한 tool call도 replay에 나타날 수 있습니다. 이후 call이 이전 변경을 덮어쓰거나 되돌릴 수도 있습니다.

Replay는 현재 session memory에만 보관됩니다. Claude Code restart 또는 plugin reload 시 사라집니다. 다음 turn에 edit가 없으면 이전 replay가 유지됩니다. “Claude가 무엇을 시도했는지” 이해하는 데 사용하고 final repository snapshot으로 보지 마세요.

최종 검수는 실제 files에서 하기

Replay Theater 표시와 관계없이 repository에서 끝내야 합니다.

git status --short
git diff --stat
git diff -- path/to/file
git diff --check

git status --short로 실제 추가, 수정, 삭제를 확인합니다. git diff --stat으로 예상보다 넓은 change scope를 찾습니다. Important file은 12-line replay excerpt가 아니라 전체 diff를 읽습니다. git diff --check로 whitespace error를 확인하고, changed files와 직접 관련된 가장 작은 test, type check, build를 실행하세요.

Acceptance criteria는 관측 가능한 결과여야 합니다. “Target function이 rename됐고, 모든 reference가 update됐으며, 관련 unit test가 통과하고, unrelated file이 바뀌지 않았다”는 판정할 수 있습니다. “Replay에 green step 5개가 보였다”는 검수 조건이 아닙니다.

실제 usage는 provider request record에서 확인하기

Token Weather는 context가 얼마나 찼는지 보여 주지만 API bill을 계산하지 않습니다. 어떤 API provider든 time과 model로 해당 request를 찾은 뒤 status, input/output tokens, 적용되는 cache tokens, recorded charge를 확인합니다.

Claude Code의 API route로 BetterToken을 쓰는 경우, 현재 페이지는 model, time, token counts, cache usage, final cost, status가 한 request record에 함께 남는다고 설명합니다. 실제 API usage는 그 record로 확인하세요. 이것이 BetterToken이 Mods를 제공하고, 완전한 prompt/response를 저장하거나 code change를 자동 승인한다는 뜻은 아닙니다. 연결 방법은 BetterToken Claude Code 가이드에 있습니다.

가장 짧은 순서로 문제 해결하기

claude plugin validate 실패

Validator가 지목한 정확한 file과 field를 읽습니다. 현재 directory가 claude-code-playground/claude-code/mods인지, download tool이 hidden file 이름을 바꾸지 않았는지, checkout이 온전한지 확인하고 launch 전에 다시 validate합니다.

Token Weather가 안 보이거나 0%에 머무름

VS Code chat panel만 보지 말고 terminal을 사용하세요. Version 2.1.287 이상인지, 올바른 Mod가 current session에 load됐는지 확인합니다. Normal request를 보내고 main-loop turn이 끝날 때까지 기다립니다. 첫 response 전 0은 정상입니다.

Replay Theater hint가 안 나타남

Turn이 Edit, Write, MultiEdit를 호출했고 완료됐는지 확인합니다. Files 읽기, 질문 답변, Bash command만 실행한 경우에는 기록할 file-edit step이 없습니다.

Replay와 git diff가 다름

실제 files를 신뢰하세요. Edit가 거부되거나 실패했을 수 있고, 이후 call이 바꿨을 수 있으며, panel은 국소 excerpt만 보여 주거나 restart/reload로 memory state가 달라졌을 수 있습니다. 전체 diff와 targeted tests로 다시 판단합니다.

두 Mods가 함께 안 보임

하나를 disable하고 다른 하나만 load한 새 session을 시작합니다. 둘 다 AbovePrompt를 공유하므로 두 번째 band가 안 보인다는 사실만으로 package가 깨졌다고 판단할 수 없습니다.

신뢰할 수 있는 최소 loop

Context 증가를 보고 싶으면 Token Weather, 어떤 file-edit call이 있었는지 알고 싶으면 Replay Theater를 고르세요. Load 성공은 첫 단계, meter나 replay가 보이는 것은 두 번째 단계입니다. 세 번째는 항상 실제 files를 확인하고 가장 작은 관련 검증을 실행하며, usage가 중요하면 provider request record를 대조하는 것입니다. 그래야 process visibility가 verified result로 바뀝니다.