@ictechgy/context-guard 0.4.0

package/docs/distribution.md

@@ -0,0 +1,55 @@
+# ContextGuard distribution plan
+
+ContextGuard separates **install** from **activation**.
+
+- Install exposes local commands or Claude Code plugin skills.
+- Activation is explicit and scoped through `context-guard setup` or `/context-guard:setup`.
+- Package installation must not write project or user configuration.
+
+## Supported install paths
+
+| Path | Status | Command | Notes |
+| --- | --- | --- | --- |
+| Claude Code plugin | shipped | `/plugin marketplace add ictechgy/context-guard` then `/plugin install context-guard@context-guard` | Best native Claude Code workflow. |
+| npm global | added | `npm install -g @ictechgy/context-guard` | Installs `context-guard` and helper aliases on PATH. |
+| npx/npm exec | added | `npx @ictechgy/context-guard --version` | One-off usage; activation still requires explicit setup. |
+| Homebrew | draft | `brew tap ictechgy/contextguard && brew install context-guard` | Formula template exists under `packaging/homebrew/`; publish after release artifact SHA is known. |
+
+## Activation examples
+
+```bash
+context-guard setup --agent codex --scope project --with-init --with-skill --plan
+context-guard setup --agent codex --scope project --with-init --with-skill --yes
+context-guard setup --agent claude --scope user --plan
+```
+
+Project scope is the default. User scope is opt-in and requires an explicit agent for writes. Supported user-scope writes record backups and rollback metadata under `.context-guard/rollback` in the user home directory.
+
+## Runtime requirements
+
+The helpers are Python/shell scripts packaged through npm and Homebrew. Supported machines need:
+
+- macOS or Linux
+- Python 3 available as `python3`
+- POSIX no-follow file operations for setup writes
+- Node/npm only for npm/npx install paths
+
+## Non-goals for this release
+
+- No install-time `postinstall` configuration writes.
+- No sudo/root/system configuration writes.
+- No claim of native activation for agents whose current safe user-level path has not been verified.
+- No fixed token or cost savings claim from packaging alone.
+
+## Homebrew formula release checks
+
+Before publishing the Homebrew tap, run the formula-specific checks locally or in CI when Homebrew is available:
+
+```bash
+brew style packaging/homebrew/context-guard.rb
+brew audit --strict --new packaging/homebrew/context-guard.rb
+brew install --build-from-source packaging/homebrew/context-guard.rb
+brew test context-guard
+```
+
+The formula should rewrite Python shebangs to the declared Homebrew Python dependency and expose both `context-guard` and legacy compatibility wrappers from `plugins/context-guard/bin`.

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@ictechgy/context-guard",
+  "version": "0.4.0",
+  "description": "ContextGuard CLI helpers for keeping AI coding agent context focused and local-first.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/ictechgy/context-guard#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ictechgy/context-guard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ictechgy/context-guard/issues"
+  },
+  "type": "commonjs",
+  "bin": {
+    "context-guard": "plugins/context-guard/bin/context-guard",
+    "context-guard-setup": "plugins/context-guard/bin/context-guard-setup",
+    "context-guard-diet": "plugins/context-guard/bin/context-guard-diet",
+    "context-guard-audit": "plugins/context-guard/bin/context-guard-audit",
+    "context-guard-trim-output": "plugins/context-guard/bin/context-guard-trim-output",
+    "context-guard-sanitize-output": "plugins/context-guard/bin/context-guard-sanitize-output",
+    "context-guard-artifact": "plugins/context-guard/bin/context-guard-artifact",
+    "context-guard-pack": "plugins/context-guard/bin/context-guard-pack",
+    "context-guard-tool-prune": "plugins/context-guard/bin/context-guard-tool-prune",
+    "context-guard-compress": "plugins/context-guard/bin/context-guard-compress",
+    "context-guard-bench": "plugins/context-guard/bin/context-guard-bench",
+    "context-guard-read-symbol": "plugins/context-guard/bin/context-guard-read-symbol",
+    "context-guard-rewrite-bash": "plugins/context-guard/bin/context-guard-rewrite-bash",
+    "context-guard-guard-read": "plugins/context-guard/bin/context-guard-guard-read",
+    "context-guard-failed-nudge": "plugins/context-guard/bin/context-guard-failed-nudge",
+    "context-guard-statusline": "plugins/context-guard/bin/context-guard-statusline",
+    "context-guard-statusline-merged": "plugins/context-guard/bin/context-guard-statusline-merged"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "README.ko.md",
+    "context-guard-kit/*.py",
+    "context-guard-kit/*.sh",
+    "context-guard-kit/README.md",
+    "context-guard-kit/settings.example.json",
+    "plugins/context-guard/.claude-plugin/plugin.json",
+    "plugins/context-guard/README.md",
+    "plugins/context-guard/README.ko.md",
+    "plugins/context-guard/LICENSE",
+    "plugins/context-guard/bin/**",
+    "plugins/context-guard/brief/**",
+    "plugins/context-guard/lib/**",
+    "plugins/context-guard/skills/**",
+    "docs/distribution.md",
+    "packaging/homebrew/context-guard.rb.template"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "keywords": [
+    "ai",
+    "codex",
+    "claude-code",
+    "context",
+    "token-budget",
+    "cli"
+  ]
+}

