@ictechgy/context-guard 0.4.0

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

@@ -0,0 +1,65 @@
+# ContextGuard brief mode (advisory)
+
+Brief mode is a set of **agent-neutral, advisory** rule snippets that ask a coding/tool
+agent to cut filler from its responses while preserving the technical evidence a reviewer
+needs. It is guidance text, not an enforcement mechanism.
+
+- **Advisory / best-effort.** Compatible agents may follow these rules fully, partially, or
+  ignore them. Brief mode does not intercept, rewrite, or block model output.
+- **No guaranteed savings.** Brief mode does **not** promise any token or cost reduction.
+  Verbosity behavior varies by agent and model. Measure real before/after results for your
+  own tasks with `context-guard-bench` before making any savings claim.
+- **Evidence first.** Every level keeps the same mandatory evidence floor (see below). Brief
+  mode trims wording, never correctness-critical content.
+- **Local and reversible.** Snippets are plain text you install into an agent's own rule or
+  instruction file. They are delimited by stable markers so a setup/adapter step can add or
+  remove them without touching unrelated configuration.
+
+## Levels
+
+Brief mode ships three deterministic levels. Each level file contains one marker-delimited
+block that is safe to copy into an agent rules file as-is.
+
+| Level | File | Verbosity dial |
+| --- | --- | --- |
+| `lite` | [`brief-mode.lite.md`](brief-mode.lite.md) | Drop pleasantries and restated context; keep explanations where they aid understanding. |
+| `standard` | [`brief-mode.standard.md`](brief-mode.standard.md) | Answer first, bullets over paragraphs, one short rationale line where it matters. |
+| `ultra` | [`brief-mode.ultra.md`](brief-mode.ultra.md) | Telegraphic: results/bullets/tables only, no preamble or self-narration. |
+
+The levels differ only in how aggressively they cut wording. They never differ in what
+evidence must be preserved.
+
+## Mandatory evidence floor (all levels)
+
+A brief-mode response must still include, whenever relevant:
+
+1. **File paths** — exact paths, with line numbers where useful (e.g. `src/app.py:42`).
+2. **Commands** — the exact commands that were run.
+3. **Command output / failure evidence** — relevant output, error messages, stack traces,
+   and exit codes. Never hide a failure to look terse.
+4. **Code blocks** — when code is needed for correctness, keep it in a fenced block.
+5. **Verification status** — what was run to verify, and whether it passed or failed.
+6. **Changed files** — the list of files created, modified, or deleted.
+7. **Known gaps** — TODOs, untested paths, and assumptions made.
+8. **Caveats** — uncertainty and anything the reader must double-check.
+
+## Installing and removing
+
+Brief mode is installed by copying the marker-delimited block from a level file into the
+target agent's rule/instruction file (for example a repo `AGENTS.md`, `CLAUDE.md`,
+`.cursorrules`, or `.github/copilot-instructions.md`). The cross-agent setup planner is the
+intended automation for this; per the project safety rules it stays dry-run first, writes
+only local files, backs up before changing anything, and applies only with explicit
+approval.
+
+Each block is wrapped in stable markers:
+
+```text
+<!-- BEGIN context-guard:brief-mode level=<level> version=1 -->
+...rules...
+<!-- END context-guard:brief-mode -->
+```
+
+To remove brief mode, delete the block between (and including) those two marker lines. Only
+one brief-mode block should be present at a time; installing a different level replaces the
+existing block rather than stacking a second one.

package/plugins/context-guard/brief/brief-mode.lite.md

@@ -0,0 +1,29 @@
+# Brief mode — lite (advisory)
+
+Lightest level. Trims pleasantries and restated context while keeping explanations where they
+genuinely aid understanding. Advisory and best-effort: a compatible agent may follow it
+partially or ignore it, and it does **not** guarantee any token or cost savings. Copy the block
+below into your agent's rule/instruction file; remove it by deleting the marked block.
+
+<!-- BEGIN context-guard:brief-mode level=lite version=1 -->
+## Response style: brief mode (lite) — advisory
+
+Keep replies focused. This is best-effort guidance, not a hard rule.
+
+- Skip greetings, apologies, self-congratulation, and restating the request back to me.
+- Don't narrate what you are about to do; just do it and report the result.
+- Explanations are welcome where they aid understanding — trim them, don't delete them.
+
+Always preserve this evidence, even when trimming wording:
+
+- Exact file paths, with line numbers where useful (e.g. `src/app.py:42`).
+- The exact commands you ran.
+- Relevant command output, error messages, stack traces, and exit codes — never hide a failure.
+- Code in fenced blocks whenever code is needed for correctness.
+- Verification status: what you ran and whether it passed or failed.
+- The list of changed files.
+- Known gaps, TODOs, and assumptions.
+- Caveats and anything I should double-check.
+
+This guidance does not promise reduced tokens or cost; measure real results before claiming savings.
+<!-- END context-guard:brief-mode -->

