token-guard

cc-guard

Claude Code를 안전하게 만드는 원커맨드 도구. 772개의 example hook · 71건 이상의 Anthropic 공식 Issue에 대응 · 9,228+ 테스트 ·

npx @gaebalai/cc-guard

10초 만에 8개의 안전 hook을 설치한다. rm -rf / 차단, main 브랜치 push 방지, 시크릿 유출 감지, 구문 오류 자동 검출. 의존성 제로.

hook이란? Claude Code가 명령을 실행하기 전에 내용을 검사하고 위험하면 중단시키는 구조. 공항의 보안 검색대와 같다 — 탑승구(명령 실행) 앞에 체크포인트(hook)가 있어, 위험물(rm -rf 등)을 소지하고 있으면 통과시키지 않는다.

기능

명령	기능
npx @gaebalai/cc-guard	8개의 안전 hook 설치
--shield	최대 안전(stack 감지 + 권장 hook 자동 선택)
--install-example <name>	772개의 example 중 개별 설치
--examples	모든 example 일람 표시
--create "설명"	자연어로 커스텀 hook 생성
--verify	각 hook의 동작 확인
--audit	안전 스코어(0-100)
--doctor	동작하지 않는 원인 진단
--dashboard	차단 통계 대시보드
--stats	차단 통계 리포트
--lint	설정의 정적 분석
--benchmark	hook 실행 속도 측정
--diff <file>	설정 비교
--watch	차단된 명령을 실시간으로 표시
--export / --import	팀에서 설정 공유
--team	프로젝트에 커밋해 공유

56개의 CLI 명령 전체 리스트: npx @gaebalai/cc-guard --help

설치

npx @gaebalai/cc-guard

Claude Code 재시작. 완료.

차단되는 동작

동작	Before	After
rm -rf /	실행됨	차단
git push --force	실행됨	차단
git push origin main	실행됨	차단
git add .env	실행됨	차단
cat ~/.netrc	토큰 표시	차단
Python 구문 오류	알아차리지 못함	자동 감지
컨텍스트 고갈	갑작스러운 종료	단계적 경고
CLAUDE.md 규칙 소실	압축 후 무시	자동 재주입
서브에이전트의 지시 무시	v2.1.84 이후 CLAUDE.md 제외 (#40459)	hook으로 제약
읽지 않고 편집	6%→34%로 증가 (#42796)	경고

📘 token 소비가 너무 많은가? Token Checkup 무료 진단 도구로 30초 만에 자신의 소비 패턴을 확인할 수 있다. CLAUDE.md 최적화 · hook을 통한 token 제어 · 컨텍스트 관리 · 워크플로 설계 가이드는 COOKBOOK과 hook 예제를 참고한다.

알려진 제약:

• FileChanged 알림은 파일 내용을 hook의 이전에 컨텍스트로 주입한다. session 중에 .env나 credentials.json이 외부에서 변경된 경우 hook으로 차단할 수 없다(#44909). 대책: dotenv-watch로 경고를 수신하고, Claude Code 실행 중에는 기밀 파일을 편집하지 않는다.

Session 보호 hook

session의 손상이나 token 낭비를 방지하는 hook.

hook	해결하는 문제	Issue
cch-cache-guard	session 파일 읽기로 인한 cache 오염 차단	#40652
image-file-validator	가짜 이미지 파일(텍스트의 .png) 읽기 차단	#24387
large-read-guard	큰 파일의 cat에 의한 컨텍스트 낭비 경고	#41617
prompt-usage-logger	모든 prompt를 로깅해 token 소비 패턴 추적	#41249
compact-alert-notification	auto-compaction 발화 알림(token 낭비 사이클 감지)	#41788
token-budget-guard	session 비용 상한 초과 시 tool 호출 차단	#38335
session-index-repair	종료 시 sessions-index.json 재구축(--resume로 session 소실 방지)	#25032
session-backup-on-start	시작 시 session JSONL 백업(임의의 삭제로부터 보호)	#41874
working-directory-fence	CWD 밖의 Read/Edit/Write 차단(다른 프로젝트에서의 오작업 방지)	#41850
pre-compact-transcript-backup	compaction 전에 JSONL 전체 백업(rate limit 시 데이터 손실 방지)	#40352
read-before-edit	읽지 않고 편집하는 패턴을 감지해 경고(Read:Edit 비율이 70% 저하 — #42796)	#42796
subagent-error-detector	서브에이전트의 529/502/timeout 결과를 감지해 경고	#41911
subagent-identity-leak-guard	자식 에이전트가 부모의 신분을 사칭하거나 부모의 대화 이력을 누설하는 것을 예방(delegation prompt의 신분 경계 검사)	#55488
subagent-tool-allowlist-enforcer	자식 에이전트의 도구 경계를 delegation prompt로 명시하고, 부모의 검증 절차를 유도(허위 보고 예방)	#55653
subagent-spawn-verification-enforcer	자식 에이전트의 spawn 응답이 허위가 아닌지 산출물의 검증 절차로 예방	#55666
subagent-destructive-git-guard	자식 에이전트의 delegation prompt에서 destructive한 git 명령의 금지와 안전한 대체(git stash) 및 working tree 상태 확인 지시가 명시되어 있는지 검사(4/25-5/8의 3건의 동형 data-loss 예방)	#57463 / #46444 / #53765