package/packaging/homebrew/context-guard.rb.template

@@ -0,0 +1,34 @@
+# Homebrew formula draft for ContextGuard.
+# Replace URL/SHA/tag during release packaging; do not publish with SHA placeholder.
+class ContextGuard < Formula
+  include Language::Python::Shebang
+
+  desc "Local-first context guardrails for AI coding agents"
+  homepage "https://github.com/ictechgy/context-guard"
+  url "https://github.com/ictechgy/context-guard/archive/refs/tags/v0.4.0.tar.gz"
+  sha256 "REPLACE_WITH_RELEASE_TARBALL_SHA256"
+  license "Apache-2.0"
+
+  depends_on "python@3.12"
+
+  def install
+    libexec.install "CHANGELOG.md", "LICENSE", "NOTICE", "README.md", "README.ko.md"
+    libexec.install "context-guard-kit"
+    libexec.install "plugins"
+
+    python_shebang = detected_python_shebang
+    Dir[libexec/"plugins/context-guard/bin/*"].each do |command|
+      next unless command.file?
+
+      first_line = command.open { |file| file.gets.to_s }
+      rewrite_shebang python_shebang, command if first_line.include?("python")
+      bin.write_exec_script command
+    end
+  end
+
+  test do
+    assert_match version.to_s, shell_output("#{bin}/context-guard --version")
+    mkdir testpath/"project"
+    system bin/"context-guard", "setup", "--root", testpath/"project", "--agent", "codex", "--scope", "project", "--plan"
+  end
+end

package/plugins/context-guard/.claude-plugin/plugin.json

@@ -0,0 +1,41 @@
+{
+  "name": "context-guard",
+  "description": "ContextGuard keeps AI coding-agent context lean, safe, and auditable with project-local setup, scans, large-read guards, output trimming/sanitizing, queryable log artifacts, budgeted context packs, tool/MCP schema pruning, statusline visibility, and usage audits.",
+  "author": {
+    "name": "jinhongan"
+  },
+  "license": "Apache-2.0",
+  "keywords": [
+    "context-safety",
+    "context-hygiene",
+    "context-guard",
+    "claude-code",
+    "tokens",
+    "cost",
+    "context",
+    "settings",
+    "diet",
+    "read-symbol",
+    "large-read-guard",
+    "statusline",
+    "hooks",
+    "sanitize-output",
+    "grep-sanitizer",
+    "diff-sanitizer",
+    "secret-redaction",
+    "setup-wizard",
+    "interactive-setup",
+    "artifact-escrow",
+    "context-escrow",
+    "queryable-logs",
+    "tool-schema",
+    "mcp",
+    "schema-pruning",
+    "context-pack",
+    "research-radar",
+    "experimental-roadmap",
+    "gated-experiments",
+    "future-roadmap"
+  ],
+  "version": "0.4.0"
+}

package/plugins/context-guard/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/plugins/context-guard/NOTICE

@@ -0,0 +1,4 @@
+ContextGuard
+Copyright 2026 jinhongan
+
+This product is licensed under the Apache License, Version 2.0.

package/plugins/context-guard/README.ko.md

