context-audit

context-audit

A Claude Code skill that audits your context hygiene and reports token waste. Produces a Context Health Score (1-100), a concrete per-turn overhead in tokens, and a ranked list of fixes you can approve one-by-one.

Nothing changes without your explicit y. Every write is backed up first.

What it checks

Area	Examples
CLAUDE.md	Default-behavior rules, contradictions, cross-file duplicates, verbose reference blocks, stale notes
settings.json	Missing permissions.deny for heavy dirs, unused allow entries, version-specific context keys
MCP servers	Heavy schemas (chrome-devtools, playwright, notion, etc.), broken MCPs, zero-usage MCPs, CLI alternatives
Skills	Oversized SKILL.md (>400 lines), description-workflow leak (CSO bug)
Custom agents	Bloated system prompts, agents duplicating skills, never-invoked agents
Hooks & statusline	Per-turn hook output size, statusline latency (>200ms)
Compact pressure	Auto-compact rate over last 30 days

How it works

1. Step 0 — schema discovery. Probes the live settings.json schema. If a key isn't in the current schema, the skill will not propose it. No guesses.
2. Self-test. The skill audits its own SKILL.md first. A bloated audit skill has no business lecturing you about bloat.
3. Measurement, not estimates. Token counts come from wc -c divided by 4. Every finding reports real numbers plus bytes so you can verify.
4. One-by-one walkthrough. Each finding is tagged:
   • [AUTO] — safe, reversible, one-shot.
   • [DECIDE] — you pick the action.
   • [MANUAL] — you apply a printed diff.
5. Safety. Every write backs up first (file.bak.<timestamp>). Validation error → auto-restore, drop the item, tell you honestly.

Install

Claude Code only. This skill is built against Claude Code internals — settings.json schema, claude mcp list, ~/.claude/projects/*.jsonl transcripts, ~/.claude/skills/ path. Other agents (Gemini CLI, Codex, Cursor, Windsurf, Copilot, Cline) are not supported in v0.1.

Option A — plugin marketplace (recommended)

Inside Claude Code:

/plugin marketplace add CShark-Hub/context-audit
/plugin install context-audit@cshark-context-audit

Or add manually to ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "cshark-context-audit": {
      "source": { "source": "github", "repo": "CShark-Hub/context-audit" }
    }
  },
  "enabledPlugins": {
    "context-audit@cshark-context-audit": true
  }
}

Restart the session. Disable with /plugin disable context-audit@cshark-context-audit or flip the key to false.

Option B — install script

macOS / Linux / WSL / Git Bash:

git clone https://github.com/CShark-Hub/context-audit.git && cd context-audit && ./install.sh

Windows PowerShell:

git clone https://github.com/CShark-Hub/context-audit.git; cd context-audit; .\install.ps1

Both copy skills/context-audit/SKILL.md to ~/.claude/skills/context-audit/SKILL.md (Windows: %USERPROFILE%\.claude\skills\context-audit\SKILL.md). Existing file is backed up with a timestamp.

Option C — fully manual

mkdir -p ~/.claude/skills/context-audit
curl -o ~/.claude/skills/context-audit/SKILL.md \
  https://raw.githubusercontent.com/CShark-Hub/context-audit/main/skills/context-audit/SKILL.md

# Windows PowerShell
$dest = "$HOME\.claude\skills\context-audit"
New-Item -ItemType Directory -Force -Path $dest | Out-Null
Invoke-WebRequest `
  -Uri "https://raw.githubusercontent.com/CShark-Hub/context-audit/main/skills/context-audit/SKILL.md" `
  -OutFile "$dest\SKILL.md"

Usage

Start a new Claude Code session (skills are loaded at startup). Then:

audit my context

or

/context-audit

or just tell Claude what you're after — "my sessions hit compact too early, check my setup" — the skill auto-triggers on phrases like these.

The skill will:

1. Scan CLAUDE.md, settings.json, MCPs, skills, hooks.
2. Print a health report.
3. Walk findings one by one.
4. For each: show options, wait for your number, apply immediately.
5. Back up any file before writing.

Example session

# Context Health Report
Score: 72/100
Per-turn overhead: ~6200 tokens

Breakdown:
- CLAUDE.md:  25/25
- Settings:    5/25   [3 findings]
- Resources:  17/25   [3 findings]
- Hooks:      25/25

## Findings
[1/6] [AUTO] Settings: missing `permissions.deny` for heavy dirs
  Options: 1) Add all 7  2) Pick subset  3) Skip  4) Stop
> 1

Backup: ~/.claude/settings.json.bak.1776941541
Applied. Next item...

What it will NOT do

• Write anything without your explicit approval.
• Propose settings keys it can't verify in the current schema.
• Remove MCP servers or modify skills.
• Auto-edit CLAUDE.md beyond exact-duplicate removal.
• Touch managed (enterprise policy) settings.

Uninstall

rm -rf ~/.claude/skills/context-audit