package/plugins/context-guard/brief/brief-mode.standard.md

@@ -0,0 +1,31 @@
+# Brief mode — standard (advisory)
+
+Balanced level. Answer first, bullets over paragraphs, one short rationale line where it
+matters. Advisory and best-effort: a compatible agent may follow it partially or ignore it,
+and it does **not** guarantee any token or cost savings. Copy the block below into your
+agent's rule/instruction file; remove it by deleting the marked block.
+
+<!-- BEGIN context-guard:brief-mode level=standard version=1 -->
+## Response style: brief mode (standard) — advisory
+
+Be concise by default. This is best-effort guidance, not a hard rule.
+
+- Lead with the answer or result; put detail after it only if it is needed.
+- Prefer bullet points and short tables over paragraphs.
+- Keep at most one short rationale line where a choice is non-obvious.
+- Drop greetings, apologies, restated context, and "I will now..." narration.
+- Don't pad with summaries of work you already showed.
+
+Always preserve this evidence, even at this terseness:
+
+- Exact file paths, with line numbers where useful (e.g. `src/app.py:42`).
+- The exact commands you ran.
+- Relevant command output, error messages, stack traces, and exit codes — never hide a failure to look terse.
+- Code in fenced blocks whenever code is needed for correctness.
+- Verification status: what you ran and whether it passed or failed.
+- The list of changed files.
+- Known gaps, TODOs, and assumptions.
+- Caveats and anything I should double-check.
+
+This guidance does not promise reduced tokens or cost; measure real results before claiming savings.
+<!-- END context-guard:brief-mode -->

package/plugins/context-guard/brief/brief-mode.ultra.md

@@ -0,0 +1,32 @@
+# Brief mode — ultra (advisory)
+
+Most aggressive level. Telegraphic output: results, bullets, and tables only, with no preamble
+or self-narration. Advisory and best-effort: a compatible agent may follow it partially or
+ignore it, and it does **not** guarantee any token or cost savings. The evidence floor below is
+never dropped, no matter how terse. Copy the block below into your agent's rule/instruction
+file; remove it by deleting the marked block.
+
+<!-- BEGIN context-guard:brief-mode level=ultra version=1 -->
+## Response style: brief mode (ultra) — advisory
+
+Maximum terseness. Best-effort guidance, not a hard rule.
+
+- Result first. No preamble, no greeting, no apology, no restated request.
+- No self-narration ("I'll now...", "Let me...", "Here is..."). Just the content.
+- Use bullets, tables, and short fragments. Avoid connective prose.
+- No closing summary of what you just did.
+- Terseness must never remove correctness-critical content or hide problems.
+
+Never drop this evidence, however terse:
+
+- Exact file paths + line numbers where useful (e.g. `src/app.py:42`).
+- Exact commands run.
+- Relevant output, errors, stack traces, exit codes — surface failures, don't bury them.
+- Fenced code blocks when code is needed for correctness.
+- Verification status: command run + pass/fail.
+- Changed files list.
+- Known gaps, TODOs, assumptions.
+- Caveats / what to double-check.
+
+Does not promise reduced tokens or cost; measure real results before claiming savings.
+<!-- END context-guard:brief-mode -->

