# ContextGuard

ContextGuard는 AI 코딩·도구 에이전트를 위한 로컬 우선 컨텍스트 관리 도구 모음입니다. Claude Code 플러그인으로 먼저 시작할 수 있으며, 같은 프로젝트 로컬 가드레일을 일반 로컬 헬퍼 명령과 안내용 brief 모드 규칙 스니펫으로 다른 에이전트에도 확장합니다.

처음에는 `/context-guard:setup`을 실행하세요. 설정은 명시적이며, 프로젝트 단위로 적용되고, 되돌릴 수 있습니다. 추천 프로젝트 설정을 병합하고, 읽기 전용 컨텍스트 관리 검사 요약을 출력하며, 전역 Claude 설정은 변경하지 않습니다. 외부 AI 서비스로 작업을 위임하거나 외부에서 실행되도록 설정하지 않습니다.

## 빠른 시작

```bash
/plugin marketplace add ictechgy/context-guard && /plugin install context-guard@context-guard   # Claude Code
/context-guard:setup          # applies the recommended project-local hooks after showing a plan
/context-guard:audit          # shows where your tokens went, by tool and per turn
```

npm 사용자는 `npx @ictechgy/context-guard setup --profile recommended --plan`을 실행한 뒤 `--yes`로 적용하세요.

## 줄이려는 토큰 낭비 경로

ContextGuard는 provider prompt cache나 semantic answer cache가 아니라 로컬 컨텍스트 관리 계층입니다. 에이전트 대화에 들어가기 전에 큰 파일은 검색·심볼·줄 범위 읽기로 좁히고, 긴 명령 출력은 축약하거나 요약하며, 큰 로그는 로컬 보관 요약 기록으로 남깁니다. 또한 민감 정보처럼 보이는 값과 경로를 최대한 가리고, Bash 실패가 반복되면 전략을 바꾸도록 알리며, 제한된 가림 처리된 segment hash로 캐시 친화적 프롬프트 배치를 감사하고, 감사·벤치마크로 실제 작업의 전후 비교 근거를 남기도록 돕습니다.

## 리브랜딩 참고

Claude Code는 예전 `/claude-token-optimizer:*` 플러그인 슬래시 명령을 별칭으로 제공하지 않습니다. 설치 후에는 `/context-guard:*`를 사용하세요.

legacy `claude-*` 래퍼 이름은 이번 릴리스에서 제거했습니다. `context-guard-*` 이름을 사용하세요(마이그레이션: 접두사만 교체).

## 스킬

설치 후 Claude Code 안에서 다음 스킬을 사용할 수 있습니다.

```text
/context-guard:setup
/context-guard:optimize
/context-guard:audit
```

| 스킬 | 용도 |
| --- | --- |
| `/context-guard:setup` | 처음 적용할 때 쓰는 프로젝트 설정 마법사입니다. |
| `/context-guard:optimize` | 컨텍스트 가드레일을 점검하고 조정합니다. |
| `/context-guard:audit` | 로컬 Claude 대화 기록의 토큰·비용 집중 지점을 확인합니다. |

## 헬퍼 명령과 PATH

대표 명령은 `context-guard`이며, 기존 호환 헬퍼는 `context-guard-*` 접두사를 유지합니다. Claude Code 플러그인 스킬은 패키지에 포함된 헬퍼를 호출할 수 있지만, 일반 셸의 `PATH`에 플러그인 `bin/` 디렉터리가 자동으로 추가된다고 보장할 수는 없습니다.

`setup`은 기본적으로 패키지/체크아웃 내부 헬퍼 경로를 기록합니다. 신뢰할 수 있는 설치라고 명시한 경우에만 `--allow-path-helper-fallback`으로 `PATH` 헬퍼 대체 경로를 허용하며, 이때도 canonical 실행 파일 경로와 helper identity를 검증한 뒤 사용합니다.

Codex나 다른 터미널 기반 에이전트에서는 npm 패키지를 설치하거나 npx로 한 번만 실행할 수 있습니다. 설치 자체는 설정 파일을 변경하지 않습니다.

