🇬🇧 English | 🇹🇷 Türkçe Dokümantasyon

📦 smart-context-packer (scp)

High-Fidelity AI Context Packer & Multi-Language Dependency Graph Analyzer

Pack only the code your AI assistant actually needs to see — zero hallucinations, minimal tokens.

Quickstart • Features • 16-Language Polyglot • Universal Agent Presets • Active Task Engine • Tool Output Sandbox • PageRank Repo-Map • BM25 Intent Search • OSS Comparison • CLI Usage • 15-Tool MCP Suite

💡 The Problem

When developing with AI assistants (ChatGPT, Claude, Gemini, Cursor, Copilot, Codex, OpenCode, Aider, Windsurf), developers constantly face two extremes:

1. The "Full Repository Dump" Trap: Tools dump the entire codebase into a 90k+ token mega-prompt. The AI loses focus on the real task, exceeds context budgets, racks up enormous API bills, and gets confused by irrelevant boilerplate.

2. The "Isolated File" Trap: The developer copies a single file. The AI immediately hallucinates missing function implementations, invents nonexistent interfaces, and generates code that breaks workspace imports.

The Solution: smart-context-packer (scp v2.4)

scp takes your target entry file(s), analyzes their directed dependency graph across 16 programming languages, redacts sensitive credentials, and packages ONLY the target files and their direct/transitive local dependencies into a clean, token-counted prompt equipped with an AI pre-flight directive header.

In v2.4.0, smart-context-packer brings Symbol-Level AST Tree-Shaking (--tree-shake), Automatic Monorepo Workspace Resolution (packages/*, apps/*, pnpm-workspace.yaml), Git Commit & PR Packing (--commit, --pr), Live File Watch Mode (-w, --watch), 16-Language Ultra-Polyglot AST Support, 12 Universal AI Agent Presets, and Surgical Layer 4 MCP Suite (15 native tools) — all with zero external binary dependencies (no Python, no Bun, no ChromaDB, no SQLite).

Related MCP server: io.github.pmgarg/cgraphy

🏆 How scp v2.4 Compares to the Best OSS Tools

⚡ Quickstart

No installation required — run instantly with npx:

# Analyze a file, bundle dependencies up to depth 2, and copy to clipboard:
npx smart-context-packer src/auth/login.ts -c

# Shorthand alias with skeleton mode:
npx scp src/server.ts -d 2 -s -c

# Auto-skeletonize deep dependencies to strictly fit within token budget:
npx scp src/server.ts -m 4000 -c

# Pack all uncommitted Git changes + dependencies + unified diff patch:
npx scp --diff -c

# Configure AI coding assistants (Cursor, Antigravity, Copilot) background rules:
npx scp --init-agent

# Start zero-dependency Model Context Protocol (MCP) stdio server:
npx scp --mcp

# Generate VS Code / Cursor Command Palette tasks:
npx scp --init-vscode

Or install globally / locally:

# Global installation
npm install -g smart-context-packer

# Local dependency
npm install -D smart-context-packer

📊 Terminal Experience

When you run scp, you receive an instant terminal breakdown:

╭─────────────────────────────────────────────────────────────╮
│ 📦  smart-context-packer summary                            │
├─────────────────────────────────────────────────────────────┤
│ Targets:              1 target file(s)                      │
│ Packed Files:         4 total (3 deps, 1 skeleton)          │
│ Lines of Code:        248                                   │
│ Total Characters:     6,820                                 │
│ Estimated Tokens:     1,640 tokens                          │
├─────────────────────────────────────────────────────────────┤
│ Context Window Usage:                                       │
│  • 128k (GPT-4o):     1.25%                                 │
│  • 200k (Claude/Gemini): 0.80%                              │
├─────────────────────────────────────────────────────────────┤
│ Output File:          .context-pack.md                      │
│ Clipboard:            ✔ Copied to system clipboard          │
╰─────────────────────────────────────────────────────────────╯

✔ Prompt saved to /workspace/.context-pack.md
✔ Copied to clipboard! Ready to paste into ChatGPT, Claude, Cursor, or Gemini.

🚀 Key Features

1. 🧠 Multi-Language Dependency Graph Engine

• TypeScript, JavaScript, JSX, TSX: Resolves static import, dynamic import(), export ... from, and CommonJS require().

• NodeNext Extension Mapping: Automatically resolves .js import specifiers to .ts/.tsx source files on disk.

• Path Aliases: Automatically reads tsconfig.json or jsconfig.json path mappings (e.g. @/* -> src/*, ~/* -> ./*).

• Vue 3 SFCs: Extracts script blocks from .vue components and traces subcomponent/composable imports.

• Lua & FiveM: Parses fxmanifest.lua tables (shared_scripts, client_scripts, server_scripts with glob expansion) and Lua dot-notation require('client.utils').

2. 🛡️ Automatic Secret & Token Redaction

Never accidentally leak API keys to third-party LLMs:

• OpenAI Keys (sk-..., sk-proj-...) -> [REDACTED_OPENAI_KEY]

• Anthropic Keys (sk-ant-...) -> [REDACTED_ANTHROPIC_KEY]

• GitHub Tokens (ghp_..., github_pat_...) -> [REDACTED_GITHUB_TOKEN]

• AWS Credentials (AKIA...) -> [REDACTED_AWS_KEY]

• Private Key PEM Blocks (-----BEGIN PRIVATE KEY-----) -> [REDACTED_PRIVATE_KEY]

• Database Connection Strings (postgres://user:pass@host/db) -> postgres://user:[REDACTED]@host/db

• .env* assignments masked automatically.

3. ✂️ Skeleton / Signature Mode (--skeleton)

Save up to 85% more tokens on deep dependencies. Deep files have their internal function and method bodies replaced with type signatures:

// Original in deep dependency:
export function computeLargeData(items: Item[]): ProcessedResult {
  // 150 lines of complex internal algorithmic logic...
}

// In Skeleton Mode:
export function computeLargeData(items: Item[]): ProcessedResult { /* [Implementation omitted for token efficiency] */ }