@@ -0,0 +1,135 @@
+# ContextGuard
+
+ContextGuard는 AI 코딩·도구 에이전트를 위한 로컬 우선 컨텍스트 관리 도구 모음입니다. Claude Code 플러그인으로 가장 먼저 제공되며, 같은 프로젝트 로컬 가드레일을 일반 로컬 헬퍼 명령과 안내용 brief 모드 규칙 스니펫으로 다른 에이전트에도 확장합니다.
+
+가장 먼저 `/context-guard:setup`을 실행하세요. 설정은 명시적이며, 프로젝트 단위로 적용되고, 되돌릴 수 있습니다. 권장 프로젝트 설정을 병합하고, 읽기 전용 컨텍스트 관리 검사 요약을 출력하며, 전역 Claude 설정은 변경하지 않습니다. 외부 AI에 작업을 넘기거나 대신 실행하도록 설정하지도 않습니다.
+
+## 줄이려는 토큰 낭비 경로
+
+ContextGuard는 provider prompt cache나 semantic answer cache가 아니라 로컬 컨텍스트 관리 계층입니다. 에이전트 대화에 들어가기 전에 큰 파일은 검색·심볼·줄 범위 읽기로 좁히고, 긴 명령 출력은 축약하거나 요약하며, 큰 로그는 로컬 보관 요약 기록으로 남깁니다. 또한 민감 정보처럼 보이는 값과 경로를 최대한 가리고, Bash 실패가 반복되면 전략을 바꾸도록 알리며, 제한된 가림 처리된 segment hash로 캐시 친화적 프롬프트 배치를 감사하고, 감사·벤치마크로 실제 작업의 전후 비교 근거를 남기도록 돕습니다.
+
+## 리브랜딩 참고
+
+Claude Code는 예전 `/claude-token-optimizer:*` 플러그인 슬래시 명령을 별칭으로 제공하지 않습니다. 설치 후에는 `/context-guard:*`를 사용하세요.
+
+기존 자동화가 바로 깨지지 않도록 로컬 CLI 호환 래퍼(`claude-token-*`, `claude-read-symbol`, `claude-trim-output`, `claude-sanitize-output`)는 `bin/`에 계속 포함합니다.
+
+## 스킬
+
+설치 후 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/` 디렉터리가 자동으로 추가된다고 보장할 수는 없습니다.
+
+Codex나 다른 터미널 기반 에이전트에서는 npm 패키지를 설치하거나 npx로 한 번만 실행할 수 있습니다. 설치 자체는 설정 파일을 쓰지 않는 수동적 단계입니다.
+
+```bash
+npm install -g @ictechgy/context-guard
+context-guard setup --agent codex --scope project --with-init --with-skill --plan
+npx @ictechgy/context-guard --version
+```
+
+이 저장소 루트에서는 경로를 직접 지정해 실행하세요.
+
+```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 get <artifact_id> --lines 1:80
+context-guard-compress --json < large-output.txt
+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 build --root . --source 'path=README.md,priority=100,lines=1:80' --budget-bytes 12000 --json
+context-guard-pack slice --root . --path README.md --lines 1:40 --json
+context-guard-tool-prune select --catalog tools.json --query "review failing tests" --top 5 --budget-bytes 12000 --json
+context-guard-tool-prune get <receipt_id> --tool read_file --json
+context-guard-statusline
+context-guard-statusline-merged
+```
+
+## 헬퍼가 하는 일
+
+- **설정 마법사**는 `.claude/settings.json`을 덮어쓰지 않고 병합한 뒤, 읽기 전용 `context-guard-diet scan` 요약을 출력합니다. 자동화에서 적용 후 검사 요약이 필요 없으면 `--no-diet-scan`을 사용하세요.
+- **컨텍스트 관리 스캐너**는 누락된 `permissions.deny` 가드레일, Bash 출력 축약 훅, 상태표시줄 설정, 넓은 읽기 허용, 비용이 큰 기본 모델/추론 강도, 많은 MCP 서버, 크거나 민감해 보이는 에이전트 규칙 파일, bulky/sensitive 로컬 경로에 대한 자문형 context-exclusion 추천을 확인합니다.
+- **대용량 읽기 가드와 심볼 리더**는 파일 전체 읽기 전에 검색, 심볼 구간, 작은 줄 범위 읽기 순서로 에이전트를 안내합니다. Python, JavaScript/TypeScript, Go, Rust 소스 구간 읽기를 지원합니다.
+- **로컬 로그 보관소**는 큰 명령 출력을 기본적으로 `.context-guard/artifacts`에 가림 처리해 저장하고, 줄 번호가 있는 top error, 중복 라인 그룹, 가림 처리된 bounded suggested query가 담긴 요약 기록이나 요청한 정확한 줄 범위만 반환합니다. `get`과 `list`는 리브랜딩 이전의 `.claude-token-optimizer/artifacts` 요약 기록도 읽을 수 있습니다.
+- **예산 기반 컨텍스트 패커**는 우선순위가 있는 로컬 파일 근거를 렌더링된 바이트 예산 안의 Markdown pack으로 조립하고, 포함·부분 포함·누락 source 메타데이터, bounded `.context-guard/packs` 요약 기록, 안전할 때만 정확한 가림 처리 `slice` 명령, 안전하지 않을 때의 `retrieval_omitted_reason`을 남깁니다. 토큰 수는 측정된 provider token 절감이 아니라 추정 `chars_div_4` proxy입니다.
+- **Tool/MCP schema pruner**는 로컬 tool catalog를 bounded top-k 자문 리포트로 순위화하고, compact 요약 기록과 payload integrity check로 전체 가림 처리된 schema 재조회를 보존합니다.
+- **보수적 압축기**는 가림 처리된 stdin을 JSON, diff, 로그, 검색 출력, 코드, 산문으로 분류하고, 관측 바이트 근거와 추정 토큰 proxy를 함께 노출합니다.
+- **출력 축약기**는 감싼 명령의 종료 코드를 보존하면서 긴 로그를 줄이고, `--digest markdown` 또는 `--digest json`으로 실행기 실패 정보, 가림 처리된 failure signature, 중복 라인 그룹, 다음 조회 제안이 담긴 요약을 만들 수 있습니다.
+- **민감정보 가림 도구**는 검색, diff, 로그 출력에서 자격 증명 패턴, 비공개 키 블록, 인증 헤더, 자격 증명이 포함된 URL, 민감해 보이는 경로를 가립니다.
+- **상태표시줄**은 모델, 컨텍스트, 비용 신호를 짧게 보여주고, 대화 기록 데이터가 있으면 캐시 읽기와 캐시 재사용 신호도 함께 표시합니다.
+- **대화 기록 감사**는 usage/cost/cache bucket을 집계하고, 토큰 집중 지점과 `cache_friendliness` 프롬프트 배치 신호를 제한된 가림 처리된 segment hash로 보고합니다. 원문 프롬프트는 출력하지 않습니다.
+- **반복 실패 알림**은 Bash 실패가 반복될 때 같은 경로를 계속 재시도하지 않고 전략을 바꾸도록 안내합니다.
+- **벤치마크 헬퍼**는 기준/변형 실행을 대응해 실제 토큰·비용 필드, 별도의 바이트 감소 간접 증거, 진단용 `wall_time_seconds`, `provider_cached_tokens`, provider-cache 사용 가능성 텔레메트리로 기록합니다.
+
+## brief 모드 (권고)
+
+brief 모드는 코딩 에이전트가 군더더기를 줄이되 증거(파일 경로, 명령, 명령 출력과 오류, 코드 블록, 검증 상태, 변경 파일, 남은 과제, 주의사항)는 유지하도록 요청하는 에이전트 중립·안내용 규칙 스니펫을 제공합니다. 강제가 아니라 최선 노력 안내이며, 토큰·비용 절감을 **보장하지 않습니다.**
+
+세 가지 결정적 레벨(`lite`, `standard`, `ultra`)이 [`brief/`](brief/)에 있습니다. 각 레벨은 마커로 구분된 하나의 블록이며, 에이전트의 규칙·지시 파일(`AGENTS.md`, `CLAUDE.md`, Cursor 규칙 파일, Copilot 지시 등)에 설치하고 블록을 지워서 제거합니다. 자세한 내용은 [`brief/README.md`](brief/README.md)를 참고하세요.
+
+## 절감 수치를 과장하지 않습니다
+
+이 헬퍼들은 흔히 컨텍스트를 불필요하게 키우는 원인을 줄이지만, 고정된 절감률을 보장하지 않습니다. 실제 전후 비교 증거가 필요하면 `context-guard-bench --ledger-jsonl ... --report-json ...`로 본인 작업에서 측정하세요. 토큰 절감 주장은 대응 태스크 양쪽 모두에 `primary_tokens_measured`가 있을 때만 계산하며, wall-time과 provider-cache 필드는 진단용 텔레메트리이지 단독 절감 증거가 아닙니다. 감사의 `cache_friendliness`는 휴리스틱 배치 신호이며 청구 기준이 아닙니다. 벤치마크 CSV 스키마는 엄격하므로 헬퍼 업그레이드 후에는 새 CSV를 시작하거나 헤더를 마이그레이션하세요.
+
+ContextGuard는 모델 토큰을 줄이기 위해 작업을 외부 AI 서비스로 전송하지 않습니다. 모든 헬퍼 명령은 로컬에서 동작합니다.
+
+미래 learned, multimodal, self-hosted 최적화 아이디어는 [`../../research/experimental-token-reduction-radar.md`](../../research/experimental-token-reduction-radar.md)에만 gated experiment로 기록합니다. 이 radar는 제공 중인 runtime 기능이 아니며, provider가 측정한 matched-task 근거 없이 hosted API 절감을 주장하지 않습니다.
+
+교차 에이전트 규칙 스니펫은 권고 사항입니다. 대상 에이전트가 반드시 따른다고 보장할 수 없으므로, 절감 주장이 필요하면 실제 전후 동작을 직접 측정하세요.
+
+## 로컬 배포 테스트
+
+마켓플레이스 저장소 루트에서 실행합니다.
+
+```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)를 참고하세요.