```bash
npm install -g @ictechgy/context-guard
context-guard doctor --root . --json  # 읽기 전용 상태 점검; 변경 없음
context-guard setup --agent codex --scope project --with-init --with-skill --plan
context-guard setup --agent codex --scope project --brief-mode standard --plan
npx @ictechgy/context-guard --version
```

짧은 `bash_reference_v1` Bash 출력 경로는 이 marketplace plugin/소스 배치에서
의도적으로 활성화되지 않습니다. 정확한 프로젝트 로컬
`@ictechgy/context-guard@0.14.0` npm 설치와
`@ictechgy/context-guard-receipt@0.4.0` 의존성이 필요하며, 그 뒤
`setup --agent claude --scope project --bash-reference-v1`로 명시적으로
활성화해야 합니다. Plugin setup은 동작하지 않는 reference flag를 설치하지 않고
legacy trim을 유지하며 경고합니다. 활성화·비활성화, 7일 handle, 상태 보존은
저장소의 배포 문서를 참고하세요.

이 저장소 루트에서는 경로를 직접 지정해 실행하세요.

```bash
./plugins/context-guard/bin/context-guard-setup --plan
./plugins/context-guard/bin/context-guard-diet scan . --json
```

로컬 개발 중 짧은 명령으로 실행하려면 현재 셸에 플러그인 bin 경로를 추가하세요.

```bash
export PATH="$PWD/plugins/context-guard/bin:$PATH"
context-guard-setup --plan
```

자주 쓰는 헬퍼는 다음과 같습니다.

```bash
context-guard-audit ~/.claude/projects --top 20 --recommend
context-guard-setup
context-guard-diet scan . --json
context-guard-artifact store --command "long-command" --json < large.log
context-guard-artifact receipt <artifact_id> --json
context-guard-artifact get <artifact_id> --lines 1:80
context-guard task-memory put --task issue-123 --source src/app.py --json < stable-context.txt
context-guard task-memory get <opaque_handle> --task issue-123 --source src/app.py --max-bytes 65536
context-guard-compress --json < large-output.txt
context-guard cost preflight --request request.json --budget-krw 3000 --json
context-guard cost observe --usage usage.json --json
context-guard cost advisory --workload advisory-workload.json --json
context-guard-trim-output --max-lines 120 -- npm test
context-guard-read-symbol path/to/file.py TargetSymbol
context-guard-sanitize-output -- rg -n "TOKEN|SECRET" .
context-guard-sanitize-output -- git diff
context-guard-pack auto --root . --query "failing tests review" --diff HEAD --manifest-out suggested-pack.json --pack-out context-pack.md --budget-bytes 12000 --json --explain --adaptive-k --adaptive-k-policy recall
context-guard-pack auto --root . --files src/app.py --query "entrypoint 검토" --top 1 --budget-bytes 12000 --json --no-artifact --apply-symbol-memory
context-guard-pack auto --root . --query "실패 테스트 검토" --top 8 --budget-bytes 12000 --json --no-artifact --apply-adaptive-k
context-guard-pack build --root . --manifest suggested-pack.json --budget-bytes 12000 --json
context-guard-pack build --root . --manifest suggested-pack.json --budget-bytes 12000 --json --no-artifact --delta-from-pack-id 0123456789abcdef0123
context-guard-pack slice --root . --path README.md --lines 1:40 --json
context-guard-cache-score --input prompt.json --provider openai --json
context-guard-tool-prune select --catalog tools.json --query "review failing tests" --top 5 --budget-bytes 12000 --json
context-guard-tool-prune defer-report --catalog tools.json --query "review failing tests" --core-top 3 --deferred-top 20 --json
context-guard-tool-prune get <receipt_id> --tool read_file --json
context-guard-statusline
context-guard-statusline-merged
```

## 헬퍼가 하는 일

모든 pack build는 기존 `pack_id`를 바꾸지 않고 렌더링된 byte의 SHA-256 `content_address`를 포함합니다. `build`와 `auto`의 선택적 `--delta-from-pack-id PACK_ID`는 private local receipt 하나만 bounded/fail-soft 방식으로 비교합니다. `rolling_delta`는 진단 전용이고 selection이나 pack 본문을 바꾸지 않으며 provider token/cost savings claim이 아닙니다. 진단은 `--json` 출력 또는 저장된 artifact receipt에서만 보고됩니다. `--no-artifact`를 쓰면 진단 보고에 `--json`이 필요하며, 기존 text stdout은 정확한 pack 본문을 그대로 유지합니다.