The AI assistant gains 100% type and API awareness with 85% less token overhead.

4. 🧭 AI Pre-flight Directive & Visual Directory Tree

Every generated prompt begins with a standardized instruction header:

<!-- ============================================================================== -->
<!--                      SMART CONTEXT PACKER: AI DIRECTIVE                        -->
<!-- ============================================================================== -->
<!-- CRITICAL PRE-FLIGHT INSTRUCTIONS FOR AI CODING ASSISTANT:                      -->
<!-- 1. CAREFULLY INSPECT the visual directory tree and dependency graph below.     -->
<!-- 2. ANALYZE all imported symbols, types, and architectural boundaries BEFORE    -->
<!--    proposing or generating any code changes.                                   -->
<!-- 3. PRESERVE existing conventions, naming styles, and strict typing.            -->
<!-- 4. DO NOT invent or hallucinate modules not present in the workspace.          -->
<!-- ============================================================================== -->

Accompanied by a visual ASCII directory tree and dependency relationship map:

.
└── src
    ├── models
    │   └── user.ts [DEP: depth 2]
    ├── services
    │   └── auth.ts [DEP: depth 1, SKELETON]
    └── index.ts [TARGET]

src/index.ts -> imports -> ["src/services/auth.ts"]
src/services/auth.ts -> imports -> ["src/models/user.ts"]

5. 🌿 Git Diff & Working Tree Resolver (--diff, --staged)

Resolve uncommitted modified and untracked files as targets, calculate their full dependency graph, and append a unified ## Git Diff Patch section into the prompt for rapid PR reviews and bugfixes.

6. 🗄️ Smart Prisma Schema Model Extractor

Detects @prisma/client and prisma.<model> usage, parsing schema.prisma and extracting ONLY the models and enums referenced in the packed code (along with 1-level relations) to prevent DB hallucinations without bloating prompts.

7. 🔌 Native Model Context Protocol (MCP) Server (--mcp)

Zero-dependency JSON-RPC 2.0 stdio server enabling AI coding agents (Claude Desktop, Cursor, Antigravity, Cline) to pack context and inspect dependency graphs autonomously.

