context-gen-cli Documentation

A lightweight, hardware-governed tool that maps codebase ASTs, distills context using Shannon Information Theory, and exposes a live Model Context Protocol (MCP) server.

#Overview & Motivation

Frontier LLMs (Claude 3.7 Sonnet, Gemini 2.5 Flash, GPT-4o) support massive context windows, yet dumping entire codebases into prompts leads to Context Rot:

The Raw Dump Problem

Dumping 50,000+ tokens wastes attention budget, spikes latency by 5x–10x, costs ~$0.20 per call, and frequently causes models to modify wrong files.

The EGRD Solution

Entropy-Guided Reference Distillation extracts only exported AST signatures and downstream blast-radius dependents in ~40 tokens (98.5% reduction).

#Installation

Install globally or run ad-hoc with your preferred package manager:

Node.js (npm / npx)Zero Install Option

npx context-gen-cli@latest -d

Python (pip)PyPI Package

pip install context-gen-cli && ctx -d

Homebrew (macOS / Linux)Formula Tap

brew tap yakkshit/context-gen https://github.com/yakkshit/context-gen.git && brew install context-gen-cli

#Core CLI Commands

ctx -d

Default All-In-One

Scans all code files, builds the dependency graph, writes artifacts (`context/agent.md`, `agent.json`, `agent.yaml`), launches the local MCP server, and starts background auto-sync file watching.

ctx distill <prompt> [-p <path>] [-b <budget>]

EGRD Engine

Performs Entropy-Guided Reference Distillation on your prompt. Calculates $H(P)$ to either ask clarifying questions or output a surgical Senior Engineer Context Plan.

ctx serve [--public]

Remote MCP

Boots the Model Context Protocol server. With --public, provisions an encrypted tunnel (via native SSH or ngrok) with token-based API key authentication for remote cloud models.

ctx update [-f md|json|yaml|all]

Manual Refresh

Forces an immediate re-scan of the codebase and refreshes context files without starting the server.

#How EGRD Works

Entropy-Guided Reference Distillation (EGRD) applies information theory principles to code context selection:

1. Shannon Entropy Formulation

H(P) = -∑ pᵢ · log₂(pᵢ)

The probability distribution P represents semantic similarity scores between your prompt and all codebase signatures (symbols, imports, exports, roles).

2. The Clarification Gate (H ≥ 1.50 bits)

When a prompt is ambiguous (e.g., "add auth"), the probability distribution is spread out across many files. Instead of guessing, the engine pauses and asks targeted questions using actual file paths from your repo.

3. Knowledge Graph Blast Radius Propagation

AST dependencies are traversed to identify which other files import the candidate module. The Senior Blueprint lists these under "Blast Radius" so the developer or agent knows what downstream code might break.

#IDE & MCP Integration

Add the MCP config to your editor. The agent will call distill_context before generating or modifying code.

Antigravity / Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "context-gen": {
      "url": "http://localhost:3456/mcp"
    }
  }
}

#Benefits & Benchmarks

Metric	Raw Context Dumps	ctx with EGRD
Token Payload	50,000 – 120,000	41 – 150 (-98.5%)
Cost per Query	~$0.20 – $0.60	< $0.0001
Time to First Token	6.0s – 12.0s	< 0.25s
Hardware Requirement	Often requires GPU RAG	1–2 CPU cores
Ambiguity Protection	None (Hallucinates)	Clarification Gate

Back to Homepage Explore Cedzlabs Labs & More Tools