🚀 The Problem: "Lost in the Middle"

Standard context tools act like dump trucks: they take your entire src/ folder and throw 200,000 tokens into your LLM. The result? LLMs hallucinate, lose focus on instructions hidden in the middle of long contexts, and cost you $2 per prompt.

ContextSniper acts like a sniper rifle. You give it a target task ("fix auth middleware"), and it selectively extracts only the 5-10 files that matter, keeping your context under a strict token budget.

✨ Features

• 🎯 Task-Aware Selection: Uses BM25 scoring to find files semantically related to your task.
• 🕸️ Dependency Graph Boost: Automatically traces import and require statements. If a file is relevant, its dependencies get a relevance boost.
• 📉 Graceful Degradation: If a file doesn't fit in your token budget, it isn't just dropped. ContextSniper trims it down to its method and class signatures (e.g., export function login(user) { /* ... */ }).
• 🔒 100% Local & Private: No code ever leaves your machine. All AST parsing and token scoring happens locally.
• ⚡ Lightning Fast: Scans and scores hundreds of files in milliseconds.
• 🔄 Watch Mode: Live context sync that updates your clipboard automatically as you code.

📦 Installation

# Global installation (coming soon to npm)
# npm install -g context-sniper

# Or run instantly via npx
npx context-sniper "your task"

💻 Usage

1. Basic Task Search

Provide a description of what you are working on, and ContextSniper will find the relevant files.

ctx-snipe "add auth via Supabase" --budget 15000

2. Explain Mode (Transparency)

Analyze why certain files were selected without generating the full context payload.

ctx-snipe "fix auth middleware" --explain

Output includes file scores, exact token counts, and matching reasons (e.g., "BM25 match", "Imported by high-score file").

3. Presets for Common Tasks

Use predefined keywords to quickly grab specific domains of your app.

ctx-snipe --preset database --budget 8000 --copy

Available presets: auth, api, database, styling.

4. Diff-Only Mode (PR Reviews)

Packs only the files that have uncommitted changes or are staged in Git. Perfect for asking an LLM to review your current work.

ctx-snipe --diff-only --copy

5. Watch Mode (Live Sync)

Watch for file changes and automatically recalculate and copy context to clipboard as you code.

ctx-snipe "refactor checkout" --watch --copy

🛠️ Configuration & Options

| Option | Description | Default | | :--- | :--- | :--- | | -t, --target <task> | Target task description | Required | | -b, --budget <tokens>| Maximum token limit for the context | 30000 | | --preset <type> | Predefined task preset | undefined | | -o, --output <file> | Custom output file path | AI_CONTEXT.md | | --copy | Automatically copy output to clipboard | false | | --explain | Show scoring breakdown instead of packing | false | | --diff-only | Only include git modified/staged files | false | | --watch | Live reload context on file save | false | | --no-tree | Exclude project tree from context | false | | --no-git-diff | Exclude uncommitted diff from context | false |

📄 License

MIT © EGN Labs