- **설정 마법사**는 `.claude/settings.json`을 덮어쓰지 않고 병합한 뒤, 읽기 전용 `context-guard-diet scan` 요약을 보여줍니다. 자동화에서 적용 후 검사 요약이 필요 없으면 `--no-diet-scan`을 사용하세요. `PATH` helper fallback은 기본적으로 꺼져 있으며, `--allow-path-helper-fallback`과 identity 검증을 통과해야만 사용됩니다.
- **컨텍스트 관리 스캐너**는 누락된 `permissions.deny` 가드레일, Bash 출력 축약 훅, 상태표시줄 설정, 넓은 읽기 허용, 비용이 큰 기본 모델/추론 강도, 많은 MCP 서버, 크거나 민감해 보이는 에이전트 규칙 파일, 부피가 크거나 민감해 보이는 로컬 경로에 대한 자문형 context-exclusion 추천을 확인합니다.
- **대용량 읽기 가드와 심볼 리더**는 파일 전체 읽기 전에 검색, 심볼 구간, 작은 줄 범위 읽기 순서로 에이전트를 안내합니다. Python, JavaScript/TypeScript, Go, Rust 소스 구간 읽기를 지원합니다.
- **로컬 로그 보관소**는 큰 명령 출력을 기본적으로 `.context-guard/artifacts`에 가림 처리해 저장하고, 줄 번호가 있는 top error, 중복 라인 그룹, 가림 처리된 bounded suggested query, 안정적인 `contextguard-artifact:<id>` 핸들이 담긴 `output_sandbox` 요약 기록이나 요청한 정확한 줄 범위만 반환합니다. `receipt <artifact_id> --json`은 본문 없이 핸들과 재조회 명령만 다시 출력합니다. `get`과 `list`는 리브랜딩 이전의 `.claude-token-optimizer/artifacts` 요약 기록도 읽을 수 있습니다.
- **예산 기반 컨텍스트 패커**는 우선순위가 있는 로컬 파일 근거를 렌더링된 바이트 예산 안의 Markdown pack으로 조립하고, 포함·부분 포함·누락 source 메타데이터, bounded `.context-guard/packs` 요약 기록, 안전할 때만 정확한 가림 처리 `slice` 명령, 안전하지 않을 때의 `retrieval_omitted_reason`을 남깁니다. 추가된 `auto` 하위 명령은 추천과 pack build를 한 번에 실행하고, `auto --explain`은 manifest, pack 본문, receipt, byte budget을 바꾸지 않으면서 결정적 로컬 선택/build 이유를 짧게 추가합니다. JSON explain의 bounded repo-map은 sampled byte/token-proxy tree, category-only secret risk count, signature-first hint, explain-only graph rank, 기존 `slice`/symbol 재조회 힌트를 제공하지만 pack 선택이나 provider savings claim은 아닙니다. `suggest`는 로컬 query, diff, 명시 파일, 가림 처리된 output/test-output 신호를 `build`와 호환되는 manifest로 순위화하며 네트워크·모델 호출·임베딩·provider 비용 추정은 하지 않습니다. `suggest/auto --adaptive-k`는 `--adaptive-k-policy balanced|recall|precision` 및 선택적 recall/precision proxy gate, capped selected/omitted evidence, 구조화된 source-verification hint를 제공하지만 추천값을 자동 적용하거나 manifest/pack/receipt를 바꾸지 않습니다. 명시적 `auto --apply-symbol-memory`는 안전한 direct import neighbor slice를 최대 4개 manifest에 추가하고 동일 byte budget으로 다시 build합니다. explicit/query seed의 우선순위를 보존하고 secret-risk neighbor를 제외하며 exact fallback과 닫힌 `graph_application` 근거를 남깁니다. 토큰 수는 측정된 provider token 절감이 아니라 추정 `chars_div_4` proxy입니다.
- `auto --self-financing-selection`은 기본 비활성 조합 경로로 Adaptive, task-matching Symbol, bounded one-hop Graph 순서로 ordinary-pack byte ceiling 안에서 적용합니다. caller/critical source는 대체하지 않으며 각 후보의 frozen identity, secret 판단, byte delta, exact fallback, replacement removal 또는 정직한 no-op을 기록합니다. provider savings 주장은 하지 않습니다.
- `auto --selection-plan --json`은 query, diff, output/log, symbol, self-financing 입력에서 provider-free read-only closed plan만 출력합니다. 저장한 plan은 같은 입력에 `--apply-selection-plan PATH`를 별도로 지정해야 적용됩니다. apply는 출력 전에 plan과 source identity를 다시 검증하며 incomplete scan, secret-risk/scorer-private 입력, drift, unsafe output boundary, exact recovery 누락을 fail-closed로 거부합니다.

