redcon
Redcon is an MCP server that gives AI coding agents a deterministic, budget-aware toolkit for selecting, compressing, and retrieving repository context — so agents pull only the files and facts they need instead of dumping whole repos into context.
Core Tools:
redcon_rank— Rank files by task relevance via keyword + import-graph signals, with scores and reasons. The recommended first call for any new task.redcon_overview— Lightweight, task-filtered repo map grouped by directory for quick orientation at minimal token cost.redcon_compress— Task-scoped compressed view of a single file (signatures, imports, relevant sections) at 3–10x fewer tokens.redcon_search— Regex search scoped to task-relevant files (scope='ranked') or the whole repo (scope='all'), pre-filtered by relevance.redcon_structural_search— AST-based search via ast-grep that matches real code structure (e.g.,class $NAME { $$$ }) while skipping comments/strings.redcon_repo_map— Task-ranked files with class/function signatures and line numbers, fitted under a token budget.redcon_budget— Plan how to fit files into a token budget with per-file strategies, showing which files must be dropped.redcon_run— Run a shell command and return schema-aware compressed output (tests, git, builds, coverage, kubectl, etc.) with hard token caps. (Disabled by default; enable withREDCON_MCP_ENABLE_RUN=1.)redcon_quality_check— Run a command, compress its output, and verify the compression against the M8 quality harness before consuming it.
Provides MCP tools for deterministic context budgeting, including ranking, compressing, and packing repository context, to optimize token usage in Windsurf (by Codeium).
Redcon
Deterministic context budgeting for AI coding agents
Stop sending agents 200k tokens of irrelevant code. Redcon scores, compresses, and packs repo context so your agent gets what it actually needs.
Install - Quick Start - How It Works - Docs
The Problem
AI coding agents burn tokens on irrelevant context. You either:
Dump the whole repo and pay for 200k input tokens per request, or
Let the agent grep blindly and waste tool calls figuring out where to look
Redcon solves both. It ranks files by task relevance, compresses them with language-aware strategies (full, snippet, symbol extraction, summary), and packs the result under your token budget. Deterministic, local-first, no embeddings. One MCP server covers Claude Code, Cursor, Windsurf, Cline and Zed; a plain CLI covers CI. Measured on this repository it cuts input tokens by more than 83% at the same task coverage (methodology).
Related MCP server: mcp-sophon
Punch above your plan
On a flat subscription - Claude Pro/Max, Cursor, GitHub Copilot - the token bill isn't what stings, the usage limit is. Redcon cuts the tokens each task needs, so the same plan covers far more work before you hit the weekly wall. Same subscription, more runway.
It stretches the budget you already pay for, and reports exactly how much it saved.
Install
Option 1: VS Code Extension (easiest)
Install Redcon - Context Budget from the marketplace
Open the Redcon sidebar, click Install & Set Up
Reload window. Done.
The extension installs the CLI via pip, registers the MCP server for Claude Code, Cursor, and Windsurf, and gives you a sidebar with budget analytics, file rankings, and compression dashboards.
Option 2: CLI + MCP Server
pip install "redcon[mcp]"
redcon init # creates redcon.toml + registers MCPThe init command auto-configures MCP for Claude Code, Cursor and Windsurf, plus VS Code, Codex CLI, Gemini CLI, Junie CLI, Cline and Zed when they are detected, so your AI agent can call redcon_rank, redcon_search, redcon_compress, and redcon_budget as native tools. It also writes a short AGENTS.md section that tells agents to prefer these tools for context selection.
Option 3: CLI only
pip install redcon
redcon init --no-mcpQuick Start
# Rank files relevant to a task
redcon plan "add rate limiting to auth API" --repo .
# Pack context under a token budget
redcon pack "refactor payment flow" --repo . --max-tokens 30000
# Compare compression strategies
redcon benchmark "add caching" --repo .
# Audit a PR for context growth
redcon pr-audit --repo . --base origin/main --head HEADOutput goes to run.json (machine-readable) and run.md (human-readable). Use them in CI, or feed the compressed context directly into your agent.
For a full end-to-end walkthrough on a realistic service repo (plan, pack, validate, with deterministic output), see examples/service-repo.
How It Works
task: "add rate limiting to auth"
|
v
[1] scan - incremental scan of repo files (cached)
|
v
[2] rank - score each file: keyword match, imports, file role, git history
|
v
[3] compress - per-file strategy: full / snippet / symbol extraction / summary
|
v
[4] pack - fit top-N compressed files under token budget, drop the rest
|
v
run.json + run.md + compressed_context ready for your agentEvery step is deterministic. Same input, same output. No embeddings, no random chunking.
Benchmark: context-eval
Selection quality is measured, not claimed. context-eval/
is an open benchmark for context-selection tools: tasks come from real git
commits, ground truth is the files each commit actually modified, and every
tool packs the same token budget. Current results (33 tasks, 24k budget):
Tool | Mean coverage | Tokens / coverage point |
| 43.8% | 306.8 |
| 29.8% | 538.9 |
| 15.3% | 533.3 |
| 11.4% | 720.0 |
Rerun it on any repo: python context-eval/run.py --repo /path/to/repo.
Methodology, limitations, and how to add your own tool:
context-eval/README.md.
MCP Integration (Pull Model)
mcp-name: io.github.natiixnt/redcon
Instead of pushing a 30k-token blob to your agent, Redcon exposes 9 MCP tools the agent calls on demand:
Tool | What it does |
| Top-K files with scores and reasons - call this first |
| Lightweight repo map grouped by directory |
| Top ranked files plus their code signatures, fitted under a token budget |
| Compressed single-file view for cheap inspection |
| Regex search scoped to ranked files or full repo |
| ast-grep structural search - patterns match the AST, not text |
| Plan fitting files within a token budget |
| Run a shell command, return its output compressed |
| Run a command and verify the compressed output against the quality harness |
Typical agent flow uses ~5k tokens for exploration instead of 30k for a blob. The agent itself decides what to read in full.
Config gets written automatically to:
.mcp.json(Claude Code).cursor/mcp.json(Cursor)~/.codeium/windsurf/mcp_config.json(Windsurf)
Command Output Compression
Source files are only half the bloat. The other half is command output: git diff, pytest, cargo test, grep, ls -R. Redcon's redcon_run MCP tool (and redcon run CLI) wraps the call, parses the output, and returns a budget-aware compressed view that preserves every fact the agent actually needs.
Headline reductions on representative inputs:
Compressor | Fixture | Raw tokens | Compact | Ultra |
| 12 files, 240 hunks | 8,078 | 97.0% | 99.5% |
| 30 failures + 200 passes | 2,555 | 73.8% | 99.2% |
| 600 matches across 50 files | 7,015 | 76.9% | 99.9% |
| 500 paths | 3,398 | 81.3% | 99.8% |
| 30 dirs x 15 files | 1,543 | 33.5% | 99.0% |
| 200-row CrashLoopBackOff | ~5,000 | 91.5% | 99.5% |
| 200 stacks | 2,385 | 90.0% | 99.0% |
| 200 NDJSON records | 6,038 | 91.1% | 98.0% |
| 50-file grid | 738 | 73.2% | 95.0% |
| 11-node Postgres plan | 435 | 71.3% | 93.3% |
Quality is enforced separately. Every compressor declares must_preserve_patterns (file paths in a diff, failing test names in pytest, branch name in git status, slowest node operator in EXPLAIN); the M8 quality harness rejects any compressor whose compact output drops a fact present in the raw input. Run it as a CI step:
redcon cmd-quality # exits non-zero if any compressor regressed
redcon cmd-bench # markdown table; --json for CI baselines
redcon run "git diff" --quality-floor compact --max-output-tokens 4000Twenty compressors ship today: git_diff, git_status, git_log, pytest, cargo_test, npm_test (vitest+jest), go_test, grep, ls, tree, find, lint (ruff+mypy), docker, pkg_install (pip+npm+yarn), kubectl_get/kubectl_events, profiler (py-spy+perf), json_log, coverage, sql_explain (Postgres+MySQL TREE), bundle_stats (webpack + esbuild metafiles). Full per-schema benchmarks: docs/benchmarks/cmd/.
Cross-call dimension
Beyond per-call compression, four layers compose across an agent session:
Path aliases (V41): repeated paths like
redcon/cmd/pipeline.pycollapse tof001on later mentions. Lazy first-use, never net-negative.Content reference ledger (V43): paragraph-shaped blocks above 6 cl100k tokens get session-stable
{ref:001}aliases on second-and-later occurrences. Empirically 23% of session output had block-level overlap.Symbol aliases (V49): CamelCase types / multi-word snake_case identifiers (>=8 chars) collapse to
c001aliases the same way paths do. Empirically 72% of distinct symbols recur >=2 times per session.Snapshot delta vs prior call (V47): when the same argv runs twice, ship only the delta. Schema-aware renderers for
pytest(set-diff over failure names),git_diff(file-set with per-file +/- counts), andcoverage(per-file pp moves) win meaningfully over generic line-diff. Always picksmin(cost_delta, cost_abs)so non-regressive by construction.Invariant cert (V93): every COMPACT/VERBOSE output stamps
mp_sha=<16hex>over the sorted multiset of(pattern, capture)extracted from raw. Auditors recompute the cert against the compressed text to detect spurious additions or capture thinning - upgrades the existing must-preserve boolean to set-equality.
Empirical measurement on 5 simulated agent sessions (benchmarks/measure_sessions.py): the cross-call layers add +8.3% session-level saving on top of the per-call compressors, with +15% on heavy-overlap sessions (debugging, search-and-edit) and near-zero on distinct-content sessions. V85 adversarial GA fuzzer ratchets all 20 schemas as a hard CI gate (REDCON_V85_ENFORCE=1).
VS Code Extension
Once installed you get:
Sidebar chat: type a task, send, watch the pack run live
Dashboard: donut/pie/bar charts for budget, strategies, token impact per file
Status bar: current budget usage with risk indicator
CodeLens: compression strategy and token count shown above each file
File decorations: relevance score badges on files in the explorer
History: browse past runs, diff them, export to clipboard
Branding: red->navy gradient with triple chevron mark, glass-style UI.
Workspaces (Multi-Repo)
One task can span multiple repos. Place the workspace TOML in a folder that contains all the repos (a monorepo root or a common parent directory) - repo paths must resolve inside that folder, so a workspace file cannot reach above itself:
name = "backend-services"
[scan]
include_globs = ["**/*.py", "**/*.ts"]
[budget]
max_tokens = 28000
top_files = 24
[[repos]]
label = "auth-service"
path = "auth-service"
[[repos]]
label = "billing-service"
path = "billing-service"
ignore_globs = ["tests/fixtures/**"]Artifacts include workspace, scanned_repos, selected_repos, and repo-qualified paths like auth-service:src/auth.py.
See docs/workspace.md.
Python API
from redcon import RedconEngine
engine = RedconEngine()
# Rank files
plan = engine.plan(task="add user auth", repo=".", top_files=15)
# Pack context
result = engine.pack(
task="add user auth",
repo=".",
max_tokens=30000,
top_files=25,
)
print(f"Used {result['budget']['estimated_input_tokens']} of {result['max_tokens']} tokens")
print(f"Risk: {result['budget']['quality_risk_estimate']}")
for file in result["compressed_context"]:
print(f"{file['path']}: {file['strategy']} ({file['compressed_tokens']} tokens)")Full reference: docs/python-api.md.
Features
Deterministic scoring: keyword match, import graph, file role (test/docs/prod), git history
Language-aware compression: Python, TypeScript, JavaScript, Go, Rust, Java, and more
Command output compression: 20 compressors covering git, test runners, grep/rg, listings, lint, docker, pkg-install, kubectl, profilers, JSON logs, coverage, SQL EXPLAIN, and bundle stats - 70-99% reduction at compact level
Incremental scanning: cached file metadata with git-aware change detection
Multi-repo workspaces: single task, multiple repos, shared config
Budget policies: enforce max tokens, quality risk levels, file counts in CI
Quality harness: must-preserve regex assertions per compressor, deterministic, robust to truncated/binary input
Streaming runner: chunked Popen reader with bounded memory and early SIGTERM/SIGKILL when output cap is hit
Run history: SQLite-backed artifact store for both file packs and command runs, diff/heatmap/drift analysis
Cost analysis: estimate token costs across GPT-4o, Claude, and other models
PR auditing: detect context growth in pull requests
Plugin system: custom scorers, compressors, token estimators, summarizers
Cache backends: in-memory, local file, Redis
Doctor command: diagnose environment, Python version, disk space, git availability
Documentation
Getting Started - first pack in 60 seconds
CLI Reference - all commands and flags
MCP and Hooks - agent integration, tool list, deterministic context injection
Configuration - redcon.toml fields
Workspaces - multi-repo setup
Python API - programmatic usage
Agent Integration - middleware layer
Plugins - custom extensions
Architecture - how it all fits together
Migration Notes - upgrading between versions
License
Everything in this repository is licensed under the Functional Source License, FSL-1.1-MIT: use it freely for any purpose except building a competing commercial product or service. Each release automatically becomes MIT-licensed two years after it ships.
The hosted Redcon Cloud control plane (orgs, quotas, usage metering, billing, team dashboards) is separate commercial software maintained in a private repository.
Commercial licensing: natjiks@gmail.com
Available Tools
9 toolsredcon_budgetA
Plan how to fit a set of files under a token budget, choosing a compression strategy per file. Use before reading several files at once; returns per-file token costs, strategies, and which to drop.
Inputs: task (required), files (required), max_tokens (required), repo.
redcon_compressA
Task-scoped compressed view of one file (signatures, imports and the relevant sections), typically 3-10x fewer tokens. Prefer this over reading a whole file; fetch the full file only if it is insufficient.
Inputs: path (required), task (required), repo, max_tokens.
redcon_overviewA
Lightweight repository map grouped by directory, filtered to the task's modules. Use to orient instead of ls -R or find; costs a few hundred tokens. For signatures, use redcon_repo_map.
Inputs: task (required), repo.
redcon_quality_checkA
Run a shell command, compress its output, and verify the compression against the M8 quality harness. Use instead of redcon_run when you want a structured pass/fail verdict on the compression.
Inputs: command (required), cwd, quality_floor, timeout_seconds, +3 more.
redcon_rankA
Rank repository files by relevance to a task. Call this FIRST on a new task, before grepping or reading: it returns the top-K paths with scores and reasons. Follow up with redcon_compress on the top hits.
Inputs: task (required), repo, top_k.
redcon_repo_mapA
Repo map: top ranked files plus their class and function signatures with line numbers, under a token budget. Use for code structure across many files at once. Degrades to a path-only listing without the redcon[symbols] extra.
Inputs: task (required), repo, budget, top_files.
redcon_runA
Run a shell command and return its output compressed for LLM consumption (pytest, git diff/status/log, builds, coverage and more). Use instead of a raw shell when output may exceed a screenful; token caps are hard and failures keep their essential detail. DISABLED by default; set REDCON_MCP_ENABLE_RUN=1 to enable.
Inputs: command (required), cwd, quality_floor, timeout_seconds, +4 more.
redcon_searchA
Regex search. scope='ranked' (default) limits matches to the task's relevant files; scope='all' covers the whole repo. Prefer over raw grep on large repositories.
Inputs: task (required), pattern (required), repo, scope, +2 more.
redcon_structural_searchA
Search by AST pattern (ast-grep), not regex, so matches skip comments and strings. Needs ast-grep on PATH or redcon[ast_grep]; returns backend=unavailable otherwise so callers fall back to redcon_search.
Inputs: pattern (required), scope, language, max_results.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools have clearly distinct purposes: repo_map provides ranked file signatures, overview gives directory grouping, rank prioritizes files, compress condenses a file, search and structural_search differ by regex vs AST, and budget plans token allocation. The only notable overlap is between redcon_run and redcon_quality_check, both of which run shell commands and compress output, but their verification approaches differ.
All tools share the redcon_ prefix and use snake_case, but the second part mixes nouns (repo_map, overview, budget) and verbs (rank, compress, search, run) without a consistent verb_noun pattern. This makes the API slightly less predictable, though still readable.
9 tools is well-scoped for a code exploration and compression server. Each tool covers a distinct phase of the workflow—ranking, mapping, searching, compressing, budgeting, and running commands—without unnecessary bloat or gaps.
The tool surface covers the core workflows: orientation (overview), relevance ranking (rank), structural mapping (repo_map), searching (search, structural_search), file compression (compress), budget planning (budget), and command execution (run, quality_check). A direct full-file read is absent, but that is intentional given the server's compression-focused design, so the gap is minor.
Maintenance
Related MCP Connectors
Codebase intelligence for agents: 152 structured artifacts across 21 programs, one call.
Context selection and compression for AI agents - recall measured, not claimed.
Evidence-backed project memory and checkpoints for AI coding agents.
Token-efficient search for coding agents over public and private documentation.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceLocal-first code retrieval for AI agents — cuts codebase context from thousands of tokens to a few hundred, with zero hallucinated file paths.3-
- AlicenseNot gradedqualityBmaintenanceDeterministic context compression for MCP agents, reducing token usage via 11 tools for prompts, history, shell output, file deltas, and code navigation without ML or GPU.9MIT
- AlicenseNot gradedqualityBmaintenanceReduces token consumption for AI coding agents by 50-70% through intelligent code context filtering, Git delta tracking, and local SQLite/Tree-sitter indexing.167 npmMIT
- AlicenseNot gradedqualityCmaintenanceTask-adaptive repository context for coding agents, enabling budgeted evidence retrieval without API keys or network calls.1MIT