EGRD v1.3.0

Entropy-Guided Reference Distillation

Stop Dumping 50,000 Tokens Into Your AI Agent.

ctx scans your codebase, extracts an AST Knowledge Graph, and calculates Shannon Entropy $H(P)$ to yield a surgical ~40-token Senior Engineer Context Plan—or pauses at the Clarification Gate when your prompt is ambiguous. Runs on 1–2 CPU cores with zero GPU overhead.

InstallationmacOS, Linux & Windows

$npx context-gen-cli@latest -d

98.5%

Token Reduction

1–2 Cores

Strict CPU Bound

0 CUDA

Zero GPU Downloads

bash — context-gen-cli

INTERACTIVE DEMO

Shannon Entropy $H(P)$ Distillation in Action

Test how the engine detects ambiguous prompts and prevents hallucinatory multi-file writes.

Interactive Engine

1 Core • CPU Only

Shannon Entropy $H(P)$ Distillation Simulator

Watch $H(P)$ evaluate uncertainty and route to either the Clarification Gate or the Senior Context Blueprint.

Input Query to ctx distillMode: Feature Implementation

"update mcp tools and scanner graph"Low Entropy

Shannon Entropy Metric $H(P) = -\sum p_i \log_2(p_i)$

H(P) = 0.21 bits

Deterministic (< 0.50 bits)

Initial H₀

2.86 bits

0.0 bits (Certainty)1.50 bits (Gate Threshold)3.50 bits (Noise)

Distillation Pipeline

1. Neural & AST Signature MatchingH = 1.84

Matched src/mcp/tools.js, src/scanner.js, and src/graph.js with 94.2% confidence.

2. Knowledge Graph Activation FlowH = 0.89

Propagated dependencies across 18 AST edges; identified downstream callers.

3. Shannon Information OptimizationH = 0.42

Ranked by ΔH / token density. Extracted exported AST signatures only.

4. Senior Context Blueprint GeneratedH = 0.21

H(P) dropped to 0.21 bits. Zero ambiguity. Exact 41-token blueprint produced.

Context Payload

-99% Reduction

Raw Context2,800tokens

EGRD Distilled41tokens

Senior Engineer Blueprint

Surgical Context Blueprint (41 tokens | CPU 1 core):

Zero hallucinations. AI receives only exact signatures and AST dependencies.

### Senior Engineer Context Plan (41 tokens)
- Task: update mcp tools and scanner graph
- Engineering Mode: Feature Implementation

- Primary Files to Reference:
  • src/mcp/tools.js [js/mcp]
    exports: [registerTools, handleCall]
  • src/graph.js [js/core]
    exports: [buildDependencyGraph]

- Blast Radius (Dependents):
  • src/index.js (imports tools)

- Architecture Guardrail:
  Keep tool schema backwards compatible.

PIPELINE & SETUP

3-Step Workflow: From Repo to Live MCP

Run the CLI in your repository root, distill your prompts, and connect any AI agent.

Scan & Graph AST

Run ctx -d in any repo. The AST scanner parses file dependencies and generates artifacts in context/.

$ ctx -d

Auto-Sync

Distill With EGRD

Run ctx distill "prompt". The entropy governor runs on 1 CPU core, evaluating $H(P)$ to guard against hallucinated multi-file overwrites.

$ ctx distill <prompt>

1-2 Cores

Connect Any MCP Agent

Add our MCP config to Cursor, Antigravity, Claude Code, or VS Code. Your models get live codebase awareness with built-in public tunneling.

$ ctx serve

MCP Ready

Model Context Protocol (MCP) Configuration

Select your client to copy the exact configuration:

Target File: .cursor/mcp.jsonJSON

{
  "mcpServers": {
    "context-code": {
      "command": "ctx",
      "args": ["serve"]
    }
  }
}

Developer Cookbooks

Common Workflows with `ctx`

Commands to eliminate context rot, prevent hallucinated imports, and keep CPU usage capped at 1–2 cores.

Daily Workflow

1. Zero-Config Workspace Boot (ctx -d)

Run once when you open any repo. Scans files, maps dependencies, starts the MCP server on port 3456, and auto-syncs on save.

$ npx context-gen-cli@latest -d

⚡ context-gen-cli — Default All-In-One Mode (-d)
✓ Context files generated in context/ (agent.md, agent.json, agent.yaml)
✓ MCP Server live on http://localhost:3456/mcp
👀 Watch Mode: Running in background (auto-syncing changes)

Anti-Hallucination Gate

2. Catching Vague Prompts Before AI Guesses

When you type a short, ambiguous prompt, Shannon Entropy stays ≥ 1.5 bits—forcing the AI to ask concrete questions using your actual files.

$ ctx distill "add auth"

╔═══════════════════════════════════════════════════════════════╗
║ ⚠️  CLARIFICATION NEEDED — Ambiguous Prompt Detected          ║
╚═══════════════════════════════════════════════════════════════╝
▸ 1. Implementation Pattern: Should I extend an existing module?
     (e.g., "Follow src/mcp/auth.js" or "Create a standalone module")
▸ 2. Side Effects & Persistence: Persist to disk/DB or stay stateless?

98.5% Token Savings

3. Senior Engineer Blueprint for Targeted Edits

Give a clear intent and EGRD distills only the exact exports, imports, and downstream Blast Radius callers in ~40 tokens.

$ ctx distill "update mcp tools and scanner graph in src"