```bash
context-guard-pack auto --root . --query "retry 수정" --diff worktree --output logs/test.txt --json --selection-plan > selection-plan.json
context-guard-pack auto --root . --query "retry 수정" --diff worktree --output logs/test.txt --json --apply-selection-plan selection-plan.json --no-artifact
```
- **Tool/MCP schema pruner**는 로컬 tool catalog를 bounded top-k 자문 리포트로 순위화하고, compact 요약 기록과 payload integrity check로 전체 가림 처리된 schema 재조회를 보존합니다. `defer-report`는 core inline tool과 deferred stub/namespace 요약을 나누고 gross deferred-schema 및 net initial-report `chars_div_4` proxy 회계를 보여주지만, deferred tool을 쓰기 전에는 전체 schema를 다시 조회해야 합니다.
- **적용형 adaptive breadth**는 명시적 `auto --apply-adaptive-k`에서만 동작합니다. 로컬 회귀 gate 통과 뒤 heuristic source를 줄이고 caller가 지정한 file/output/test-output 및 diff source는 항상 보존하며, 같은 byte budget으로 다시 build하고 `adaptive_k_application`을 기록합니다. 로컬 proxy는 provider token/cost 절감 주장을 허용하지 않습니다.
- **보수적 압축기**는 가림 처리된 stdin을 JSON, diff, 로그, 검색 출력, 코드, 산문으로 분류하고, 관측 바이트 근거와 추정 토큰 proxy를 함께 노출합니다.
- **정적 cache-score lint와 Anthropic 비용 가드**는 `context-guard-cache-score`로 로컬 prompt/request cache layout과 사용자 제공 cache write/read multiplier 기반 amortization 위험을 안내하고, `context-guard cost preflight/observe/ledger/compile`로 호출 전 비용 추정, provider usage 대조, keyed-HMAC cache 위험 기록, 안정적인 prefix 배치 안내를 제공합니다. `context-guard-receipt evaluate full-wire`는 크기가 제한된 canonical baseline/candidate request envelope를 하나의 canonical-byte ceiling으로 비교하면서 선택한 JSON pointer와 출력 토큰 예산을 보존하고 request 원문을 출력하지 않습니다. 원문 프롬프트를 저장하지 않고 Anthropic/provider prompt cache를 대체하지 않으며, 추천은 matched successful task, 비열등 quality evidence, shifted-cost accounting 없이는 hosted token/cost 절감 주장이 아닙니다.
- **Net-efficiency P0-P2 계약**은 로컬 `net-efficiency`, `fanout-plan`,
  `prefix-plan`, `prune-plan`, `shadow-policy` 평가와 task-scoped read-only
  `receipt_batch` MCP 호출을 추가합니다. 모두 provider-free·shadow-only이며
  shell/network 권한을 추가하지 않고 quality-safe matched evidence를 요구합니다.
