🛡️ contextshield

Before you paste code into an LLM, contextshield finds secrets, filters noise, orders context, and outputs the optimal prompt pack.

Every time you paste your repository code into Cursor, Copilot, ChatGPT, Gemini, or Claude, you are wasting money, hitting token limits, and risking leaking your API keys.

contextshield makes your repo LLM-ready in one command. It recursively scans your workspace, applies robust .gitignore and default exclusions (lockfiles, node_modules, binaries, build dirs, maps), runs a high-fidelity secret scanner, packs files intelligently by priority, and writes an optimized prompt pack file (with all secrets masked for safety!).

✨ Features

• 🚀 Zero Setup: Run it instantly using npx or install globally.
• 🔒 Zero Leak Promise: High-fidelity detection of OpenAI keys, AWS access keys, Stripe keys, GitHub PATs, private keys, and high-entropy database credentials. Any detected secret is automatically masked in the output pack.
• 🧹 Auto-Junk Exclusion: Filters out lockfiles, node_modules/, binary/image files, build folders (dist/, build/), sourcemaps, IDE configs, and logs.
• 📊 Token Budgeting & Truncation: Specify your target token budget (e.g. 8k, 32k, 100k). If the repo exceeds it, contextshield prioritizes critical configurations and source code, truncating files at the margin to fit perfectly.
• 🌲 Dynamic Tree Generator: Includes a clean, folder-first ASCII directory tree of the packed context at the top of your prompt pack.
• 🎨 Rich CLI Dashboard: Beautiful terminal progress indicators, progress bars, and alerts.

⚡️ Quick Start in 3 Commands

1. Run it instantly (Zero Install)

Scan your current directory with a default 100k token budget:

npx contextshield .

2. Customize the Token Budget

Set a specific budget (e.g., 32k tokens for Claude 3.5 Sonnet context, or 8k for smaller windows):

npx contextshield . -b 32k

3. Specify Custom Output File

Output your prompt pack to a custom path:

npx contextshield . -b 100k -o my-prompt-pack.md

📊 Benchmarks & Token Savings

By filtering junk and lockfiles, contextshield routinely saves 95%+ on token costs, ensuring you stay well within LLM context limits.

| Project Size / Type | Raw Codebase Size | Packed Prompt Size | Token Savings | Secrets Caught | | :--- | :---: | :---: | :---: | :---: | | Vite / React SPA | 342,000 tokens | 12,400 tokens | 96.3% | 1 (mock .env key) | | Express.js API | 185,000 tokens | 8,200 tokens | 95.5% | 2 (leaked API keys) | | Next.js Fullstack app | 2,150,000 tokens | 38,000 tokens | 98.2% | 0 | | Fastify Plugin | 98,000 tokens | 5,100 tokens | 94.8% | 0 |

🎪 Interactive Examples / Playground

contextshield ships with 10 pre-configured playgrounds demonstrating how the CLI solves different repo issues. To set them up, clone the repo and run:

npm run setup-examples

This creates the following playgrounds in the ./examples/ directory:

1. 01-secrets-leak: Contains a simulated OpenAI Key and AWS credential to demonstrate the scanner and automated masking.
2. 02-token-bloat-lockfiles: Contains a massive mock lockfile. Watch contextshield reduce token sizes by 99%.
3. 03-token-bloat-build-folder: Contains huge transpiled javascript bundles and sourcemaps in dist/ showing how they are ignored.
4. 04-broken-context-order-tests: Demonstrates context priority sorting (configs & source code are prioritized over test files).
5. 05-binary-bloat: Contains image files to show how they are filtered using MIME types and content inspection.
6. 06-custom-gitignore: Demonstrates that .gitignore rules (like custom log/temp files) are fully respected.
7. 07-deep-nesting-tree: Shows how the directory structure tree is generated for deeply nested components.
8. 08-truncate-critical: Shows how contextshield truncates long files at the margin to fit tiny budgets (e.g. npx contextshield examples/08-truncate-critical -b 200).
9. 09-clean-prompt-pack: A standard clean playground template.
10. 10-multi-language: Shows syntax highlighting mapping in Python, Rust, Go, CSS, and HTML file blocks.

🛠 Usage Options

Usage: contextshield [options] [dir]

Before you paste code into an LLM, contextshield finds secrets, huge noise, broken context order, and outputs the optimal prompt pack.

Arguments:
  dir                    directory to scan (default: ".")

Options:
  -b, --budget <tokens>  token budget (e.g. 8k, 32k, 100k) (default: "100k")
  -o, --output <file>    output file name (default: "contextshield-prompt.md")
  --max-size <size>      max individual file size limit (e.g. 500kb, 1mb) (default: "1mb")
  --no-secrets           skip checking for secrets
  --secrets-only         only scan for secrets and print warnings, do not generate prompt pack
  -h, --help             display help for command

📜 License

MIT License. Feel free to use and distribute.