python -m pip install "codenib[graph,mcp]"
codenib codegraph init /path/to/your/repo
That one command detects the repository languages, installs the pinned
package-level graph providers it can manage, builds BM25 plus a source-linked
symbol graph, and registers the resulting MCP server with installed Codex and
Claude Code clients. It is local, open source, requires no model or cloud, and
does not write configuration or indexes into the target repository.
System Architecture
| Layer | Responsibility |
|---|
| View compiler | Chunk source and materialize BM25, dense, graph, and navigation views; reuse current artifacts and atomically rebuild affected views |
| View manifest | Record repository identity, source fingerprint, builder profile, capabilities, status, and artifact location independently for each view |
| Context serving | Execute lexical, semantic, hybrid, reranked, and structural query plans while preserving repository-relative source locations |
| Agent runtime | Expose capability-aware MCP and LSP-shaped tools, assemble bounded evidence, and return citations that agents and humans can inspect |
repository change
-> reuse current views or rebuild affected views
-> publish a capability-bearing manifest
-> plan repository queries
-> deliver bounded, source-linked context
On a later commit, CodeNib reuses views whose source and builder identities are
still current. A requested view affected by source or policy changes currently
rebuilds in an isolated generation; file- and symbol-level delta repair remains
disabled until it can use the same pinned source authority.
Quickstart
Requires Python 3.10+ and Git. For an agent-ready CodeGraph with no model or API
key, install the graph and MCP extras and run one command:
python -m pip install "codenib[graph,mcp]"
codenib codegraph init /path/to/repository
codegraph init detects Codex and Claude Code, installs only the detected
languages' package-managed providers, builds reusable bm25 and
symbol_graph views, and asks each native client CLI to own its configuration.
Run codenib codegraph status /path/to/repository to diagnose the complete
path or codenib codegraph uninstall /path/to/repository to remove only the
managed client registrations. The index remains reusable.
Repositories can persist exact root-relative subtree exclusions when generated
or vendored content should not be indexed:
codenib codegraph init /path/to/repository \
--exclude-dir ios/Pods \
--exclude-dir generated/api
Paths use repository-relative POSIX spelling (/) and name exact subtrees,
not globs. Repeat --exclude-dir to replace the complete custom exclusion set. Later
init and index runs reuse that policy from the manifest; use
--clear-exclude-dirs to return to the default source surface. CodeNib does not
implicitly treat .gitignore as an indexing policy, because tracked and local
ignored source can still be intentional input.
Zoekt supports the default source policy only when its fixed commit tree
exactly matches the authenticated checkout and contains no tracked path that
the default policy excludes. It does not currently support a non-empty custom
exclusion set. A command that explicitly requests the zoekt view, including
--preset full, fails closed when either condition is unmet; use the
CodeGraph, fast, or semantic paths instead. Authenticated MCP serving for
Zoekt currently requires Linux /proc; see the
source-surface boundaries.
For a browser Wiki with hybrid BM25+dense retrieval, install the semantic extra:
python -m pip install "codenib[semantic]"
codenib wiki /path/to/repository
Both paths keep reusable state under ~/.codenib/repositories and leave the
target checkout unchanged. Set CODENIB_HOME to relocate state.
Preview the CodeGraph operations without installing, indexing, or configuring
an agent:
codenib codegraph init /path/to/repository --dry-run
For a structural view, CodeNib detects the repository languages and manages
only their package-level providers; operating-system and project prerequisites
remain explicit:
python -m pip install "codenib[graph]"
codenib toolchain install /path/to/repository --scope graph
codenib doctor /path/to/repository --require graph
Export that indexed commit as a serverless Wiki when a live Ask backend is not
needed:
codenib export /path/to/repository --output /tmp/repository-wiki
The export contains a versioned provenance manifest, precomputed Wiki pages,
source citations, and available page-level dependency data. It contains no
provider credential; interactive Ask and runtime graph exploration remain on
the local or MCP serving path.
For a repository-hosted Wiki, CodeNib also ships a reusable GitHub workflow
that builds or reuses the same manifest, deploys the static site to Pages,
and uploads the matching commit-addressed context artifact. Its default
semantic route builds BM25 and vector views with a cached local Hugging Face
model and needs no API key. An explicit fast route avoids the model download;
a BYO OpenAI-compatible endpoint can replace local embedding. Query-time search
remains in the local or MCP runtime. See
GitHub Pages.
The published BM25/vector artifact can then be verified against an exact local
checkout and served through MCP without rebuilding the repository views.
See the
Quickstart
for ports, advanced indexing, and troubleshooting.
Serve An Agent
The recommended path configures installed Codex and Claude Code clients through
their native CLIs:
python -m pip install "codenib[graph,mcp]"
codenib codegraph init /path/to/repository
Ask the agent to start with explore_context for bounded, source-verified
repository context and use dependency_subgraph for caller impact or callee
dependencies. The MCP server also exposes ranked BM25, regex, definition,
reference, route, and bounded source-read tools. See the
CodeGraph guide for client scopes,
diagnostics, uninstall behavior, and language prerequisites, and the
MCP Server for the complete tool contract.
The same planner is available directly to Python agents:
from codenib.agent import RepositoryContextExplorer
with RepositoryContextExplorer.from_repository(
"/path/to/repository", policy="auto"
) as explorer:
result = explorer.explore("where is request retry behavior implemented?", top_k=10)
Each result includes source-validated evidence plus the selected plan,
capabilities, loaded views, fusion, graph, and reranking trace.
What CodeNib Provides
| Surface | Purpose |
|---|
| View compiler | Build independently managed views, reuse current generations, and atomically rebuild changed views under one source identity |
| Agent context runtime | Plan capability-aware retrieval and navigation, then assemble bounded source-linked evidence |
| Retrieval | BM25, dense-vector, regex/trigram, Zoekt, fusion, and reranking paths; see the validated model matrix |
| Structural context | SCIP/LSP-backed symbol graphs with source locations and typed edges |
| MCP and LSP-shaped tools | Serve one manifest to coding agents without tying the runtime to one agent framework |
| Agent compatibility | Reuse one manifest across revision-pinned LocAgent, Agentless, CoSIL, and OrcaLoca contracts, plus the published RepoNavigator jump contract over SCIP/LSP definition signals; see the support matrix |
| Benchmark compatibility | Evaluate native exploration against pinned external datasets and scorers, including SWE-Explore; see the dataset and benchmark matrix |
| Local inspection | Audit the same context through Wiki pages, Ask answers, citations, and the Dependency Map |
| Evaluation harness | Measure retrieval, navigation, incremental maintenance, and context policies on the same artifacts |
Language support varies by surface. The generated
capability matrix
records chunking, graph, incremental, and C++ decoder support.
Documentation
Build the documentation site locally with:
python -m pip install -e ".[dev]"
mkdocs serve
Development
git clone https://github.com/sysevol-ai/CodeNib.git
cd CodeNib
make dev
make test
The test suite is split into unit, integration, serial integration, core,
graph-consumer, and slow tiers. See
CI/CD before
running the credential- or toolchain-dependent tiers.
Status
CodeNib is currently in beta. The CLI and manifest format are usable, but
public interfaces may still change before a stable release. Historical
research artifacts retain their published dataset identifiers; the maintained
package, import namespace, commands, and repository use CodeNib. See
Naming.
Citation
If you use CodeNib in your research, please cite our
arXiv paper:
@misc{yu2026codenibmultiviewdataserving,
title={CodeNib: A Multi-View Data System for Serving Repository Context to Coding Agents},
author={Zhongming Yu and Hengjia Yu and Boqin Yuan and Shuting Zhao and Yizhao Chen and Aryan Dokania and Mihir Jagtap and Jiayu Chang and Yitong Ma and Yash Jayswal and Wentao Ni and Hejia Zhang and Zhaoling Chen and Gangda Deng and Jishen Zhao},
year={2026},
eprint={2607.25431},
archivePrefix={arXiv},
primaryClass={cs.SE},
url={https://arxiv.org/abs/2607.25431},
}
Project
Website
·
Releases
·
Changelog
·
Contributing
License
CodeNib is licensed under the
Apache License, Version 2.0.