- **출력 축약기**는 감싼 명령의 종료 코드를 보존하면서 긴 로그를 줄이고, `--digest markdown` 또는 `--digest json`으로 실행기 실패 정보, 가림 처리된 failure signature, 중복 라인 그룹, 다음 조회 제안이 담긴 요약을 만들 수 있습니다. `--artifact-receipt`를 digest mode와 함께 쓰면 sanitized 전체 출력을 로컬 artifact receipt로 저장하고 `contextguard-artifact:<id>` 핸들과 `context-guard-artifact receipt/get/search ...` 재조회 명령으로 누락된 slice를 다시 확장할 수 있습니다.
- **민감정보 가림 도구**는 검색, diff, 로그 출력에서 자격 증명 패턴, 비공개 키 블록, 인증 헤더, 자격 증명이 포함된 URL, 민감해 보이는 경로를 가립니다.
- **상태표시줄**은 모델, 컨텍스트, 비용 신호를 짧게 보여주고, 대화 기록 데이터가 있으면 캐시 읽기와 캐시 재사용 신호도 함께 표시합니다.
- **대화 기록 감사**는 usage/cost/cache bucket을 집계하고, 토큰 집중 지점, `cache_friendliness` 프롬프트 배치 신호, `cache_layout_advice` 확인/실험 우선순위를 제한된 가림 처리된 segment hash로 보고합니다. 원문 프롬프트는 출력하지 않습니다.
- **반복 실패 알림**은 Bash 실패가 반복될 때 같은 경로를 계속 재시도하지 않고 전략을 바꾸도록 안내합니다.
- **벤치마크 헬퍼**는 기준/변형 실행을 대응해 실제 토큰·비용 필드, 별도의 바이트 감소 간접 증거, 진단용 `wall_time_seconds`, `provider_cached_tokens`, provider-cache 사용 가능성 텔레메트리, report-level measurement-baseline contract, 파일 기반 `variant_prompt_files`, 선택적 run별 `self_hosted_metrics` JSONL ledger sidecar를 기록합니다. 이 sidecar는 hosted API 절감 주장에 합치지 않습니다.

### Claude Read의 정확한 적용 범위

설치되는 가드는 Claude Code `PreToolUse`의 `Read` matcher 훅입니다. 이 가드를 선택하면 setup은 기존 deny 값 중 정확히 `Read(./.env)`와 `Read(./.env.*)`만 제거하고, 비슷한 항목과 상대적 순서는 유지합니다. 훅은 제한된 대용량 파일 범위를 검사하고, root 또는 중첩 경로의 basename이 `.env`로 시작하면 차단합니다. 단, 정확히 `.env.example`, `.env.sample`, `.env.template`인 템플릿 이름은 허용하며 symlink 여부가 모호하면 차단합니다. `Glob`은 이름을 나열할 수 있습니다. `Grep`과 `Bash`는 파일 내용을 읽을 수 있고 이 훅의 범위 밖입니다. 이는 범용 `.env` 보호나 Bash 보호가 아닙니다.

훅은 symlink를 따라가지 않고 파일을 열어 같은 descriptor의 identity, size, modification time을 다시 검증합니다. 실제 Claude `Read`는 훅 반환 뒤 별도로 파일을 열기 때문에, 그 post-hook 구간의 파일 교체 가능성은 문서화된 TOCTOU 한계로 남습니다.

비용 가드의 로컬 HMAC 키는 기본적으로 `.context-guard/cost-ledger/hmac.key`에 자동 생성됩니다. 관리자가 직접 주입하는 경우 파일에는 필수 padding을 포함한 canonical URL-safe base64 32바이트 키만 정확히 들어 있어야 하며, trailing newline이나 공백은 허용하지 않습니다. 리포트는 키와 원문 프롬프트를 출력하지 않고, 로컬 ledger는 Anthropic/provider prompt cache를 대체하지 않습니다.

## brief 모드 (안내용)

brief 모드는 코딩 에이전트가 군더더기를 줄이도록 요청하되, 증거(파일 경로, 명령, 명령 출력과 오류, 코드 블록, 검증 상태, 변경 파일, 남은 과제, 주의사항)는 유지하게 돕는 에이전트 중립·안내용 규칙 스니펫을 제공합니다. 강제가 아니라 최선 노력 안내이며, 토큰·비용 절감을 **보장하지 않습니다.**