package/plugins/context-guard/lib/hook_secret_patterns.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""Shared high-confidence secret patterns for hook-visible text.
+
+These patterns are intentionally narrower than the full output sanitizer: hooks
+use them on user-controlled path labels and short diagnostics where false
+positives should redact the whole label rather than rewrite large command
+output. Keep alternatives bounded or structurally linear; hooks run before any
+downstream sanitizer can protect their own stderr/JSON output.
+"""
+from __future__ import annotations
+
+import re
+
+
+CONTROL_CHAR_RE = re.compile(r"[\x00-\x1f\x7f-\x9f]")
+SENSITIVE_HOOK_TEXT_RE = re.compile(
+    r"(?i)("
+    r"gh[pousr]_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,}|"
+    r"glpat-[A-Za-z0-9_-]{12,}|(?:AKIA|ASIA)[0-9A-Z]{16}|"
+    r"(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{16,}|"
+    r"sk-(?:ant|proj)-[A-Za-z0-9_-]{8,}|xox[abprs]-[A-Za-z0-9-]{8,}|"
+    r"npm_[A-Za-z0-9]{20,}|AIza[0-9A-Za-z_-]{20,}|"
+    r"SG\.[A-Za-z0-9_-]{16,256}\.[A-Za-z0-9_-]{16,512}|"
+    r"eyJ[A-Za-z0-9_-]*(?:\.[A-Za-z0-9_-]*){2}|"
+    r"\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{12,}|"
+    r"[a-z][a-z0-9+.-]{0,31}:/+(?:[^/\s:@]{0,256}:[^/\s@]{0,2048}|[^/\s@]{1,2048})@|"
+    r"(?<![A-Za-z0-9])(?:api[_-]?key|token|secret|password|client[_-]?secret)\s*(?:=|:|%3d)[^/\\\s]{4,})"
+)
+
+
+def hook_text_has_sensitive_evidence(value: str) -> bool:
+    """Return True when hook-visible text contains a high-confidence secret."""
+    return bool(SENSITIVE_HOOK_TEXT_RE.search(value))
+
+
+def hook_label_has_sensitive_evidence(value: str) -> bool:
+    """Return True when a compact hook-visible label must be fully redacted."""
+    return bool(CONTROL_CHAR_RE.search(value) or hook_text_has_sensitive_evidence(value))
+
+
+def redact_sensitive_hook_text(value: str, replacement: str = "[redacted]") -> str:
+    """Redact high-confidence secrets from hook-visible text."""
+    return SENSITIVE_HOOK_TEXT_RE.sub(replacement, value)

package/plugins/context-guard/skills/audit/SKILL.md

@@ -0,0 +1,39 @@
+---
+description: Audit local Claude Code transcript usage and summarize likely token hotspots. Use when the user asks where Claude Code tokens are going or wants evidence before optimizing.
+argument-hint: [optional transcript path]
+disable-model-invocation: true
+---
+
+# ContextGuard Audit
+
+Run a best-effort transcript audit, then interpret the result conservatively.
+
+Default command:
+
+```bash
+context-guard-audit ~/.claude/projects --top 20 --recommend
+```
+
+If the user supplies a path, audit that path instead. If no path is supplied, keep the default Claude projects path:
+
+```bash
+if [ -n "$ARGUMENTS" ]; then
+  context-guard-audit "$ARGUMENTS" --top 20 --recommend
+else
+  context-guard-audit ~/.claude/projects --top 20 --recommend
+fi
+```
+
+Report:
+
+- observed token buckets: input, output, cache_read, cache_creation;
+- model distribution;
+- query_source distribution: main, subagent, auxiliary;
+- top transcript files and commands observed;
+- generated recommendations with priority, reason, action, and evidence;
+- `cache_friendliness` status, bounded prefix/tail churn signals, and any cache-layout findings;
+- top likely causes and one safe next experiment.
+
+Privacy: default output uses basename+hash transcript labels and command category+hash labels. Do not ask for `--show-paths` or `--show-commands` unless the user explicitly wants local identifiers in the report. Cache-friendliness diagnostics use bounded redacted segment hashes and do not print raw prompt text. Recommendations are heuristics; treat them as hypotheses, especially with small `files` or `records` counts.
+
+Caveat: Claude Code transcript schemas can change. Treat this as an operational signal, not billing authority. `cache_read`/`cache_creation` and `cache_friendliness` are provider-cache diagnostics, not proof of ContextGuard-caused token reduction. For billing authority, use Claude Console, cloud-provider billing, or configured OpenTelemetry metrics.

package/plugins/context-guard/skills/optimize/SKILL.md

@@ -0,0 +1,48 @@
+---
+description: Diagnose and reduce Claude Code token usage for a project or session using context hygiene, model and effort routing, MCP minimization, output trimming/sanitizing, subagent discipline, and measurement. Use when the user asks to lower Claude Code token usage, cost, context bloat, or usage-limit burn.
+argument-hint: [project/session symptoms]
+allowed-tools: Bash(context-guard-setup *), Bash(context-guard-audit *), Bash(context-guard-diet scan *), Bash(context-guard-read-symbol *), Bash(context-guard-artifact store *), Bash(context-guard-artifact get *), Bash(context-guard-artifact list *), Bash(context-guard-statusline)
+---
+
+# ContextGuard
+
+Goal: reduce Claude Code token usage without lowering task success quality.
+
+Use this order:
+
+1. Measure before changing behavior.
+   - Ask the user to run `/usage` and `/context` if inside Claude Code.
+   - For first-time setup, run `context-guard-setup --plan` and offer `context-guard-setup --yes` for recommended project-local settings.
+   - If transcript files are available, run `context-guard-audit ~/.claude/projects --top 20 --recommend`.
+   - For project configuration/context bloat, run `context-guard-diet scan .`.
+2. Identify the largest bucket:
+   - stale conversation history -> recommend `/clear` between unrelated tasks and focused `/compact` for long tasks.
+   - startup context -> prune `CLAUDE.md`, move long workflows to skills, disable unused MCP servers.
+   - large file reads -> use `context-guard-read-symbol` and the example Read guard before whole-file context.
+   - very large logs that may need later exact slices -> store sanitized output with `context-guard-artifact store` and query only needed lines/patterns.
+   - noisy command output -> use `context-guard-trim-output` wrappers or the example PreToolUse hook.
+   - grep/diff output with possible secrets -> use `context-guard-sanitize-output` or the example Bash hook.
+   - expensive reasoning -> route default work to `sonnet` and lower `/effort`; reserve Opus/`opusplan` for planning.
+   - noisy exploration -> keep it local: use `rg`, `context-guard-read-symbol`, artifact queries, or a bounded subagent only when parallel value justifies the multiplier.
+3. Produce a minimal action plan with:
+   - immediate changes,
+   - config or hook snippets,
+   - validation command,
+   - risks and rollback.
+4. Do not recommend payment/limit bypasses, account sharing, leaked-source patches, or other unsafe/unauthorized methods.
+
+Useful local commands provided by this plugin:
+
+```bash
+context-guard-audit ~/.claude/projects --top 20 --recommend
+context-guard-setup --plan
+context-guard-diet scan .
+context-guard-read-symbol path/to/file.py TargetSymbol
+context-guard-artifact store --command "long-command" --json < large.log
+context-guard-artifact get <artifact_id> --lines 1:80
+context-guard-trim-output --max-lines 120 -- npm test
+context-guard-sanitize-output -- rg -n "TOKEN|SECRET" .
+context-guard-statusline
+```
+
+If installing hook examples, prefer project-local opt-in settings first. Do not silently modify global `~/.claude/settings.json`.

package/plugins/context-guard/skills/setup/SKILL.md

@@ -0,0 +1,40 @@
+---
+description: Interactive or guided project setup for Claude Code token optimizer settings. Use when the user asks to install, configure, setup, enable hooks, or choose token-saving options interactively.
+argument-hint: [plan|apply|options]
+allowed-tools: Bash(context-guard-setup *), Bash(context-guard-diet scan *)
+---
+
+# ContextGuard Setup
+
+Goal: help the user configure this plugin without memorizing helper commands.
+
+Default flow:
+
+1. Run a read-only plan first:
+
+```bash
+context-guard-setup --plan
+```
+
+2. Explain the options briefly:
+   - deny bulky/sensitive reads,
+   - token/cost statusline,
+   - Bash trim + grep/diff sanitizer hook,
+   - large Read guard,
+   - failed-attempt nudge for repeated Bash failures,
+   - missing model/effort defaults.
+3. If the user wants the recommended project-local setup, run:
+
+```bash
+context-guard-setup --yes
+```
+
+4. Treat the post-apply `context-guard-diet scan` summary emitted by setup as the default remaining-gap check; run `context-guard-diet scan .` separately only when the user wants the full report.
+5. For automation that must skip the post-apply scan summary, run `context-guard-setup --no-diet-scan --yes`.
+6. If they want extra token reduction beyond setup, prefer local artifact escrow, symbol reads, and semantic digests rather than external model offload.
+
+Safety:
+
+- Do not modify global `~/.claude/settings.json`.
+- Prefer project-local `.claude/settings.json`.
+- Setup's post-apply scan is local, read-only, and prints a summary only; it does not mutate settings.