ContextFlux is a local context engine and MCP server for coding agents. It classifies the current workflow, fuses lexical, path/symbol, dependency/test-graph, and workflow-specific rankings, then returns source-cited code ranges under a measured token ceiling.

It needs no API key, embedding model, daemon, or hosted index. It never executes repository code and never sends source, queries, or telemetry over the network.

Status: v0.1 is an experimental developer preview. The public API and index schema may change before v1. See limitations before production use.

Why ContextFlux?

A coding agent rarely needs every file. It needs different evidence for different jobs:

• a test when implementing a change;

• the source frame and dependencies when debugging a trace;

• downstream importers and tests before a risky edit;

• nearby code and configuration when addressing review feedback.

Recent repository-retrieval research supports this task-specific approach. The Agent Retrieval Bench reports that no single retrieval family wins across all coding-agent workflows, while repo maps are especially effective under tight context budgets. SWE-Explore evaluates ranked code regions under fixed line budgets, and context compression experiments show that smaller, more precise contexts can sometimes improve both quality and latency.

ContextFlux turns those ideas into a small, offline tool:

task / trace / review comment
              |
       workflow classifier
              |
   +----------+----------+-----------+-----------+
   | lexical | path     | code graph| task prior|
   +----------+----------+-----------+-----------+
              |
      reciprocal-rank fusion
              |
    cited ranges + exact budget

Quick start

Node.js 20 or newer is required.

git clone https://github.com/divyanshu-iitian/ContextFlux.git
cd ContextFlux
npm ci
npm run build

node dist/cli.js index .
node dist/cli.js context "Fix the login timeout and update its tests" --budget 3000

Run directly from GitHub without a global install:

npx --yes --package=github:divyanshu-iitian/ContextFlux \
  contextflux context "Trace the invalid credentials error" --root . --budget 3000

Useful CLI commands:

contextflux search "createSession" --limit 8
contextflux context "Add regression tests for login" --intent code2test --budget 2500
contextflux context "Show the blast radius of changing src/auth.ts" --intent edit2ripple
contextflux map --budget 1200
contextflux stats
contextflux benchmark benchmarks/self.json

The incremental cache lives at .contextflux/index.json, which should remain gitignored.

Connect an agent over MCP

Add this to an MCP client's configuration, replacing the root with an absolute path to the repository the agent will work on:

{
  "mcpServers": {
    "contextflux": {
      "command": "npx",
      "args": [
        "--yes",
        "--package=github:divyanshu-iitian/ContextFlux",
        "contextflux-mcp"
      ],
      "env": {
        "CONTEXTFLUX_ROOT": "/absolute/path/to/repository"
      }
    }
  }
}

On Windows, use npx.cmd if the client does not resolve npx. Restart the client after saving the configuration.

The server exposes four read-only tools:

An agent skill and drop-in instruction files are included under skills/context-efficient-coding and integrations.

Retrieval modes

Leave the mode on auto in normal use, or choose one explicitly:

Every search result includes a path, line range, symbols, preview, score, and human-readable evidence signals. Scores rank candidates; they are not calibrated probabilities.

Library API

import { ContextFlux } from "contextflux";

const flux = new ContextFlux({ root: process.cwd() });

const packet = await flux.context(
  "Show the blast radius of changing src/auth.ts",
  { intent: "edit2ripple", budgetTokens: 3_000 },
);

console.log(packet.context);
console.log(packet.reductionPercent);

budgetTokens is enforced against the rendered packet with the GPT-4o tokenizer. For a model with a different tokenizer, leave headroom.

Evaluation

The benchmark runner accepts gold-file cases and reports:

• mean reciprocal rank;

• Recall@5 and Recall@10;

• budgeted context yield (gold files present in the final packet);

• average packet tokens;

• the same retrieval metrics for a plain lexical baseline;

• measured lift over that baseline.

[
  {
    "id": "code-to-test",
    "task": "Add regression tests for token-budget enforcement in src/engine.ts",
    "intent": "code2test",
    "goldFiles": ["test/engine.test.ts"],
    "budgetTokens": 3000
  }
]

Run the checked-in smoke set:

npm run build
node dist/cli.js benchmark benchmarks/self.json --root . --json

The smoke set checks wiring and regressions; it is not evidence of state-of-the-art quality. For externally valid comparisons, evaluate on Agent Retrieval Bench or another independent dataset and publish the full configuration.

How it compares

These projects solve adjacent problems and can be complementary:

ContextFlux does not claim to replace language servers, embeddings, or full coding agents. Its narrow job is budgeted evidence retrieval.

Research basis

The implementation is informed by, but is not an official implementation of, these papers:

• Yuan et al., Agent Retrieval Bench (27 July 2026): task-dependent retrieval families, natural no-gold cases, and budgeted context yield (paper, benchmark).

• SWE-Explore (June 2026): code-region retrieval under fixed exploration budgets (paper).

• CORE-Bench (June 2026): repository-level code retrieval evaluation (paper).

• RANGER (2025): graph-enhanced repository retrieval (paper).

• Context compression for coding agents (April 2026): empirical quality/latency trade-offs (paper).

Privacy and security

• Indexing, ranking, tokenization, and context assembly run locally.

• Symlinks and paths escaping the configured root are rejected.

• Binary, generated, dependency, lock, and oversized files are skipped by default.

• Repository text is returned as untrusted evidence, never executed as instructions.

• The cache contains source-derived terms and previews; protect it like source code.

Please report vulnerabilities according to SECURITY.md.

Limitations

• Import extraction is intentionally lightweight and currently recognizes common JavaScript, TypeScript, Python, Rust, Go, Java, Kotlin, Ruby, and PHP forms. It is not a compiler.

• Dynamic imports, aliases, generated sources, and runtime wiring may not form graph edges.

• Retrieval is lexical/structural; semantic paraphrases can be missed without shared terms.

• Confidence is deliberately not presented as calibrated. Closely ranked candidates produce a verification warning.

• The index is single-process and intended for local developer repositories, not a shared multi-tenant service.

Contributing

Issues, benchmark cases, language resolvers, and reproducible retrieval improvements are welcome. Read CONTRIBUTING.md before opening a pull request.

MIT licensed. Built by Divyanshu.