Contextmaxxing

Historical Windows baseline (unattested and predating later hardening): one reviewed pre-rename rctx binary indexed a pinned 1.1-million-line Django checkout into 22.8 MiB in 4.32 seconds and produced 4K-budget context in 491 ms p50. The current source is not claimed to reproduce those numbers until it receives a clean, source-attested rerun.

The baseline used one host (4.56 seconds initial-index process wall; 10 warm query samples). It measures engine operations, not whether coding agents use fewer tokens or solve more tasks. Raw-input checksums, binary/repository hashes, limitations, and smaller itsdangerous/ripgrep runs are in BENCHMARKS.md.

Contextmaxxing turns (repository, task, token budget) into a compact evidence package. It combines literal and normalized lexical search, Tree-sitter syntax, a confidence-graded code graph, and a representation-aware hard-budget packer. It is not another coding agent, repository concatenator, or mandatory embedding service.

Normal operation is local: no account, API key, telemetry, model call, or source-code upload.

Thirty seconds to useful context

Rust 1.88 or newer is required to build from source.

git clone https://github.com/313Wentzy/Contextmaxxing.git
cd Contextmaxxing
cargo install --locked --path .

cd /path/to/repository
contextmaxxing index .
contextmaxxing context "Find why authentication sessions occasionally expire early" \
  --budget 5000

The first command builds a compressed persistent index. Normal Git repositories store it under .git/contextmaxxing/; linked worktrees and submodules use their validated Git administration directory, so the worktree remains clean. Non-Git repositories use .contextmaxxing/. Put project-specific exclusions in .contextmaxxingignore. Existing .git/rctx/, .rctx/, and .rctxignore locations and rules remain available for legacy compatibility. Same-schema indexes at a legacy path migrate automatically; snapshots from older index schemas fail closed with an explicit rebuild instruction.

The second command hashes/synchronizes changes, ranks exact and structural evidence, and writes a Markdown package to stdout. Progress and diagnostics use stderr.

What the package contains

contextmaxxing context "Where is authentication handled?" --budget 4000 --format json

JSON includes:

• repository-relative path and exact byte/line span;
• source hash and index generation for staleness checks;
• symbol and representation (full_symbol, signature, or excerpt);
• ranking signals, traversal reasons, and token cost;
• relationship endpoints, kind, evidence grade, confidence, and reason;
• the complete rendered package inside the requested token budget.

Contextmaxxing labels Tree-sitter relationships syntactic. A same-name/import heuristic is never called compiler-precise. SCIP/LSP-backed identities are a planned separate evidence tier.

CLI

contextmaxxing index [PATH]                       initial parallel index
contextmaxxing sync                               synchronize one generation
contextmaxxing watch                              watch; hashes verify event hints
contextmaxxing context TASK --budget 8000         one-shot context compilation
contextmaxxing changed-context                    focus on Git working-tree changes
contextmaxxing search QUERY --source              literal/source + lexical fallback
contextmaxxing symbol QUERY
contextmaxxing references QUERY
contextmaxxing callers QUERY
contextmaxxing callees QUERY
contextmaxxing dependencies QUERY
contextmaxxing tests QUERY
contextmaxxing architecture
contextmaxxing status
contextmaxxing bench --repeat 20                  raw warm-query samples
contextmaxxing serve                              MCP over stdio

Text, Markdown, and structured JSON are supported. Machine-readable index, sync, status, context, and benchmark outputs make the tool suitable for scripts as well as interactive use.

MCP integration

Point any stdio-compatible MCP client at the globally installed executable:

{
  "mcpServers": {
    "contextmaxxing": {
      "command": "contextmaxxing",
      "args": ["--repo", "/absolute/path/to/repository", "serve"]
    }
  }
}

The primary tool is repo_context(task, budget, format). Nine focused companion tools cover literal/lexical search, symbol lookup, references, callers, callees, dependencies, related tests, architecture, and changed context. The surface stays small so an agent can request one complete package instead of reconstructing it through a long sequence of graph calls.

repo_search synchronizes the accepted file inventory by default. Its optional sync=false mode deliberately queries the last index snapshot while still verifying and reading current bytes for those indexed files.

The server uses JSON-RPC/MCP 2025-06-18, bounded frames and closed argument schemas. Context-tool budgets cover the complete model-visible tool result. Non-context tools have bounded result counts but do not expose a token-budget parameter.

How it works

ignore-aware scanner -> content hashes -> Tree-sitter file facts
        |                                      |
        +---- normalized postings + literal scan ----+
                                               v
                                   confidence-graded graph
                                               v
task identifiers/terms/paths/Git changes -> deterministic ranking
                                               v
                         full unit | signature | excerpt
                                               v
                      hard-budget context packer

Files own their extracted facts. An ordinary sync reparses only added/changed files, updates changed lexical/name buckets, and recomputes graph origins whose symbol, import, or test relationships may have changed. Updates adding, replacing, or deleting 128 or more files deliberately fall back to one deterministic derived rebuild. Tests compare incremental facts and normalized contexts with clean rebuilds.

The research and alternatives behind the design are in docs/architecture-research.md. The exact invariants, persistence model, and known weak points are in ARCHITECTURE.md.

Language capabilities

V1 has syntax extractors for Rust, Python, JavaScript, TypeScript/TSX, Go, Java, C, C++, C#, and Ruby. JSON, TOML, YAML, Markdown, shell, manifests, configuration, and unknown UTF-8 text remain searchable and participate in path and lexical ranking.

This is parser coverage, not uniform semantic coverage. Dynamic dispatch, overloads, macros, reflection, generated code, and string wiring can defeat syntactic resolution. Literal and normalized lexical/source search remain available for those cases.

Benchmarks without the compression theater

Contextmaxxing separates three questions:

1. Do extracted facts and incremental generations equal a clean rebuild?
2. Does a package retain judged evidence at each budget?
3. Does the same coding agent still pass official tests while consuming fewer discovery tokens and calls?

The first is covered by golden and adversarial tests. The second has a small self-retrieval regression, explicitly labeled human_pending. The third has a provider-neutral A/B/C harness and offline fake-adapter smoke, but no public model run yet. Therefore Contextmaxxing makes no compression multiplier or agent-success claim.

Every headline benchmark number comes from a reviewed artifact with ignored raw-input checksums. See BENCHMARKS.md and benchmarks/README.md for the methodology and commands.

Privacy and security

Contextmaxxing itself performs no network requests and contains no telemetry path. Repository content and indexes stay on the machine. Scanning/index ingestion rejects links/reparse points, root escapes, likely binary data, invalid UTF-8, and files outside configured size bounds. Later source-consuming operations repeat the path/size/binary checks and skip bytes that are no longer valid UTF-8. Snapshot decoding and persistence are bounded and fail closed on unsafe parent/destination paths.

An MCP client may send returned context to its configured model; that behavior belongs to the client. Likewise, raw coding-agent benchmark logs can contain model output or secrets and must be reviewed before publication.

Contributing

cargo fmt --all -- --check
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked --all-targets --all-features

New extraction rules need golden spans, grammar/runtime compatibility coverage, an incremental-versus-clean case, and a dependency/license review. See CONTRIBUTING.md and ROADMAP.md.

MIT licensed.