세 가지 고정 레벨(`lite`, `standard`, `ultra`)이 [`brief/`](brief/)에 있습니다. 각 레벨은 에이전트 규칙·지시 파일(`AGENTS.md`, `CLAUDE.md`, Cursor 규칙 파일, Copilot 지시 등)에 들어가는 마커 구분 블록입니다. `context-guard setup --agent codex --scope project --brief-mode standard --plan`으로 미리 보고, `--yes`로 적용하며, 제거는 `--brief-mode off`를 사용하세요. 자세한 내용은 [`brief/README.md`](brief/README.md)를 참고하세요.

## Claude 조용한 진행 설명 (안내용)

조용한 진행 설명은 기본적으로 꺼져 있는 별도의 Claude 전용 규칙입니다. 선택적 사전 설명, 도구별 진행 중계, 군더기, 반복 중간 요약은 줄이되 승인·결정, 차단 요인, 실패, 파괴적 작업·보안 경고, 필수 진행 보고, 최종 결과, 변경 파일, 검증 결과는 유지합니다.

```bash
context-guard setup --rules-only --agent claude --scope project --narration-mode quiet --plan
context-guard setup --rules-only --agent claude --scope project --narration-mode quiet --yes
context-guard setup --rules-only --agent claude --scope project --narration-mode default --yes
```

이 격리된 작업은 프로젝트 `CLAUDE.md`의 ContextGuard narration 구간만 관리하며 settings, hook 또는 다른 에이전트 파일을 읽거나 바꾸지 않고 일반 setup 작업과 함께 사용할 수 없습니다. 최종 답변의 간결성·추론 깊이와 별개인 최선 노력 규칙이며, Gate C는 모델 준수나 절감 효과를 주장하지 않습니다.

## 절감 수치를 과장하지 않습니다