╔═══════════════════════════════════════════════════════════════╗
║ 🧠 SENIOR ENGINEER CONTEXT PLAN (41 tokens | CPU: 1 core)     ║
╚═══════════════════════════════════════════════════════════════╝
🎯 Task: update mcp tools and scanner graph in src
📂 Primary Files to Reference:
   ✔ src/graph.js [js/lib] — exports: [buildDependencyGraph]
   ✔ src/scanner.js [js/lib] — exports: [scanProject]
💥 Blast Radius: src/mcp/server.js, src/mcp/tools.js
🛡️ Architecture Guardrail: Mirror existing patterns; keep modular.

Polyglot & Monorepos

4. Multi-Language & Monorepo Filtering

Works natively across TypeScript, Python, Rust, Go, Dart/Flutter, and C#—automatically detecting apps/ and packages/ workspaces.

$ ctx distill "add billing webhook handler" -p ./services/api -b 200

🎯 Task: add billing webhook handler (services/api)
📂 Primary Files to Reference:
   ✔ services/api/routes/webhooks.py [python/api] — exports: [stripe_webhook]
   ✔ services/api/models/subscription.py [python/model] — exports: [Subscription]
💥 Blast Radius: services/api/main.py

ARCHITECTURE & CAPABILITIES

System Design & Technical Pillars

Every layer of ctx delivers maximum semantic context with minimal token overhead and zero cloud dependencies.

Core Engine

Shannon Information Theory

Entropy-Guided Reference Distillation (EGRD)

Unlike naive RAG systems that retrieve hundreds of raw code lines, EGRD calculates Shannon Entropy H(P) = -∑ p log₂(p). It measures the ambiguity of your request against your codebase signatures and extracts only surgical AST symbol references.

Distillation Ratio MetricΔH / tokens = (p · H₀ · 1.6) / tokensEstimate

Vague Prompt GateH(P) ≥ 1.50 bits ➔ Halts & Clarifies

Distilled BlueprintH(P) < 0.50 bits ➔ 41 Tokens

Lightweight Execution

Strict CPU Cap

Hardware-Aware Resource Governor

Runs strictly on 1–2 CPU cores using lightweight quantized ONNX embeddings or probabilistic fallback. Zero CUDA, zero Torch, zero 2GB model downloads.

CPU Ceiling Governor

Threads Allocated:1–2 cores max

CUDA / GPU Requirement:0.0 MB (None)

Embedding Model:all-MiniLM-L6-v2 (q8)

Graph Traversal

AST Resolution

Dependency & Blast Radius Analysis

Deep static analysis traces import/export relationships, entrypoints, and downstream callers across TypeScript, JavaScript, Python, Go, and Rust projects.

AST Dependency Resolution

Entrypoints detected:src/index.js, src/distill.js

Graph traversal depth:3 levels (configurable)

Blast radius warning:Active

Remote Connectivity

Live MCP Bridge

Multi-Tunnel Remote MCP Server

Share your local project context with cloud-based AI agents via free native SSH tunnels (localhost.run, serveo.net) or token-based providers (ngrok, cloudflared).

Public & Local Endpoints

$ ctx -m --public ➔ https://*.localhost.run

API Key Auth:Enforced

Security & Privacy

Zero Secrets Leaked

Intelligent Security & Redaction

Automatically respects .gitignore, .dockerignore, and .npmignore while redacting API keys, SSH credentials, certificates, and environment secret patterns.

Automated Redaction Guard

.env & secrets:[REDACTED]

Target storage:Local context/ directory

Third-party telemetry:Zero (Air-gapped)

TOKEN ECONOMICS

Raw File Dumps vs. EGRD Distillation

Flooding 1M-token context windows with unrelated boilerplate dilutes attention weights, degrades reasoning accuracy, and increases inference latency.

Raw Dump Anti-Pattern

Raw Context Dump

~50,000 to 120,000 Tokens

Concatenates dozens of whole source files into the prompt, including unrelated imports, formatting comments, and unused helper routines.

Context Window Rot: Attention dilution leads to hallucinated interfaces.

High Latency: 6 to 12s time-to-first-token while LLM processes prompt payload.

High API Costs: Up to $0.25 to $0.60 per query on frontier models.

Silent Regressions: Modifies unintended files due to vague semantic boundaries.

Token Load50,000+

Query Cost~$0.20/call

Senior Engineer Blueprint

EGRD Surgical Blueprint

~41 to 120 Tokens

Calculates Shannon Entropy across AST edges, identifies blast radius callers, and feeds the AI only exact type signatures and architecture guardrails.

Zero Hallucinations: The LLM focuses 100% of attention on target interfaces.

Sub-Second Latency: Near-instant generation with TTFT under 250 milliseconds.

Near-Zero Cost: <$0.0001 per query, enabling background agent loops.

Clarification Gate: Automatically pauses vague requests ("add auth") before code breaks.

Token Load41 tokens

Query Cost< $0.0001

FREQUENTLY ASKED QUESTIONS

Frequently Asked Questions

Details on entropy calculation, hardware bounds, and protocol integration.

While modern frontier models (Claude 3.7 Sonnet, Gemini 2.5 Flash, GPT-4o) have enormous theoretical context windows, empirical research shows that 'needle-in-a-haystack' retrieval degrades reasoning quality. Irrelevant boilerplate dilutes attention weights, increases time-to-first-token latency by 5x–10x, and causes the model to guess or rewrite the wrong files. EGRD extracts only the exact AST signatures and blast radius callers needed.

DOCUMENTATION HUB

Complete Reference, CLI Flags & Architecture

Read the full technical breakdown, mathematical formulas, and MCP JSON configurations for Cursor, Claude, Antigravity, and VS Code.