8. 💻 VS Code & AI IDE Tasks Generator (--init-vscode)

One-command setup of .vscode/tasks.json with three Command Palette tasks for instant clipboard copying of active file context, skeleton signatures, or git diffs.

9. 🎯 Auto Token-Budget Optimizer (--max-tokens)

Automatically monitors the total estimated token count. If the pack exceeds your specified budget, it progressively converts deep dependencies into skeleton signatures (from deepest depth down to depth 1, keeping depth 0 targets intact) to guarantee fitting within LLM window limits.

10. 💥 Blast-Radius & Impacted Test Analyzer (-b, --blast-radius)

Performs reverse fan-in analysis to identify every workspace file calling your targets, locates all associated unit test files (*.test.ts, *.spec.ts, tests/**), warns of untested modifications, and computes a 0.0-10.0 Risk Score (LOW, MEDIUM, HIGH).

11. ⚡ Incremental SHA-256 AST Cache (.scp/cache.json)

Caches parsed AST dependencies, exported symbols, and token metrics keyed by content SHA-256 hash and file mtime. Subsequent runs on large repos execute in milliseconds without any external databases.

12. 🧠 File-Linked Persistent Project Memory (.scp/memory.json)

Store git-friendly architectural decisions, bug gotchas, and invariants linked to file globs. Whenever matching files are packed or edited, their linked memories are automatically injected into the AI context!

13. 🌐 3-Layer Progressive Disclosure MCP Suite

Enables AI coding agents to interact with massive codebases progressively:

• Layer 1: search_codebase_index (~50 tokens per file summary with exported symbols)

• Layer 1: search_codebase_index (ultra-fast compact symbol/file index ~50t)

• Layer 2: inspect_dependency_graph (visual tree, dependency map, circular checks, blast radius)

• Layer 3: pack_context & pack_git_diff (complete or skeletonized source code + diffs + memories)

• Spatial Awareness: generate_repo_map (PageRank architectural bird's-eye map)

• Semantic Intent: search_codebase_intent (BM25 intent search with camelCase boosting)

• Interactive Visualizer: generate_visualizer (offline HTML force-directed canvas report)

• Memory Tools: save_project_memory & query_project_memory for persistent cross-session knowledge.

🗺️ PageRank Architectural Repo-Map (v2.1.0)

When coding in large repositories, LLMs suffer from "tunnel vision" — seeing isolated files without understanding the global architecture. Inspired by Aider's repo-map, scp v2.1 implements Graph PageRank Centrality Ranking (damping factor 0.85, 20 iterations):

# Generate a bird's-eye architectural repo-map (defaults to 1024 token budget):
scp --repo-map -c

# Pack an entry file along with a 500-token global architectural map:
scp src/server.ts --repo-map 500 -c

What It Generates:

• Traverses the entire codebase dependency graph.

• Calculates PageRank scores based on in-degree and dependency authority.

• Extracts exported signatures, interfaces, classes, and types from top architectural hubs.

• Produces a strictly token-budgeted bird's-eye view injected directly into the prompt:

## 🗺️ Codebase Architectural Repo-Map (PageRank Centrality)
### `src/server.ts` (Score: 0.1852)
  - `startServer(port: number): Promise<void>`
  - `app: Express`
### `src/auth/service.ts` (Score: 0.1420)
  - `verifySessionToken(token: string): Promise<User>`
  - `interface UserSession`

🔍 In-Memory BM25 Semantic Intent Routing (v2.1.0)

Don't remember the exact path to a file? With -i, --query, describe what you want in plain English:

# Query by intent: Automatically discovers matching seed files and packs them!
scp -i "jwt auth token verification" -c

# Pipe intent results into skeleton packing with a token budget:
scp -i "stripe payment webhook handler" -m 2000 -c

• Smart Code Tokenizer: Splits camelCase, PascalCase, snake_case, and kebab identifiers into constituent semantic terms (e.g. verifySessionToken -> verify, session, token).

• Symbol Boosting: Exported function/class/interface names receive a 2.5x score multiplier over general file contents.

• Pure In-Memory BM25: Runs in sub-10 milliseconds without external embedding models, Python runtimes, or vector databases.

🎨 Interactive Canvas Dependency Visualizer (v2.1.0)

Inspect your codebase architecture, dependency clusters, and blast radius visually through a standalone, zero-dependency HTML report:

# Generate an interactive HTML report (.scp/visualizer.html) and open it:
scp src/index.ts --visualize

# Specify custom report output:
scp --diff --visualize ./reports/diff-impact.html

Key Visualizer Features:

• Zero-Dependency Native HTML5 Canvas: Embeds physics, styles, and data directly into one file — works completely offline without CDN dependencies.

• Physics Force-Directed Simulation: Real-time interactive node dragging, zooming, and panning.

• Dynamic Node Sizing & Heatmap: Node radius scales by estimated token count. Colors indicate Blast-Radius risk levels (Green = Low, Orange = Medium, Red = High).

• Interactive Inspector Sidebar: Click any node to view incoming/outgoing dependencies, token counts, and full source code.

🛡️ Built-in Enterprise Secret & Credential Redactor (v2.1.0)

Never accidentally upload production credentials, private keys, or API secrets into an LLM context:

# Secret redaction is ENABLED BY DEFAULT across all CLI runs and MCP tools:
scp src/config.ts -c

# Opt out only if specifically needed:
scp src/config.ts --no-redact -c

Detected & Sanitized Secret Patterns:

• Private Keys: RSA, EC, DSA, OpenSSH, and PGP -----BEGIN PRIVATE KEY----- blocks.

• AWS Credentials: AKIA... Access Key IDs and 40-character secret access keys.

• GitHub Tokens: Personal Access Tokens (ghp_..., github_pat_...), OAuth keys, and refresh tokens.

• Stripe Keys: Live and test secret keys (sk_live_..., rk_live_..., sk_test_...).

• AI Platform Keys: OpenAI (sk-proj-..., sk-...), Anthropic (sk-ant-...).

• Slack Tokens: Bot, user, and app tokens (xoxb-..., xoxp-...).

• Database Connection URIs: PostgreSQL, MySQL, MongoDB, Redis URIs with embedded passwords.

• Bearer & JWT Tokens: RFC 7519 3-segment base64url JSON Web Tokens.

🌐 16-Language Ultra-Polyglot AST Engine (v2.3.0)

smart-context-packer v2.3 expands beyond the JavaScript ecosystem into enterprise-grade multi-language AST import resolution, symbol extraction, and skeletonization across 16 programming languages:

💥 Blast-Radius & Impacted Test Analyzer (v2.0.0)

Inspired by tirth8205/code-review-graph, scp v2.0 eliminates fear of unexpected regression breakage during AI refactorings:

# Analyze impact, callers, and tests when editing auth.ts:
scp src/auth.ts -b -c

# Combine with git diff to score the risk of your uncommitted changes:
scp --diff -b -c

Risk Scoring Formula & Levels:

• LOW (0.0 - 3.5): Isolated changes or comprehensive test suite coverage with limited callers.

• MEDIUM (3.6 - 6.9): Moderate fan-in dependencies (1-3 callers) or untested utility modules.

• HIGH (7.0 - 10.0): Critical shared core modules with 4+ callers or zero matching test suites.

AI Context Injection:

When -b is enabled, scp injects a dedicated directive block into the AI prompt:

## 💥 Blast-Radius & Impact Analysis
- **Target Files**: `src/services/auth.ts`
- **Risk Level**: `MEDIUM` (5.2/10)
- **Summary**: ⚠️ MODERATE RISK: 2 callers impacted. 1 test file covers this scope.
- **Impacted Callers (Fan-in)**:
  - `src/controllers/login.ts`
  - `src/server.ts`
- **Impacted Unit Tests**:
  - `tests/auth.test.ts`

⚡ Incremental SHA-256 AST Cache (v2.0.0)

Parsing hundreds of TypeScript and Vue files repeatedly slows down interactive developer loops. scp v2.0 introduces a zero-dependency local disk cache stored in .scp/cache.json:

# Normal runs use the incremental cache automatically:
scp src/index.ts -c

# Bypass the cache:
scp src/index.ts --no-cache -c

# Purge the local cache:
scp --clear-cache

• Two-tier validation: First validates file mtimeMs and fileSize (instant sub-millisecond check). If modified, computes crypto.createHash('sha256') to check if contents actually changed.

• Stored metadata: Caches raw imports, line/token stats, and exported symbol lists (exportedSymbols).

• Zero Bloat: No SQLite binaries, no native C++ bindings, no ChromaDB. Pure Node.js JSON storage.

🧠 File-Linked Persistent Project Memory (v2.0.0)

Inspired by mem0, scp v2.0 provides cross-session architectural retention stored directly in .scp/memory.json (git-tracked so your entire team and AI agents benefit):

# Save an architectural decision or gotcha linked to a file pattern:
scp --add-memory "src/mcp.ts:Never log to stdout in stdio MCP mode to prevent JSON-RPC corruption"
scp --add-memory "src/auth/**:Always verify JWT expiration against UTC server time"

# List all stored project memories:
scp --list-memory

Automatic Context Injection:

Whenever files matching pattern globs are packed (either via CLI scp, VS Code tasks, or MCP tool calls), their linked memories are automatically attached to the AI prompt:

## 🧠 Persistent Project Memory (.scp/memory.json)
- **GOTCHA** (`src/mcp.ts`): Never log to stdout in stdio MCP mode to prevent JSON-RPC corruption

🌐 4-Layer Progressive Disclosure MCP Engine (v2.3.0)

Inspired by claude-mem and modern agentic architectures, scp v2.3 organizes 15 native MCP tools into 4 progressive disclosure layers so autonomous AI agents never exhaust context windows:

┌────────────────────────────────────────────────────────────────────────┐
│  Layer 1: Index & Discovery (~50t compact index, BM25, Repo-Map)       │
│  search_codebase_index | search_codebase_intent | generate_repo_map    │
└───────────────────────────────────┬────────────────────────────────────┘
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│  Layer 2: Topology & Architecture (Imports, Visualizer, Manifests)     │
│  inspect_dependency_graph | generate_visualizer | framework_manifest   │
└───────────────────────────────────┬────────────────────────────────────┘
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│  Layer 3: Slicing & Context Packing (Budget-Optimized Slices & Diffs)  │
│  pack_context | pack_git_diff                                          │
└───────────────────────────────────┬────────────────────────────────────┘
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│  Layer 4: Surgical Fetch & Verification (<200t Symbols, Tests, Leaks) │
│  extract_symbol_definition | get_impacted_tests | audit_context_leak   │
└────────────────────────────────────────────────────────────────────────┘

1. Layer 1 (Discovery & Index):

   • search_codebase_index: Cheaply inspect workspace files, sizes, and exported symbols (~50 tokens per file).

   • search_codebase_intent: Natural-language BM25 semantic intent ranking matching identifiers and stems.

   • generate_repo_map: PageRank architectural bird's-eye map fitting within a strict token budget.

2. Layer 2 (Topology & Architecture):

   • inspect_dependency_graph: Inspect imports, exports, circular cycles, and risk scores without file bodies.

   • generate_visualizer: Interactive offline HTML force-directed canvas report.

   • get_framework_manifest: Grounded workspace dependencies across 12 manifest formats.

3. Layer 3 (Context Slicing):

   • pack_context: Package full or skeletonized file bodies with automatic token-budget optimizer.

   • pack_git_diff: Package uncommitted working tree or staged Git modifications and diff patch.

4. Layer 4 (Surgical Extraction & Auditing):

   • extract_symbol_definition: Surgically extract exact function, class, or struct definitions in <200 tokens.

   • get_impacted_tests: Locate all unit tests covering modified targets via reverse graph traversal.

   • audit_context_leak: Scan prompt text or files for accidental secret or credential leaks.

5. Ops & Cross-Session Memory:

   • manage_task_context: Crash-proof implementation plans and progress checklists (.scp/tasks.json).

   • sandbox_tool_output: Compress noisy test and linter outputs by 80-95%.

   • save_project_memory & query_project_memory: Persistent cross-session architectural rules (.scp/memory.json).

🎯 Auto Token-Budget Optimizer (v1.3.0)

Context limits (or expensive inference costs) often require fitting within a precise token budget. Instead of manually guessing whether to include dependencies or strip function bodies, use --max-tokens:

# Automatically skeletonize dependencies if total pack exceeds 4,000 tokens:
scp src/server.ts -m 4000 -c

How It Works:

1. scp analyzes the full dependency graph and calculates the estimated tokens for all nodes.

2. If total tokens exceed maxTokens:

   • It leaves depth 0 target files intact (preserving all implementation details for files you are actively editing).

   • It sorts non-target dependency files starting from the highest dependency depth (depth 3, then depth 2, then depth 1) and by largest token size.

   • It progressively converts these dependency nodes into skeleton type signatures until the total estimated tokens fall within maxTokens.

3. The terminal summary reports Budget Optimized: ✔ and shows the exact tokens saved (Budget Saved: X tokens).

🤖 Universal AI Agent Presets (v2.3.0)

Stop running manual CLI commands every time you chat with an AI assistant. With one command, configure your AI coding assistants to automatically engineer their own context:

# Generate all 12 agent presets at once:
scp --init-agent

# Or target specific assistants:
scp --init-agent opencode
scp --init-agent codex
scp --init-agent continue
scp --init-agent zed
scp --init-agent clinerules
scp --init-agent aider
scp --init-agent jetbrains

Supported AI Agent Presets:

Autonomous Agent Behavior:

Once initialized, any of your AI assistants will automatically:

• Autonomously invoke inspect_dependency_graph before proposing file modifications.

• Call pack_context with optimal depth and token budgets instead of dumping raw directories.

• Call pack_git_diff to review your uncommitted working tree and staged patches.

• Call surgical Layer 4 tools (extract_symbol_definition, get_impacted_tests, audit_context_leak) to verify changes without burning tokens.

🌿 Git Diff & Working Tree Resolver (v1.2.0)

When you are fixing a bug or building a feature, you usually want the AI to understand what you've modified and how those changes impact adjacent modules.

Using --diff or --staged:

1. scp automatically runs git diff --name-only and git status --porcelain to identify changed, added, or untracked files.

2. It feeds those files as root targets into the DependencyGraph engine, automatically bundling all imported modules and type definitions.

3. It appends a clean unified patch block under ## Git Diff Patch:

## Git Diff Patch

```diff
diff --git a/src/auth/service.ts b/src/auth/service.ts
--- a/src/auth/service.ts
+++ b/src/auth/service.ts
@@ -12,4 +12,6 @@
+export function verifySessionToken(token: string): boolean {
+  return token.startsWith("sess_");
+}

### Usage Examples:
```bash
# Pack all uncommitted working tree changes + dependencies + unified diff:
scp --diff -c

# Pack staged changes only:
scp --staged -c

# Combine specific entry files with git diff:
scp src/index.ts --diff -c

🗄️ Smart Prisma Schema Model Extractor (v1.2.0)

In enterprise TypeScript projects using Prisma, prisma/schema.prisma can easily exceed 2,000 lines of database models. Dumping the entire schema wastes thousands of tokens on irrelevant tables.

smart-context-packer introduces Zero-Hallucination Prisma Extraction:

1. It automatically inspects every packed file for imports of @prisma/client or references like prisma.user.findMany or db.order.create.

2. It locates prisma/schema.prisma (or ./schema.prisma) in the workspace.

3. It parses all model <Name> { ... } and enum <Name> { ... } blocks.

4. It extracts ONLY the referenced models/enums, plus their direct 1-level relational models (e.g., if User references Post and Profile, those models are also included).

5. It injects a clean virtual file block into the prompt:

// prisma/schema.prisma [Extracted Models]
model User {
  id        String   @id @default(cuid())
  email     String   @unique
  role      Role     @default(USER)
  posts     Post[]
}

model Post {
  id        String   @id @default(cuid())
  title     String
  authorId  String
  author    User     @relation(fields: [authorId], references: [id])
}

enum Role {
  USER
  ADMIN
}

🔌 Model Context Protocol (MCP) Server (v2.3.0)

smart-context-packer includes a built-in, zero-dependency JSON-RPC 2.0 Model Context Protocol (MCP) server running over stdio with 15 native tools organized across 4 progressive disclosure layers. AI IDEs and autonomous coding agents can invoke scp as a native tool without any external wrappers.

Launch manually:

scp --mcp

AI Client Configuration

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "smart-context-packer": {
      "command": "npx",
      "args": ["-y", "smart-context-packer", "--mcp"]
    }
  }
}

Cursor (.cursor/mcp.json) / Antigravity (mcp_config.json) / Windsurf / Cline / OpenCode

{
  "mcpServers": {
    "smart-context-packer": {
      "command": "npx",
      "args": ["-y", "smart-context-packer", "--mcp"]
    }
  }
}

🛠️ Exposed MCP Tools Suite (15 Native Tools)

💻 VS Code & AI IDE Tasks Generator (v1.2.0)

Integrate scp directly into your daily IDE workflow with zero manual JSON writing:

scp --init-vscode

This creates or safely merges into .vscode/tasks.json with three ready-to-run tasks. Open the Command Palette (Ctrl+Shift+P on Windows/Linux, Cmd+Shift+P on macOS) and run Tasks: Run Task:

1. SCP: Pack Active File + Dependencies (Copy to Clipboard) Runs npx scp ${relativeFile} --copy on whichever file tab is currently active.

2. SCP: Pack Active File (Skeleton Mode -> Clipboard) Runs npx scp ${relativeFile} --skeleton --copy for ultra-compact signature-only packing.

3. SCP: Pack Git Diff + Dependencies (Copy to Clipboard) Runs npx scp --diff --copy to bundle all current unstaged/uncommitted changes and copy to clipboard.

📈 Token Economy Benchmarks

🛠️ CLI Usage & Flags

scp [options] [targets...]

Note: targets are optional when using --diff, --staged, --mcp, or --init-vscode.

Options Reference

Practical Examples

# 1. Daily Driver: Pack auth handler, copy to clipboard, and paste into ChatGPT
scp src/controllers/auth.ts -c

# 2. Maximum Token Efficiency: Depth 3 with Skeleton signatures
scp src/main.ts -d 3 -s -c

# 3. Review uncommitted git changes + dependencies before creating a PR
scp --diff -c

# 4. XML Mode for specialized LLMs / Claude artifacts
scp src/index.ts -f xml -o prompt.xml

# 5. Reverse Dependency Analysis: What files will be impacted if I edit utils.ts?
scp src/utils/formatters.ts --reverse -c

# 6. Pipe directly into another tool or CLI assistant
scp src/server.ts --stdout | claude

🎮 FiveM & Game Scripting Support

smart-context-packer includes first-class support for Grand Theft Auto V / FiveM game server developers:

# Point directly to a resource's fxmanifest.lua:
scp resources/[gameplay]/banking/fxmanifest.lua -c

scp automatically:

1. Parses shared_scripts, client_scripts, and server_scripts arrays.

2. Expands wildcards (e.g. 'client/**/*.lua', 'config.lua').

3. Resolves internal Lua require('utils.math') dot-notation paths.

4. Masks sensitive database credentials in server configuration scripts.

💻 Programmatic Library API

smart-context-packer is also an enterprise TypeScript library. Integrate it into VS Code extensions, MCP servers, or automated CI bots:

import { packContext, analyzeDependencies, formatContext } from 'smart-context-packer';

// 1. One-shot high-level packing (with git diff support)
const result = await packContext({
  targets: ['src/index.ts'],
  depth: 2,
  skeleton: true,
  diff: true,
  copy: true,
  output: '.context-pack.md',
});

console.log(`Packed ${result.graph.nodes.size} files.`);
console.log(`Estimated Tokens: ${result.stats.totalTokens}`);

// 2. Low-level dependency analysis
const graph = await analyzeDependencies(['src/services/payment.ts'], {
  cwd: process.cwd(),
  maxDepth: 3,
  reverse: true,
});

for (const [filePath, node] of graph.nodes) {
  console.log(`${filePath} (depth: ${node.depth}) imports:`, node.imports);
}

🤝 OpenAI Open Source Grant Alignment

smart-context-packer was engineered from the ground up to advance the mission of open-source AI tooling:

1. Inference Compute Reduction: By filtering out irrelevant files and skeletonizing non-critical dependency bodies, scp cuts prompt tokens by up to 97%. This drastically reduces global GPU compute and server energy requirements.

2. Context Fidelity & Hallucination Suppression: AI assistants hallucinate when context boundaries are missing. scp guarantees that every imported interface, type definition, and helper signature is present and verified.

3. Developer Privacy & Safety: Native, zero-telemetry secret redaction ensures that credentials, access tokens, and sensitive private keys never cross network boundaries.

🗺️ Roadmap

• TypeScript / JavaScript / TSX / JSX dependency resolver

• Vue 3 Single File Component script parser

• tsconfig.json path alias resolver (@/*, ~/*)

• FiveM fxmanifest.lua and Lua require() resolver

• Fast BPE token counter & context window budget calculations

• Automatic credential & secret redaction engine

• Skeleton signature extraction mode (--skeleton)

• Dual ESM/CJS library distribution with strict TypeScript types

• Git working tree diff and staged context resolver (--diff, --staged)

• Smart Prisma schema model & relation extractor (prisma/schema.prisma)

• Official Model Context Protocol (MCP) server integration (--mcp)

• VS Code Command Palette tasks generator (--init-vscode)

• Auto Token-Budget Optimizer (--max-tokens) with smart depth-descending skeletonization

• Background Agent Rule Generator (--init-agent for Cursor & Antigravity IDE)

• Autonomous pack_git_diff MCP tool for working tree and staged diff inspection

• Incremental SHA-256 AST local disk cache (src/cache.ts)

• Blast-radius reverse caller & test impact risk scoring (src/blast-radius.ts)

• File-linked persistent project memory (src/memory.ts)

• 3-Layer progressive disclosure MCP tool suite (search_codebase_index, inspect_dependency_graph, pack_context, save_project_memory, query_project_memory)

• Python AST dependency analyzer (import, from ... import)

• Go module and package resolver (import, go.mod)

• Rust module and crate resolver (mod, use crate::*)

• PageRank architectural repo-map generator (--repo-map)

• In-memory BM25 semantic intent routing (-i, --query)

• Offline zero-dependency HTML canvas visualizer (--visualize)

• Universal Multi-Assistant Presets (--init-agent for 12 assistants)

• Crash-Proof Active Task & Planning Context Engine (-t, --task, .scp/tasks.json)

• External Frameworks & Dependencies Manifest Grounding across 12 formats

• Visual Context Budget HUD with ASCII gauges & category breakdown (src/hud.ts)

• Tool Output Sandboxing & Compression (--sandbox <cmd>, 80-95% token savings)

• Smart Middle-Out Slicing for massive files (>500 lines)

• 16-Language Ultra-Polyglot AST Support (C#, Java, Kotlin, C++, PHP, Dart, Swift, Ruby, Svelte, TS, Go, Rust, Python, Vue, Lua, Prisma)

• Complete 15-Tool Model Context Protocol (MCP) Suite with Surgical Layer 4

• Symbol-Level AST Tree-Shaking (--tree-shake) for Dead-Code Slicing of dependencies

• Automatic Monorepo Workspace Package Resolution (package.json workspaces, pnpm-workspace.yaml, packages/*, apps/*)

• Git Commit Range & Pull Request Context Packing (--commit, --pr)

• Live File System Watch Mode (-w, --watch)

• Interactive VS Code extension with one-click "Pack Context" context menu

📄 License

Distributed under the MIT License. See LICENSE for details.