@ictechgy/context-guard 0.4.0

package/README.md

@@ -0,0 +1,353 @@
+# ContextGuard
+
+ContextGuard is a local-first context-hygiene toolkit for AI coding and tool agents. It ships as a Claude Code plugin first — install once, apply per project, reverse if needed. The same guardrails for noisy command output, large file reads, repeated failures, likely-secret values, and usage measurement extend to other agents through local helper commands and advisory brief-mode rule snippets.
+
+- Korean documentation: [`README.ko.md`](README.ko.md)
+- Static landing page: [GitHub Pages](https://ictechgy.github.io/context-guard/) ([source](docs/index.html))
+
+## TL;DR
+
+Install and activation are separate. Installing ContextGuard only puts local helpers or Claude plugin skills in reach; configuration changes happen later through an explicit setup command.
+
+| If you use... | Install | Activate |
+| --- | --- | --- |
+| Claude Code | `/plugin marketplace add ictechgy/context-guard` then `/plugin install context-guard@context-guard` | Run `/context-guard:setup` inside the project. |
+| Codex CLI or any terminal-first agent | `npm install -g @ictechgy/context-guard` or one-shot `npx @ictechgy/context-guard ...` | `context-guard setup --agent codex --scope project --with-init --with-skill --plan`, then rerun with `--yes`. |
+| Other rule-file agents | npm/npx install above | `context-guard setup --agent gemini,cursor,windsurf,cline,copilot --scope project --with-init --plan`, then apply only the agents you want. |
+| macOS/Homebrew users | planned release path: `brew tap ictechgy/contextguard && brew install context-guard` | Same `context-guard setup ...` commands after install. |
+
+Common commands:
+
+```bash
+npm install -g @ictechgy/context-guard
+npx @ictechgy/context-guard --version
+context-guard setup --agent codex --scope project --with-init --with-skill --plan
+context-guard setup --agent claude --scope user --plan
+```
+
+Project scope is the default. User-level setup is opt-in, requires an explicit agent for writes, records backups/rollback metadata, and never runs during package installation.
+
+ContextGuard is intentionally conservative about savings claims. It reduces common sources of context bloat and provides benchmark tooling so you can measure real before/after results on your own tasks. It does **not** promise a fixed token or cost reduction for every repository.
+
+## Claude Code first, other agents too
+
+ContextGuard ships as a Claude Code plugin, and that is still the fastest path to value. Once installed, the same local-first guardrails can be reused by other AI coding and tool agents through:
+
+- **Local helper commands** (`context-guard-*`) that run as plain shell commands, independent of any specific agent.
+- **Advisory brief-mode rule snippets** you install into an agent's own instruction file (`AGENTS.md`, `GEMINI.md`, `.cursorrules`, Copilot instructions, and similar rule files) and remove by deleting the marker-delimited block.
+- **Dry-run cross-agent setup** that writes only local files, backs up before changing anything, and applies only with explicit approval.
+
+Current setup surfaces:
+
+| Agent or tool | ContextGuard surface |
+| --- | --- |
+| Claude Code | Native plugin setup for project-local hooks, deny rules, and statusline configuration. |
+| OpenAI Codex CLI | Advisory `AGENTS.md` rule block plus optional project skill at `.agents/skills/context-guard/SKILL.md`. |
+| Gemini CLI | Advisory `GEMINI.md` rule block. |
+| Cursor | Advisory project-rule block, usually `.cursorrules`. |
+| Windsurf | Advisory `.windsurf/rules/contextguard.md` rule block. |
+| Cline | Advisory `.clinerules` rule block, with file/directory handling. |
+| GitHub Copilot Coding Agent | Advisory `.github/copilot-instructions.md` rule block. |
+| OpenCode, ForgeCode, or unknown agents | Manual shell-helper usage with local evidence; no automatic hooks. |
+
+## How ContextGuard reduces token waste
+
+ContextGuard does not make the model cheaper by itself. It reduces avoidable context before it reaches an AI coding agent, then gives you signals to measure whether that helped.
+
+| Waste path | ContextGuard guardrail |
+| --- | --- |
+| Whole-file reads for one function | Suggest search, symbol slices, bounded outlines, and small line ranges before a full read. |
+| Long test, build, search, or diff output | Trim output, emit structured digests, or store large logs locally and return compact receipts. |
+| Repeated failing commands | Warn after repeated Bash failures so the agent changes strategy before more stale logs enter context. |
+| Secret-like or noisy terminal output | Apply best-effort, pattern-based redaction for common credential patterns and sensitive-looking paths before output is copied into context. |
+| Unknown token/cost hotspots | Surface statusline signals, transcript audits, and matched benchmark reports for before/after evidence. |
+| Volatile context before stable prompt prefixes | Audit bounded redacted prompt-segment hashes and flag likely cache-unfriendly prompt layouts without exposing raw prompt text. |
+| Large tool/MCP catalogs for one narrow task | Rank a local tool catalog into a bounded top-k schema report while keeping full sanitized schemas retrievable from local receipts. |
+
+## How it fits with caching and compression tools
+
+ContextGuard is complementary to provider and semantic caches, and adjacent to prompt compression. It focuses on **not sending unnecessary files, logs, or output in the first place**.
+
+| Tool category | Saves by | ContextGuard relationship |
+| --- | --- | --- |
+| Provider prompt/context caching | Reusing stable prompt prefixes. | Complementary; ContextGuard helps keep the changing tail of context smaller and cleaner, and `context-guard-audit` can flag likely volatile prefix layouts. |
+| Semantic response cache | Reusing answers to identical or similar requests. | Complementary; ContextGuard does not serve cached AI answers. |
+| Prompt/context compression | Shortening text that is already selected for the model. | Adjacent; ContextGuard trims and summarizes local output, but does not promise lossless semantic compression. |
+| Experimental learned/multimodal/self-hosted techniques | Compressing prompts, reducing visual evidence, or optimizing self-hosted inference internals. | Tracked only in the experimental radar until matched benchmarks prove quality-preserving value; not a hosted API savings claim. |
+| ContextGuard | Avoiding unnecessary files, logs, repeated failures, and noisy output before they enter agent context. | Local guardrails, reversible artifacts, and measurement. |
+
+Related patterns that informed the design:
+
+| Approach | What it emphasizes | ContextGuard relationship |
+| --- | --- | --- |
+| Compression-first | Shortening text already selected for the model, often with lossy transforms. | ContextGuard prefers local artifact storage with exact slice retrieval over lossy one-way compression; you can get the original back. |
+| Terse-output rulesets across agents | Installing brief-mode output rules into many agents at once. | ContextGuard offers advisory brief-mode snippets and dry-run cross-agent setup — opt-in per project, no guaranteed savings claimed. |
+| ContextGuard | Avoiding unnecessary files, logs, and output before they enter context, with conservative measurement. | Local guardrails, reversible artifacts and retrieval, and benchmark evidence you measure yourself. |
+
+## Brief mode (advisory)
+
+Brief mode is a set of agent-neutral, advisory rule snippets that ask a coding agent to cut filler while preserving the evidence a reviewer needs: file paths, commands, command output and errors, code blocks, verification status, changed files, known gaps, and caveats. It is best-effort guidance, not enforcement, and does **not** guarantee any token or cost savings.
+
+Three deterministic levels ship under [`plugins/context-guard/brief/`](plugins/context-guard/brief/): `lite`, `standard`, and `ultra`. Each level is a single marker-delimited block you install into an agent's rule/instruction file (for example `AGENTS.md`, `CLAUDE.md`, a Cursor rules file, or Copilot instructions) and remove by deleting the block. See [`plugins/context-guard/brief/README.md`](plugins/context-guard/brief/README.md).
+
+## What to measure
+
+When you need a savings claim, measure it on your own tasks:
+
+- full-file reads versus symbol or line-range reads
+- raw logs versus digest output or artifact receipts
+- transcript hotspots reported by `context-guard-audit`, including `cache_friendliness` prompt-layout signals
+- statusline `cache` / `reuse` as observed transcript/provider-cache signals, not savings caused by ContextGuard
+- matched successful baseline/variant runs from `context-guard-bench`
+- large tool/MCP catalogs versus `context-guard-tool-prune` top-k reports plus receipt retrieval
+- optional experimental lanes in [`research/experimental-token-reduction-radar.md`](research/experimental-token-reduction-radar.md), measured with the same matched-task benchmark gates before any savings claim
+
+## What ContextGuard does not do
+
+- It does not guarantee a fixed token or cost reduction.
+- It does not send work to external AI providers to save model tokens.
+- It does not mutate global Claude settings during install.
+- It does not replace real before/after measurement when you need a savings claim.
+- It does not ship learned compression, multimodal OCR/crop pruning, or self-hosted KV/latent inference optimization as runtime features; those remain gated experiments in the research radar.
+- It does not alias the old `/claude-token-optimizer:*` Claude Code slash-command namespace. Use `/context-guard:*` after installing this plugin.
+
+Legacy local CLI wrappers (`claude-token-*`, `claude-read-symbol`, `claude-trim-output`, and `claude-sanitize-output`) still ship in `bin/` so existing automation can migrate gradually.
+
+## Features
+
+| Feature | What it helps with |
+| --- | --- |
+| Claude Code plugin skills | Guided setup, optimization, and transcript usage audits. |
+| Project-local setup wizard | Applies recommended `.claude/settings.json` options without touching global settings. |
+| Context hygiene scanner | Finds missing guardrails, noisy hooks, broad reads, large context files, secret-like files, excessive MCP servers, and expensive defaults. |
+| Large-read guard and symbol reader | Nudges the agent toward `rg`, symbol reads, and small line ranges instead of full-file reads. |
+| Output trimming and sanitizing | Keeps test, build, search, and diff output compact while redacting likely secrets before they enter agent context. |
+| Local artifact store | Saves large sanitized logs outside the conversation and returns compact receipts or exact requested slices. |
+| Budgeted context packer | Assembles prioritized local file evidence into a hard byte-budgeted Markdown pack with omission reasons and exact slice commands when safe. |
+| Tool/MCP schema pruner | Emits bounded top-k tool/schema advisory reports from local catalogs with compact receipts and full sanitized payload retrieval. |
+| Conservative stdin compressor | Shrinks selected JSON, diffs, logs, search output, code, and prose with observed byte evidence and estimated token proxies. |
+| Repeated-failure nudge | Warns after repeated Bash failures so the agent changes strategy before stale logs fill the context. |
+| Statusline, audit, and benchmarks | Shows context/cache/cost signals, finds usage and cache-friendliness hotspots, and records conservative before/after evidence. |
+
+## Install in Claude Code
+
+Add the marketplace and install the plugin:
+
+```text
+/plugin marketplace add ictechgy/context-guard
+/plugin install context-guard@context-guard
+```
+
+Then run setup from Claude Code in the project you want to protect:
+
+```text
+/context-guard:setup
+```
+
+Available plugin skills:
+
+| Skill | Purpose |
+| --- | --- |
+| `/context-guard:setup` | First-time project setup wizard. |
+| `/context-guard:optimize` | Inspect and tune context guardrails. |
+| `/context-guard:audit` | Audit local Claude transcript token/cost hotspots. |
+
+Setup is explicit, project-local, and reversible. The plugin does not configure external model delegation or offload; all helper commands run locally. See [`plugins/context-guard/examples/settings.example.json`](plugins/context-guard/examples/settings.example.json) for an example settings file.
+
+## Install with npm/npx
+
+The npm package exposes a canonical `context-guard` command plus the backwards-compatible `context-guard-*` helper commands. Package installation is passive: there is no `postinstall` setup hook and no config write until you run `context-guard setup` yourself.
+
+```bash
+npm install -g @ictechgy/context-guard
+context-guard --version
+context-guard setup --agent codex --scope project --with-init --with-skill --plan
+```
+
+For a one-off run without global installation:
+
+```bash
+npx @ictechgy/context-guard setup --agent codex --scope project --with-init --with-skill --plan
+npm exec @ictechgy/context-guard -- --version
+```
+
+Use `--scope project` for repository files such as `AGENTS.md` and `.agents/skills/...`. Use `--scope user` only when you intentionally want a user-level path; applying user scope requires `--yes` plus an explicit `--agent`, and supported writes record rollback metadata.
+
+## Homebrew release path
+
+Homebrew is documented as the macOS release path once formula publishing is wired to a verified release artifact:
+
+```bash
+brew tap ictechgy/contextguard
+brew install context-guard
+context-guard --version
+```
+
+Until the tap is published, use npm/npx or the Claude plugin install path above.
+
+## Helper commands
+
+Most users should start with `/context-guard:setup`. The helper commands below are useful for local testing, automation, or targeted debugging. The canonical command prefix is `context-guard-*`.
+
+### Scan context hygiene
+
+```bash
+./plugins/context-guard/bin/context-guard-diet scan .
+```
+
+The scanner reports missing guardrails, noisy hooks, broad context paths, large or secret-like instruction/rule files across common AI-agent surfaces, and local context-exclusion recommendations for bulky or sensitive paths. `--top` caps both the reported context-like files and context-exclusion recommendations. Recommendations are heuristic/advisory unless they are emitted as Claude `permissions.deny` entries.
+
+### Read symbols instead of whole large files
+
+```bash
+./plugins/context-guard/bin/context-guard-read-symbol path/to/file.py TargetSymbol
+```
+
+The optional Read guard uses a progressive path for oversized files: search first, then symbol slices, then small line ranges. When possible, it also returns a bounded top-level outline. Repeated attempts to full-read the same oversized file get a deduplicated warning instead of repeating the same context-heavy path.
+
+### Store and query large logs locally
+
+```bash
+long-command 2>&1 | ./plugins/context-guard/bin/context-guard-artifact store --command "long-command" --json
+./plugins/context-guard/bin/context-guard-artifact get <artifact_id> --lines 1:80
+```
+
+Artifact mode is for capture and retrieval. It stores sanitized output under `.context-guard/artifacts` by default and can still read legacy `.claude-token-optimizer/artifacts` receipts from before the rebrand. JSON receipts include line-numbered top-error receipts, duplicate-line groups, and sanitized bounded `suggested_queries` so an agent can fetch the smallest useful exact slice instead of replaying the full log. When a suggested `--lines START:END` query also includes `--max-lines`, that flag is only the returned-line cap for the selected range; it does not broaden the selector. Preserve the producer command's exit code yourself when using shell pipelines in release checks, or use `context-guard-trim-output -- ...` when exit-code preservation is the primary requirement.
+
+### Build a budgeted context pack
+
+```bash
+./plugins/context-guard/bin/context-guard-pack build \
+  --root . \
+  --source 'path=README.md,priority=100,lines=1:120' \
+  --source 'path=src/app.py,priority=50' \
+  --budget-bytes 12000 --json
+./plugins/context-guard/bin/context-guard-pack slice --root . --path README.md --lines 1:40 --json
+```
+
+`context-guard-pack` assembles prioritized local file evidence into a Markdown body whose rendered UTF-8 bytes stay within `--budget-bytes`. JSON output records included, partial, duplicate, unsafe, missing, and budget-omitted sources, writes a bounded local receipt under `.context-guard/packs`, and includes copy-pasteable `slice` commands for exact sanitized retrieval when the path/root are safe to display. If retrieval is unsafe, the pack and JSON metadata include `retrieval_omitted_reason` instead of a command. Byte counts are observed; token counts remain estimated `chars_div_4` proxies, not measured provider-token savings.
+
+### Prune a tool/MCP catalog for a task
+
+```bash
+./plugins/context-guard/bin/context-guard-tool-prune select \
+  --catalog tools.json \
+  --query "review failing tests" \
+  --top 5 --budget-bytes 12000 --json
+./plugins/context-guard/bin/context-guard-tool-prune get <receipt_id> --tool read_file --json
+```
+
+`context-guard-tool-prune` ranks a local tool or MCP catalog with deterministic lexical heuristics and emits a bounded top-k advisory report. Inline selected schemas respect an observed UTF-8 byte budget, and omitted or budget-skipped schemas remain recoverable from a compact local receipt plus a separate sanitized payload under `.context-guard/tool-prune`. This is advisory only: it does not mutate MCP configuration, and token counts remain estimated proxies rather than measured provider savings.
+
+### Compress selected local text conservatively
+
+```bash
+git diff | ./plugins/context-guard/bin/context-guard-compress --json
+pytest -q 2>&1 | ./plugins/context-guard/bin/context-guard-compress --type log
+```
+
+`context-guard-compress` classifies sanitized stdin as JSON, diff, log, search output, code, or prose, then applies deterministic reductions such as JSON compaction, diff context folding, duplicate log/search line collapse, and whitespace normalization. It never claims observed model-token savings; byte counts are observed, token counts are labeled as estimates, and lossy receipts point you back to `context-guard-artifact store` for exact retrieval.
+
+### Trim or summarize command output
+
+```bash
+./plugins/context-guard/bin/context-guard-trim-output --max-lines 120 -- npm test
+```
+
+Use `--digest markdown` or `--digest json` for a compact semantic digest instead of head/tail logs. Digest mode keeps status, exit code, truncation counts, runner failure facts, a sanitized failure signature, duplicate-line groups, representative lines, redaction counts, and suggested next queries while preserving the wrapped command exit code. Wrapped commands time out after 600 seconds by default; tune this with `--timeout-seconds`.
+
+### Sanitize search and diff output
+
+```bash
+./plugins/context-guard/bin/context-guard-sanitize-output -- rg -n "TOKEN|SECRET" .
+./plugins/context-guard/bin/context-guard-sanitize-output -- git diff
+```
+
+The sanitizer reduces the chance that token-like, key-like, password-like, or sensitive path values are copied into agent context.
+
+### Audit local transcript usage
+
+```bash
+./plugins/context-guard/bin/context-guard-audit ~/.claude/projects --top 20 --recommend
+```
+
+The audit command skips oversized transcript files and JSONL records by default (`--max-file-bytes`, `--max-line-bytes`) and reports skipped counts, so a corrupt trace cannot dominate memory or hide scan gaps. JSON output also includes `cache_friendliness`: a heuristic prompt-layout diagnostic built from bounded, redacted segment hashes. It can flag likely volatile content near the prompt prefix, but it does not print raw prompt text and may be `missing` or `partial` when transcript schemas do not expose allowlisted prompt text.
+
+### Watch context and cache health in the statusline
+
+```text
+[Sonnet] repo | main | ctx 86% ⚠ | cost $0.123 | cache 80% | reuse 8.0x
+```
+
+`cache N%` is the cache-read share of observed input-side tokens in the bounded transcript tail and stays hidden until at least one cache read is observed. `reuse X.Yx` is `cache_read / cache_creation` and is shown only when cache read is positive and cache creation is non-zero. The `⚠` marker appears when context usage reaches the warning threshold, defaulting to 80%; set `CONTEXT_GUARD_STATUSLINE_CTX_WARN=90` to tune it for a project or shell.
+
+### Run a repeatable benchmark
+
+```bash
+./plugins/context-guard/bin/context-guard-bench \
+  --tasks bench/tasks.json --variants bench/variants.json --csv bench/results.csv \
+  --ledger-jsonl bench/cost-shift.jsonl --report-json bench/report.json
+```
+
+The report compares successful baseline/variant runs by real tokens and `cost_usd + external_cost_usd`. Byte reductions are recorded as proxy evidence, not treated as proof of savings. Token-savings claims require `primary_tokens_measured` on both sides of a matched task. `wall_time_seconds`, `provider_cached_tokens`, and `provider_cached_tokens_measured` are diagnostic telemetry, not proof of ContextGuard-caused token or cost savings. If cost fields are zero or unavailable, the report can still mark token savings but will not claim shifted-cost savings. Claims are paired by matched successful tasks and downgraded when failure-rate guardrails regress. CSV schemas are strict; after upgrading the benchmark helper, start a new `--csv` file or migrate the header named in the mismatch error. See [`docs/benchmark-report.example.json`](docs/benchmark-report.example.json) for a minimal report-shape example.
+
+## What is not yet shipped
+
+These are directions the project has noted, not committed features. Nothing here ships unless documented elsewhere in the repository.
+
+- workflow-specific before/after benchmark report examples beyond the minimal report-shape fixture.
+- learned prompt/context compression, multimodal crop/OCR or visual-token pruning, and self-hosted KV/latent inference optimizations. See the [experimental token-reduction radar](research/experimental-token-reduction-radar.md); these lanes require matched successful tasks, failure-rate guardrails, human-correction tracking, shifted-cost accounting, and provider-measured token/cost evidence before any hosted API savings claim.
+
+## Repository layout
+
+- `.claude-plugin/marketplace.json` — Claude Code marketplace manifest.
+- `plugins/context-guard/` — installable Claude Code plugin package.
+- `context-guard-kit/` — underlying Python/Bash helper tools.
+- `docs/index.html` — static landing page for the project.
+- `tests/` — regression tests for helper behavior.
+
+## Local development
+
+Run Claude Code with the plugin directory:
+
+```bash
+claude --plugin-dir ./plugins/context-guard
+```
+
+Test marketplace installation from the repository root:
+
+```text
+/plugin marketplace add ./
+/plugin install context-guard@context-guard
+```
+
+Plugin helper binaries are not added to `PATH` by default. For local testing, invoke them by full path:
+
+```bash
+./plugins/context-guard/bin/context-guard-setup --plan
+./plugins/context-guard/bin/context-guard-setup --yes
+```
+
+To use shorter commands during local development, add the plugin bin directory to your shell:
+
+```bash
+export PATH="$PWD/plugins/context-guard/bin:$PATH"
+context-guard-setup --plan
+```
+
+## Release checks
+
+Before publishing or merging release-sensitive changes, run both gates:
+
+```bash
+python3 scripts/prepublish_check.py
+python3 scripts/release_smoke.py
+```
+
+`prepublish_check.py` verifies package invariants, synchronized plugin binaries, manifests, diagnostic redaction, and the regression suite. `release_smoke.py` executes representative packaged entrypoints from `plugins/context-guard/bin` in a temporary project so broken CLI wiring is caught before publish. See [docs/release-runbook.md](docs/release-runbook.md) for the full release workflow, evidence checklist, quad-review requirement, and rollback checklist.
+
+Versioned release notes live in [CHANGELOG.md](CHANGELOG.md); the prepublish gate requires an entry matching the plugin manifest version before publishing.
+
+## License
+
+Copyright 2026 jinhongan. Licensed under the Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/context-guard-kit/README.md

@@ -0,0 +1,76 @@
+# ContextGuard Kit
+
+Claude Code CLI 토큰 절감을 위한 실험용 도구 모음입니다. 모두 Python/Bash 표준 기능만 사용합니다.
+
+## 구성
+
+- `statusline.sh` — context/cost/model을 statusline에 표시
+- `trim_command_output.py` — 긴 명령 output을 head/tail/error와 pytest/Jest/Vitest/Go/Rust 실패 요약 중심으로 축약하고 원래 exit code 보존
+- `rewrite_bash_for_token_budget.py` — Claude Code `PreToolUse` hook에서 test/build/lint 명령을 wrapper로 감쌈
+- `claude_transcript_cost_audit.py` — `~/.claude/projects` JSONL transcript에서 usage/cost/cache field와 cache-friendly prompt layout 신호를 집계하고 `--recommend`로 절감 액션 제안
+- `context_guard_diet.py` — project `.claude/settings.json` deny/hook/statusline, 여러 AI 에이전트 rule file의 context bloat, local context-exclusion 추천을 스캔
+- `guard_large_read.py` — Claude Code `PreToolUse` Read hook에서 큰 파일 전체 읽기를 막고 symbol/line-range 읽기로 유도
+- `read_symbol.py` — Python/JS/TS/Go/Rust 파일에서 지정 symbol 주변만 출력
+- `sanitize_output.py` — `rg`/`grep`/`git diff` 같은 검색·diff output에서 credential을 redact하고 head/anchor/tail로 축약
+- `context_escrow.py` — 큰 command output을 sanitize 후 로컬 artifact로 저장하고 line/pattern query로 다시 조회
+- `context_pack.py` — 우선순위 local file evidence를 byte budget 안의 Markdown context pack으로 조립하고 omission/retrieval receipt를 기록
+- `tool_schema_pruner.py` — 로컬 tool/MCP catalog를 top-k schema 자문 리포트로 줄이고 전체 정제 schema는 receipt/payload로 재조회
+- `benchmark_runner.py` — 고정 task/variant fixture로 A/B token/cost 절감 benchmark, cost-shift ledger, report 생성
+- `setup_wizard.py` — 설치 후 project-local `.claude/settings.json`을 대화형으로 선택하고 병합
+- `failed_attempt_nudge.py` — 반복 Bash 실패 시 `/clear`/`/compact`와 strategy switch를 짧게 권유
+- `settings.example.json` — project `.claude/settings.json` 예시
+
+## 빠른 실험
+
+```bash
+python3 context-guard-kit/trim_command_output.py --max-lines 80 -- bash -lc 'seq 1 1000; echo FAIL test_x >&2; exit 1'
+python3 context-guard-kit/trim_command_output.py --max-lines 80 -- pytest tests -q
+python3 context-guard-kit/claude_transcript_cost_audit.py ~/.claude/projects --top 10 --recommend
+python3 context-guard-kit/setup_wizard.py
+python3 context-guard-kit/context_guard_diet.py scan . --json
+python3 context-guard-kit/read_symbol.py path/to/file.py TargetSymbol
+long-command 2>&1 | python3 context-guard-kit/context_escrow.py store --command "long-command" --json
+python3 context-guard-kit/context_escrow.py get <artifact_id> --lines 1:80
+python3 context-guard-kit/context_pack.py build --root . --source 'path=README.md,priority=100,lines=1:80' --budget-bytes 12000 --json
+python3 context-guard-kit/context_pack.py slice --root . --path README.md --lines 1:40 --json
+python3 context-guard-kit/tool_schema_pruner.py select --catalog tools.json --query "review failing tests" --top 5 --budget-bytes 12000 --json
+python3 context-guard-kit/tool_schema_pruner.py get <receipt_id> --tool read_file --json
+python3 context-guard-kit/benchmark_runner.py --tasks bench/tasks.json --variants bench/variants.json --csv bench/results.csv --ledger-jsonl bench/cost-shift.jsonl --report-json bench/report.json
+python3 context-guard-kit/sanitize_output.py -- rg -n "TOKEN|SECRET" .
+python3 context-guard-kit/sanitize_output.py -- git diff
+```
+
+`trim_command_output.py`는 output이 budget을 넘을 때 runner별 failure summary를 먼저 보여줍니다. 예를 들어 pytest node id, Jest/Vitest 실패 파일/테스트, `go test`의 실패 test와 `_test.go:line`, `cargo test` panic 위치를 짧게 보존해 Claude가 전체 로그를 다시 읽지 않고도 다음에 수정할 파일을 고를 수 있게 합니다. head/tail 로그 대신 더 작은 의미 요약만 필요하면 `--digest markdown` 또는 `--digest json`을 추가하세요. digest mode는 status, exit code, truncation count, runner failure facts, 정제된 failure signature, 중복 라인 그룹, 대표 라인, redaction count, 다음 query 제안을 남깁니다. 감싼 명령은 기본 600초 후 timeout 처리되며(`--timeout-seconds`로 조정), 가능한 환경에서는 process group까지 종료한 뒤 124를 반환합니다. ANSI color code는 제거하며, 절대경로는 기본적으로 `basename#path:<hash>`로 익명화합니다. 로컬 디버깅에서 원문 절대경로가 꼭 필요하면 `--show-paths`를 추가하세요.
+
+`context_escrow.py`는 대용량 output을 Claude context에 그대로 넣지 않고 `.context-guard/artifacts` 아래 `0o600` 파일로 저장합니다. 저장 전에 sanitizer를 적용해 secret/path 노출을 줄이고, receipt에는 `artifact_id`, line/byte count, 줄 번호가 포함된 top-error receipt, 중복 라인 그룹, 대표 head/tail, 정제된 bounded `suggested_queries`와 `get --lines`/`get --pattern` query 예시만 출력합니다. suggested `--lines START:END` query에 `--max-lines`가 함께 있으면 이는 해당 line range의 반환 cap일 뿐 selector를 넓히는 옵션이 아닙니다. `get`과 `list`는 legacy 기본 위치인 `.claude-token-optimizer/artifacts`도 함께 읽어 리브랜딩 전 receipt를 계속 조회할 수 있습니다. 저장된 artifact는 sanitize된 사본이며, 필요할 때만 `get <artifact_id> --lines 10:40`처럼 정확한 범위를 조회하세요. 파이프라인 저장은 capture/query 용도이므로 producer 명령의 exit code가 필요한 release check에서는 shell `pipefail`/별도 `$?` 저장을 쓰거나 `trim_command_output.py -- ...`로 감싸세요.
+
+
+`context_pack.py`는 여러 로컬 파일 source를 우선순위와 줄 범위에 따라 정렬하고, 렌더링된 UTF-8 byte budget 안에서 Markdown context pack을 만듭니다. 포함·부분 포함·누락 source, 누락 사유, `.context-guard/packs` bounded receipt, 그리고 `slice --lines` 정확 재조회 명령을 JSON으로 남깁니다. pack 본문/영수증을 만들기 전에 sanitizer를 적용하며, token 값은 관측값이 아닌 추정 proxy로만 표시합니다.
+
+`tool_schema_pruner.py`는 provider-neutral tool/MCP catalog helper입니다. `select`는 task query와 lexical overlap으로 top-k tool을 고르고, inline schema는 `--budget-bytes` 안에만 넣으며, compact receipt와 별도 sanitized payload를 `.context-guard/tool-prune`에 기록합니다. `get`은 payload size/SHA-256을 검증한 뒤 전체 정제 schema를 반환합니다. 이 helper는 MCP 설정을 바꾸지 않으며, token 절감은 측정값이 아니라 추정 proxy로만 표현합니다.
+
+`benchmark_runner.py`는 `research/benchmark-plan.md`의 고정 task/variant 실험을 실행합니다. `--ledger-jsonl`은 subagent·artifact 등 외부 실행 표면으로 옮겨간 token/cost를 run별로 남기고, `--report-json`은 baseline 대비 실제 token/cost 절감과 proxy byte 감소를 분리한 A/B report를 생성합니다.
+
+`../research/experimental-token-reduction-radar.md`는 learned compression, multimodal crop/OCR/visual-token pruning, self-hosted KV/latent inference optimization 같은 선택적 미래 실험을 문서화한 gate입니다. 이 radar는 runtime helper가 아니며, hosted API token/cost 절감을 보장하지 않습니다. hosted API token/cost 절감 주장은 provider가 측정한 matched-task 근거가 있을 때만 허용합니다.
+
+`claude_transcript_cost_audit.py --recommend`의 기본 출력은 공유 시 안전하도록 transcript 경로를 `basename#hash`, 명령을 `command#hash` 형태로 익명화합니다. 로컬 원문 식별자가 꼭 필요할 때만 `--show-paths` 또는 `--show-commands`를 추가하세요.
+대용량/손상 transcript 방어를 위해 파일 단위 `--max-file-bytes`, JSONL record 단위 `--max-line-bytes` 제한도 기본 적용되며, 건너뛴 항목은 skip count와 warning으로 노출됩니다. JSON summary/feasibility 출력의 `cache_friendliness`는 제한된 정제 segment hash로 안정적인 prefix와 volatile prefix/tail 신호를 비교하는 휴리스틱입니다. 원문 prompt text는 출력하지 않고, provider cache token field는 ContextGuard가 만든 토큰 절감 증거가 아니라 별도 진단 텔레메트리로 해석하세요.
+
+`context_guard_diet.py scan`은 항상 로컬에서만 읽는 read-only 스캐너입니다. 기본 출력은 project root를 익명화하고 상대경로 중심으로 보고합니다. `--top`은 보고서의 context-like file 목록과 context-exclusion recommendation 목록에 공통으로 적용됩니다. `--show-paths`는 로컬/비공개 디버깅에서만 쓰세요.
+
+`context_pack.py build`의 retrieval command는 path/root를 안전하게 표시할 수 있을 때만 출력됩니다. 안전하지 않으면 pack 본문과 JSON source metadata에 `retrieval_omitted_reason`을 기록합니다. `token_proxy`는 렌더링된 pack 문자 수를 `chars_div_4`로 나눈 추정치이며, provider가 실제로 청구/소모한 token 측정값이 아닙니다.
+
+`setup_wizard.py`는 설치 후 한 번 실행하는 설정 마법사입니다. 터미널에서 실행하면 deny rules, statusline, Bash trim/sanitize hook, large Read guard, 반복 실패 nudge, model/effort defaults를 project-local `.claude/settings.json`에 병합합니다. 비대화형 환경에서는 `--plan`으로 미리 보고 `--yes`로 추천값을 적용하세요. 설정을 적용하면 read-only `context_guard_diet.py scan` 요약을 자동으로 출력해 남은 gap을 확인할 수 있습니다. 반복 실패 nudge가 방해되는 프로젝트는 `--no-failed-attempt-nudge`로, post-setup scan이 불필요한 자동화는 `--no-diet-scan`으로 제외할 수 있습니다.
+
+`guard_large_read.py`는 opt-in Read hook입니다. 큰 파일 전체를 Claude context에 넣기 전에 progressive read ladder를 반환해 `rg -n` 검색, `read_symbol.py` symbol slice, 작은 `offset`/`limit` Read 순서로 좁히게 합니다. Python/JS/TS/Go/Rust/Markdown 파일은 bounded prefix에서 top-level outline과 line estimate도 함께 보여줍니다. 같은 oversized file fingerprint를 반복해서 읽으려 하면 repeated-read dedup 힌트를 추가해 이전 ladder를 재사용하게 합니다. `CONTEXT_GUARD_READ_GUARD=0`으로 로컬에서 일시 비활성화할 수 있습니다.
+
+`failed_attempt_nudge.py`는 같은 Bash 실패 방향이 두 번 반복되면 `/clear`/`/compact` 힌트를 주고, 세 번 이상 반복되면 strategy-switch signal을 추가해 동일 명령 재시도 대신 다른 가설·더 작은 재현·수정 후 재검증으로 전환하게 합니다. recommended setup에서는 기본으로 켜지며, 실행을 막지 않고 짧은 추가 컨텍스트만 주입합니다.
+
+`sanitize_output.py`는 grep/diff output을 Claude에게 보여주기 전에 secret-like line, Authorization header, private key block, API token, credential URL을 `[REDACTED]`로 바꾸고, 긴 결과는 head / grep·diff·security anchor / tail만 남깁니다. 명령을 감싸는 wrapper mode는 원래 exit code를 보존합니다. stdin pipe도 지원하지만 producer exit code는 shell `pipefail` 없이는 알 수 없으므로 자동화에는 `python3 .../sanitize_output.py -- rg ...`처럼 wrapper mode를 선호하세요. 절대경로는 기본 익명화되고 로컬 디버깅에서만 `--show-paths`를 쓰세요. `rewrite_bash_for_token_budget.py` hook은 단일 argv 형태의 `rg`, `grep`, `git grep`, `git diff`, `git show`, `git log -p`를 자동으로 이 sanitizer에 감쌉니다.
+
+Claude Code에 적용하려면 `settings.example.json`을 `.claude/settings.json`으로 복사하되, 먼저 작은 repo에서 quoting/exit code를 확인하세요.
+
+
+## License
+
+Copyright 2026 jinhongan. Licensed under the Apache License 2.0. See the repository [LICENSE](../LICENSE) and [NOTICE](../NOTICE).