이 헬퍼들은 흔히 컨텍스트를 불필요하게 키우는 원인을 줄이지만, 고정된 절감률을 보장하지 않습니다. 실제 전후 비교 증거가 필요하면 `context-guard-bench --ledger-jsonl ... --report-json ... --dashboard-md ...`로 본인 작업에서 측정하세요. `--evidence-jsonl ...`는 deterministic local replay용이며 provider-export provenance가 완전하지 않으면 public claim 불가로 표시됩니다. 토큰 절감 주장은 대응 태스크 양쪽 모두에 `primary_tokens_measured`가 있을 때만 계산하며, report의 `matched_pair_evidence`가 성공한 baseline/variant task bucket을 transform, quality gate, 측정 가능 여부, claim boundary와 연결합니다. report의 `default_matrix`는 같은 evidence에서 trimming, artifact escrow, tool pruning, cache advice, adaptive-k, optional compression을 `default-on`/`advisory`/`experimental`/`reject/rework`로 분류하지만 report 전용이며 runtime default나 hosted savings claim을 바꾸지 않습니다. report의 `public_claim_readiness`는 release/public claim의 최종 gate로, matched successful task, provider-measured primary token/cost, quality non-inferiority, shifted-cost accounting, 명시적 confidence/failure note, complete provider-export provenance가 모두 통과해야 `claim_allowed=true`가 되며 그 외 hosted savings claim은 금지됩니다. wall-time과 provider-cache 필드는 진단용 텔레메트리이지 단독 절감 증거가 아닙니다. 감사의 `cache_friendliness`, [`cache_diagnostics`](https://github.com/ictechgy/context-guard/blob/main/docs/cache-diagnostics-schema.md), `cache_layout_advice`는 관측/추론/가설/불가 경계를 둔 휴리스틱 배치·cache-read 신호와 순위화된 확인/실험이며 청구 기준이나 provider-cache 증명이 아닙니다. 벤치마크 CSV 스키마는 엄격하므로 헬퍼 업그레이드 후에는 새 CSV를 시작하거나 헤더를 마이그레이션하세요. 작업 유형별 합성 예시는 [`docs/benchmark-workflow-examples.md`](https://github.com/ictechgy/context-guard/blob/main/docs/benchmark-workflow-examples.md)에 있고, fixture-only 실험 시작 예시는 [`docs/experimental-benchmark-fixtures.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experimental-benchmark-fixtures.md)에 있습니다.

ContextGuard는 모델 토큰을 줄이기 위해 작업을 외부 AI 서비스로 전송하지 않습니다. 모든 헬퍼 명령은 로컬에서 동작합니다. 로컬 RAM/디스크 보관본은 다음에 보낼 컨텍스트를 줄이는 데 도움될 수 있지만 provider prompt cache를 대체하지 않습니다. Anthropic 배포나 청구 설명 전에는 공식 prompt caching/pricing 문서를 다시 확인하세요: https://docs.anthropic.com/en/build-with-claude/prompt-caching 및 https://platform.claude.com/docs/en/about-claude/pricing.

미래 learned, self-hosted 최적화 아이디어는 [`research/experimental-token-reduction-radar.md`](https://github.com/ictechgy/context-guard/blob/main/research/experimental-token-reduction-radar.md)에 gated experiment로 기록하며, fixture-only 시작 예시는 [`docs/experimental-benchmark-fixtures.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experimental-benchmark-fixtures.md)에 둡니다. 이 radar와 fixture는 provider가 측정한 matched-task 근거 없이 hosted API 절감을 주장하지 않습니다. Radar의 later-roadmap gate는 neural/semantic compression, trust-tiered injection-aware compression, generated visual-token reduction, broader local proxy forwarding constraint를 별도 미래 PR이 gate를 통과하기 전까지 experimental/non-shipped로 묶습니다.

## 실험 기능

`context-guard experiments` 명령과 plan 전용 lane들은 0.14.0에서 제거됐습니다. 어떤 lane도 런타임 동작을 만들지 않았습니다. 자세한 내용은 [`docs/experiments.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experiments.md)에 있습니다.

교차 에이전트 규칙 스니펫은 안내용입니다. 대상 에이전트가 반드시 따른다고 보장할 수 없으므로, 절감 주장이 필요하면 실제 전후 동작을 직접 측정하세요.

## 로컬 MCP 어댑터

`context-guard mcp`와 `context-guard-mcp`는 의존성 없는 로컬 stdio MCP 자식 프로세스를 실행합니다. 프로세스는 root와 namespace 하나로 격리되고 sanitization된 compression, 정확한 sanitization artifact fallback, 로컬 통계만 제공합니다. HTTP, 네트워크, provider, model, proxy 통합이나 client 설정 변경은 없습니다. artifact는 namespace 사이에서 접근할 수 없고 hosted token/cost 절감도 주장하지 않습니다.

설치된 Receipt companion도
`context-guard-receipt-mcp --root /absolute/repository`로 명시적으로 실행할 수
있습니다. `receipt_context` 도구는 사용자가 `eligible`이라고 명시한 상대
파일·로그를 보수적 byte router가 유리하다고 판단할 때 compact process-local
exact reference로 저장하고, 같은 live reference를 재사용하며, 한 번에 최대
65,536바이트의 exact slice를 조회합니다. 선택적 task scope와 명시적 release는
process-local context GC를 제공하고, content-free history에는 keyed digest와
결정만 남습니다. `receipt_diagnose`는 비적용 firewall/router와 prefix 재사용
scout/surgeon 안내를 제공합니다. `receipt_pack`은 같은 필수 task scope에 먼저
묶인 `receipt_context` capability만 사용해 caller 순서의 bounded multi-file
pack과 exact deferred expansion을 만들고, task-scoped
`receipt_tool_select` profile은 하나의 안정적인 catalog bundle을 재사용하며
drift를 거부합니다. 명시적 private `--state-dir`는 authenticated
advisory `receipt_twin`만 활성화합니다. 자동 등록, prompt 가로채기, capability의
재시작 후 지속 저장, provider 호출, hosted 절감 주장은 하지 않습니다.

## 로컬 배포 테스트

마켓플레이스 저장소 루트에서 실행합니다.

```bash
claude --plugin-dir ./plugins/context-guard
```

그다음 Claude Code 안에서 실행합니다.

```text
/context-guard:setup
```

마켓플레이스 설치 테스트:

```text
/plugin marketplace add ./
/plugin install context-guard@context-guard
```

## 라이선스

Copyright 2026 jinhongan. Apache License 2.0으로 배포됩니다. [LICENSE](LICENSE)와 [NOTICE](NOTICE)를 참고하세요.