Code Context Fabric

Code context fabric for AI coding agents — deterministic call-graph indexing, hybrid retrieval, and a single-tool MCP interface.

Code Context Fabric builds a local, zero-cost code intelligence layer that lets AI coding agents (Codex, Claude Code, and other MCP clients) answer structural questions without reading entire files.

"Who calls this method, and what would break if I change its signature?"
→ explore(query, task="impact", repo=".", max_tokens=4000)
→ [verbatim source slices + call paths + blast radius + known blind spots]

Why

AI agents that rely on grep or full-file reads waste tokens and miss cross-file call chains. Existing tools either require cloud APIs, embed LLMs in the index layer, or carry restrictive licenses. Code Context Fabric takes only the verified-consensus patterns from the landscape and assembles them locally.

Related MCP server: codemap

Design

Six primitives, all independently validated across multiple open-source tools:

Not included: LLM in the index layer (rejected by every serious tool), code sent to external APIs, opinionated semantic summaries.

Roadmap

Each milestone ships a ccf verify --level mN gate that runs in CI.

Verification approach

Benchmarks use public repos only — no proprietary code enters this repository.

SOTA alignment — measured, not claimed

Code Context Fabric ships a reproducible benchmark harness and refuses to count low-confidence or ambiguous edges as resolved coverage.

Pinned commit dae37cf…; apples-to-apples scope gson/src/main/; both source and target files must be inside the scope.

Code Context Fabric passes its release gates and is in the same measured coverage band, while remaining 2.47 percentage points behind CodeGraph on this benchmark. We therefore claim alignment, not universal superiority. Coverage cannot be improved by adding ambiguous edges: the gate pairs it with ambiguity and fixture precision.

ccf verify --level benchmark
ccf benchmark run --repo /path/to/gson --name gson \
  --scope-prefix gson/src/main/ --output gson.json
ccf benchmark compare --candidate gson.json --target benchmarks/sota-targets.yaml

See benchmark methodology, the checked-in Code Context Fabric v0.2 baseline, and the CodeGraph 1.5 comparison.

Indexing performance (v0.5.0, measured on an 884-file / 16.7k-node repo)

Indexer.build_incremental takes a fast path — re-resolving only the changed files — whenever it can prove the repo-wide symbol table is unaffected (see ADR-0005); otherwise it falls back to a full rebuild. Both incremental cases above are confirmed byte-identical (graph_signature) to a full rebuild. Full builds parse files in parallel via ProcessPoolExecutor once a batch is large enough to amortize pool startup.

Install

git clone https://github.com/Rajahn/code-context-fabric && cd code-context-fabric
uv sync --extra dev

uv run ccf build /path/to/your/java/repo     # index a repo, $0, no LLM
uv run ccf check /path/to/your/java/repo      # OK | STALE (content-hash freshness)
uv run ccf init /path/to/your/java/repo       # inject AGENTS.md protocol block
uv run ccf watch /path/to/your/java/repo      # OS-event auto-sync, 2s debounce
uv run ccf verify --level m2                  # watcher + incremental consistency gate
uv run ccf overlay scip --repo . --index path/to/index.scip  # layer typed edges (M3)
uv run ccf verify --level m3                  # typed overlay merge/precision gate
uv run ccf verify --level query               # query-facade gate (qualified syntax, panorama, cluster rank)
uv run ccf serve                              # start the MCP server (explore() tool)

fabric remains available as a compatibility alias for every ccf command above.

v0.3.0 supports Java only, via tree-sitter plus an optional SCIP-derived typed overlay. M2 adds conservative overload/type resolution, REFERENCES, annotation symbols, unresolved-candidate storage, framework entry-point metadata and auto-sync. M3 adds ccf overlay scip, which merges compiler-derived *_TYPED edges onto the existing graph without ever dropping an edge — see docs/adr/0003-typed-overlay.md. v0.4.0 adds a query facade in front of the same graph — see docs/adr/0004-query-facade.md — plus an optional .repoweaver/entrypoints.yaml in your own repo to extend or replace the built-in (public-annotation-only) entry-point table with your own project's annotations, without ever committing internal names here. No LLM or external network call is made at runtime.

MCP tool

explore(
  query: str,
  task: "understand" | "impact" | "locate" | "debug",
  repo: str = ".",
  max_tokens: int = 4000
) → {
  query, task, repo,
  slices: [{node_id, file, span_start, span_end, source, qualified_name, confidence, provenance}],
  stats: {nodes_visited, edges_traversed, tokens_estimated, freshness},
  blind_spots: "<frozen incompleteness contract string>",
  # task == "impact": + blast_radius: [{depth, node_id, qualified_name, file, edge_type, confidence, risk}]
  # task == "debug":  + call_path: [{step, node_id, qualified_name, file, edge_type, confidence}]
}

See docs/explore-contract.md (frozen v1.1) for the full contract.

Acknowledgements

Design patterns drawn from (not forked from): CodeGraph · Graft · GitNexus · Serena · SCIP · Aider

License

MIT