contextl 1.2.48 → 1.2.49

package/README.md

@@ -1,5 +1,7 @@
 # contextl
 
+> **v1.2.49 is our most stable, thoroughly benchmarked release yet.**
+
 **Architecture intelligence for AI coding agents.**
 
 Stop letting your AI agent read your entire codebase to make one small change. `contextl` finds the exact files that matter — using graph theory, not guesswork.
@@ -12,23 +14,24 @@ lib/api.ts                   [high confidence]
 types/index.ts                [medium confidence]
 ```
 
-No LLM. No embeddings. No API keys. No vector database. Pure dependency graph + text scoring — runs entirely on your machine, your code never leaves your laptop.
+No LLM. No embeddings. No API keys. No vector database. Pure dependency graph + text scoring — runs entirely on your machine, your code never leaves your system.
 
 ---
 
 ## Install (60 seconds)
 
-**Requires Python 3.9+** on your PATH. Everything else (`networkx`, `mcp`) installs automatically on first run.
+**Requires Python 3.9+** on your PATH. All required Python dependencies — graph processing and tree-sitter parsers for 7 languages — install automatically on first run.
 
-### Option 1: The AI Prompt Method (Recommended)
-Since you are using an AI IDE, you don't even need to edit the configuration yourself. Just open Cursor's Composer or Claude Code's chat and paste this prompt:
+```bash
+npm install -g contextl && contextl install
+```
 
-> *"Hey, add the `contextl` MCP server to your configuration file. The command is `npx` and the args are `["-y", "contextl"]`."*
+This will globally install the `contextl` CLI and automatically inject the correct configuration into your AI IDE (Cursor, Windsurf, Claude Code, etc.). 
 
-The AI will find its own config file, inject the JSON, and reboot automatically.
+Restart your IDE and the contextl tools will be instantly available to your agent!
 
-### Option 2: The Manual Method
-If you prefer to configure it manually, add this to your IDE's MCP config file:
+### Manual Configuration (Fallback)
+If the auto-installer doesn't detect your IDE, or if you prefer to configure it manually, add this to your IDE's MCP config file:
 
 ```json
 {
@@ -45,11 +48,13 @@ If you prefer to configure it manually, add this to your IDE's MCP config file:
 
 | IDE | Config path |
 |-----|-------------|
-| Gemini CLI | `~/.gemini/config/mcp_config.json` |
+| Antigravity | `~/.gemini/config/mcp_config.json` |
+| Claude Desktop | `~/.config/Claude/claude_desktop_config.json` (varies by OS) |
+| Cline / Roo | `~/Documents/Cline/cline_mcp_settings.json` (varies by OS) |
 | Cursor | `~/.cursor/mcp.json` |
-| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
 | Claude Code | `~/.claude.json` |
-| VS Code | `.vscode/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| VS Code (Workspace) | `.vscode/mcp.json` |
 
 Restart your IDE. Done — no cloning, no Python setup beyond having it installed.
 
@@ -90,6 +95,8 @@ Walks the dependency graph upstream from any file to find every direct and trans
 Lists every source file `contextl` can see — useful for the agent to orient itself before doing anything else.
 
 ### `find_dead_files`
+*"Which files are never imported by anything?"*
+
 Find files in the repository that are never imported by any other file (in-degree of 0 in the dependency graph). 
 
 *Note: The engine automatically detects and excludes standard entry points (e.g. `src/index.ts`, `main.py`, `app.tsx`) and test files from these results, as they are intentionally not imported by other files.*
@@ -138,16 +145,43 @@ Extracts the structural skeleton (API surface) of a source file using Tree-sitte
 }
 ```
 
+---
+
+## Benchmarks & Token Reduction
+
+Instead of dumping an entire repository into your agent's context window, `contextl` surgically extracts only the relevant dependencies. Across 9 real-world open source repositories, this results in massive token savings while maintaining high relationship accuracy:
+
+- **JavaScript (Express)**: 93.58% context reduction
+- **C++ (JSON)**: 84.31% context reduction
+- **Python (Flask)**: 52.69% context reduction
+
+See the full live telemetry and methodology breakdown at our [official documentation and metrics dashboard](https://contextl-web.vercel.app).
+
 
 
 
 
 ## How the ranking works
 
-1. **Keyword match** — does the filename contain query terms?
-2. **Content match** — does the file's source code mention the terms?
-3. **Graph proximity** — files connected to high-scoring files get a relevance boost
-4. **Centrality (PageRank)** — heavily-connected files rank higher when scores tie
+`contextl` relies strictly on deterministic mathematical scoring based on Okapi BM25 and graph theory. There are no LLMs or embeddings involved.
+
+1. **Keyword Match (Path / Filename)**
+   - Exact filename matches receive a massive `4.0x` IDF multiplier.
+   - Exact path matches receive a `2.0x` IDF multiplier.
+   - Substring and canonical abbreviation matches (e.g., `db` matching `database.py`) also receive significant boosts.
+2. **Content Match (BM25 TF-IDF & Structural Analysis)**
+   - Calculates Okapi BM25 Term Frequency (`k1=1.5`, `b=0.75`), using Document Length Normalization to aggressively penalize huge files (e.g., 5,000-line god classes) and normalize token counts.
+   - **TypeScript Exports**: Matches on `export const / class / function` receive a permanent `8.0x` multiplier.
+   - **Classes / Interfaces**: Matches on OOP class definitions receive up to a `10.0x` structural multiplier for short vibe queries.
+   - **Functions / Annotations**: Matches on method signatures and annotations receive a `4.0x` or `5.0x` boost.
+3. **Graph Proximity Bonus**
+   - Files directly adjacent in the dependency graph to high-scoring files receive a `0.2x` recursive relevance boost, pulling tightly coupled dependencies up the ranking.
+4. **Centrality Tiebreaker**
+   - The engine calculates PageRank across the entire repository graph. When files have identical or highly similar relevance scores, highly-central files heavily depended on by the rest of the codebase (like core `utils.py` or base classes) rank slightly higher.
+
+*(Note: Test files are automatically penalized by 50% unless the natural language query explicitly contains words like "test" or "spec".)*
+
+No machine learning involved — every score is fully explainable and traceable back to a specific signal.
 
 ---
 
@@ -174,7 +208,7 @@ contextl search ./my-repo "fix the auth flow"
 contextl impact ./my-repo src/api.ts
 
 # 3. Find dead unused files
-contextl dead-code ./my-repo
+contextl standalone ./my-repo
 
 # 4. Generate an Obsidian vault
 contextl obsidian ./my-repo ./my_vault
@@ -189,7 +223,9 @@ contextl review ./my-repo
 
 ## Why this exists
 
-AI coding agents are increasingly good at writing code. They're still bad at knowing *where* to look. On a 5,000-file repo, an agent might read 100+ files just to change a logo. `contextl` exists to fix that — and to eventually give agents a real model of your codebase's architecture, not just a file list.
+AI coding agents are increasingly good at writing code. They're still bad at knowing *where* to look. On a massive monorepo, an agent might blindly read 100+ files just to change a logo. `contextl` exists to fix that by giving agents a deterministic, graph-based map of your architecture.
+
+And it scales. We rigorously benchmark against massive open source repositories to ensure it can handle your monorepo. On `typeorm` (3,572 TypeScript files), the engine scans, parses, graphs, and searches the entire architecture in under 3 seconds. On Apache `superset` (5,897 mixed language files), the full end-to-end pipeline executes in ~44 seconds. No vector DBs, no cloud latency, just pure on-device intelligence.
 
 ---
 
@@ -205,6 +241,7 @@ Same engine, same tools — installable via PyPI for Python-first workflows.
 
 ## Links
 
+- [Official Documentation & Benchmarks](https://contextl-web.vercel.app)
 - [Creator GitHub](https://github.com/DS0710-coder)
 - [PyPI package](https://pypi.org/project/contextl-mcp)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contextl",
-  "version": "1.2.48",
+  "version": "1.2.49",
   "description": "contextl — finds the most relevant files in your codebase for any change request. MCP server for AI coding agents.",
   "keywords": [
     "mcp",
@@ -28,6 +28,7 @@
   "bin": {
     "contextl": "bin/contextl.js"
   },
+  "preferGlobal": true,
   "files": [
     "bin/",
     "python/",