ContextGuard

ContextGuard is a local-first context-management toolkit for AI coding and tool-using agents. It starts with a Claude Code plugin: install it once, enable it explicitly per project, and roll it back when needed. It trims noisy output, guides agents toward symbol-level reads, flags repeated failures, redacts secret-like patterns, and measures usage — and the same guardrails are reusable by other agents through local helper commands and advisory brief-mode snippets.

• Korean documentation: README.ko.md
• Static landing page: GitHub Pages (source)

Quickstart

/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 users run npx @ictechgy/context-guard setup --profile recommended --plan then --yes.

Three problems it solves

A build or test dumps thousands of lines into the transcript. The default Bash wrapper escrows the sanitized output to a local artifact and leaves a compact receipt in context. Pull back only the slice you need:

context-guard-artifact get <id> --lines a:b

You do not know where your tokens went. The audit reads local Claude transcripts and reports new tokens per turn together with the tool that preceded each turn, plus where result bytes came from by tool, content class, and file extension:

context-guard-audit ~/.claude/projects --recommend

That is an observation, not a savings claim. It says where the bytes and the new tokens landed; it does not say what you would recover by trimming them.

An agent reads a whole large file for one function. The optional Read guard pushes search → symbol slice → small line range, and the symbol reader returns the slice directly:

context-guard-read-symbol path/to/file.py TargetSymbol

Its enforcement surface is deliberately limited to the installed Claude Code PreToolUse hook whose matcher is Read:

Claude tool	Covered behavior
Read	The hook checks bounded large-file ranges and denies a basename beginning with .env, except the exact template names .env.example, .env.sample, and .env.template. Nested paths are included; ambiguous symlink paths fail closed.
Glob	May list matching names. It does not read file contents through this Read hook.
Grep	Out of scope for this hook and may read matching file contents.
Bash	Out of scope for this hook and may read file contents.

This is Claude Read protection, not universal .env or Bash protection. The hook proves the file state it opens without following symlinks and revalidates that same descriptor, but Claude performs the actual Read with a later open after the hook returns. A replacement in that post-hook window is a documented TOCTOU limitation.

Install

Installation and activation are deliberately separate. Installing ContextGuard only makes local helpers or Claude plugin skills available; it does not write configuration until you run 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.
npm, npx, 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 --with-mcp --plan, then rerun with --yes.

context-guard setup --profile recommended --plan previews the recommended profile and --yes applies it. Before applying setup, run context-guard setup --verify for a read-only health check; context-guard doctor is an alias of it. Homebrew, user-scope rules, and the cross-agent adapter matrix are in docs/guide.md, and the generated flag reference is in docs/setup-reference.md.

Run audit first

Run the audit before you enable anything. Guardrails cost something to run and not every one pays off on every project, so measure your own workload first:

context-guard-audit ~/.claude/projects --top 20 --recommend

After setup, context-guard doctor --root . --json re-checks the installed hook journal and configuration without changing them. The byte figures the audit reports are observations, not savings.

Where the rest lives

• docs/guide.md — every helper command, brief mode, quiet narration, the cross-agent adapters, the benchmark runner, the local MCP adapter, opt-in bash_reference_v1, and the Receipt companion. Pack options such as --explain, --adaptive-k-policy, --apply-adaptive-k, and --apply-symbol-memory are documented there.
• docs/safety-reference.md — trust boundaries, the PATH helper policy, what ContextGuard does not do, the standing-cost and break-even table for advisory rule blocks, the Read-guard TOCTOU limit, and the wording rules for savings claims.
• docs/builtin-overlap.md — feature-by-feature comparison with what Claude Code already does built in (overlap, complement, or not built in).
• docs/experiments.md — tombstone for the experimental lanes removed in 0.14.0.
• docs/setup-reference.md — generated setup capability and flag reference.
• docs/release-runbook.md — release workflow, evidence checklist, and rollback checklist.
• docs/experimental-benchmark-fixtures.md — fixture-only experimental task/variant starters; they clear the same matched-task benchmark gates before any savings claim.

Experimental features

The context-guard experiments command and its plan-only experimental lanes were removed in 0.14.0 — none of them produced runtime behaviour, and none ever cleared the provider-measured matched-task gate that a hosted API savings claim requires. See docs/experiments.md. The wider research lanes are still tracked in research/experimental-token-reduction-radar.md. ContextGuard does not guarantee a fixed token or cost reduction; the claim boundaries are in docs/safety-reference.md.

License

Copyright 2026 jinhongan. Licensed under the Apache License 2.0. See LICENSE and NOTICE.