Skip to content

Quickstart

This guide first connects a source-linked CodeGraph to Codex or Claude Code, then covers the browser Wiki and advanced retrieval paths. The CodeGraph path uses BM25 plus static symbol relationships and needs no model or API key.

Install

  • Python 3.10 or newer
  • Git

Install the exact release with its graph and MCP dependencies from PyPI:

python -m pip install "codenib[graph,mcp]==0.2.3"
codenib --version

The version command must report codenib 0.2.3. Exact version pins keep the environment reproducible.

Connect A CodeGraph To Your Agent

From any directory, point the initializer at the repository:

codenib codegraph init /path/to/repository

CodeNib performs five bounded steps:

  1. Detects supported source languages.
  2. Installs only package-managed graph providers required by those languages; system and project prerequisites remain explicit.
  3. Builds or updates reusable bm25 and symbol_graph views below ~/.codenib/repositories.
  4. Detects installed Codex and Claude Code clients and registers a uniquely named stdio MCP server through each client's native CLI.
  5. Writes a private CodeNib management receipt outside the checkout so repeat initialization is idempotent and uninstall can fail closed on drift.

The command does not create .mcp.json, AGENTS.md, CLAUDE.md, or index files in the repository. Codex owns its user-level registration; Claude Code owns a local-scope registration associated with that repository.

The repository must be a clean Git working tree. The initializer does not run project package managers or build systems; it checks the worktree again after indexing and registration. Existing language prerequisites such as node_modules, a Ruby bundle, or compile_commands.json remain under project owner control.

Preview every planned action without a download or write:

codenib codegraph init /path/to/repository --dry-run

For generated or vendored trees, pass exact root-relative exclusions. They are recorded with the source identity and reused by later runs:

codenib codegraph init /path/to/repository --exclude-dir ios/Pods

Repeat the flag to replace the full custom set, or use --clear-exclude-dirs. CodeNib deliberately does not infer this policy from .gitignore; see Select the repository source surface. Each value is an exact repository-relative subtree written with /, not a glob. A non-empty custom set currently cannot be combined with the zoekt view or --preset full; CodeNib fails closed instead of broadening it. Zoekt also refuses a default-policy build when the fixed commit contains a tracked path that the authenticated source policy excludes.

Verify the full path, including source freshness and native client configuration:

codenib codegraph status /path/to/repository
codenib codegraph status /path/to/repository --json

Ask the agent to use explore_context before editing and dependency_subgraph when evaluating callers, callees, or change impact. See Agent-ready CodeGraph for exact tool examples and safe uninstall behavior.

Launch A Repository Wiki

Install the semantic extra when the browser Wiki should use local dense retrieval in addition to BM25:

python -m pip install "codenib[semantic]==0.2.3"

codenib wiki /path/to/repository

CodeNib performs four steps:

  1. Detects supported source languages.
  2. Selects BM25+dense views when semantic dependencies are installed, or reports a no-model BM25 fallback, then builds or updates those views under ~/.codenib/repositories/<repo>-<id>/indexes.
  3. Registers the repository with a local FastAPI service.
  4. Serves the packaged production frontend and opens http://localhost:3000.

The release wheel contains the compiled frontend, so this path does not need Node.js, npm, or a source checkout. CodeNib-owned indexes and manifests stay outside the target repository; set CODENIB_HOME to relocate that state. The lexical and semantic views leave the checkout unchanged. Some language-aware graph backends must invoke the repository's build or package manager and may prepare project-local dependencies such as node_modules; run those profiles from a clean checkout when that distinction matters. Press Ctrl-C once to stop both services.

Use different ports or keep the browser closed when needed:

codenib wiki . --port 3100 --api-port 8100 --no-open

Reuse An Existing Index

The default command compares the repository with its existing manifest and updates changed views. To reuse an already-built manifest without performing that index update:

codenib wiki /path/to/repository --no-index

--no-index requires an existing repo_manifest.json. It skips rebuilding or updating views, but still validates that the current checkout matches the manifest's recorded source identity and commit; CodeNib refuses to launch on a mismatch.

Force a clean rebuild with:

codenib wiki /path/to/repository --rebuild

Export A Static Wiki

An existing manifest can be frozen into a serverless directory for GitHub Pages or another static host:

codenib index /path/to/repository
codenib export /path/to/repository --output /tmp/repository-wiki

The export records the repository commit, source fingerprint, view capabilities, source-location convention, generation mode, and content hashes in codenib-static.json. It also embeds source slices used by page citations, so reading a page does not require the local FastAPI process. CodeNib rejects an export when the checkout no longer matches the manifest.

For a GitHub project Pages site, set its mount path to the repository name:

codenib export . \
  --output /tmp/my-project \
  --base-path /my-project

The output must be outside the target checkout. CodeNib can replace a prior CodeNib export, but it refuses to delete an unrelated non-empty directory.

Static mode publishes only capabilities with a serverless implementation: Wiki navigation, embedded citations, and precomputed page dependency views. Interactive Ask, on-demand edge labels, and arbitrary dependency queries need an authenticated CodeNib runtime and are not exposed by the export. No API key, GitHub token, endpoint credential, or build-machine absolute path is serialized.

To build the index and both distribution surfaces in one command:

codenib publish . \
  --preset fast \
  --site-output /tmp/repository-wiki \
  --context-output /tmp/repository-context \
  --base-path /repository

The context directory is commit-addressed query-serving state with an artifact-relative manifest and file hashes. It excludes mutable maintenance caches. Portable publication currently supports fast and semantic; use the local or MCP runtime for graph and Zoekt views. See Publish With GitHub Pages for the no-model Action, local embedding model, and BYO endpoint configurations.

Select Repository Views

Preset Required package Views
fast codenib BM25
semantic codenib[semantic] BM25 and dense vectors
graph codenib[graph] BM25 and symbol graph
full codenib[full] BM25, dense vectors, symbol graph, and Zoekt

Building the Zoekt view and serving it are separate boundaries. In 0.2.2, authenticated MCP search_zoekt serving requires Linux /proc; macOS and Windows fail closed instead of handing the process a mutable shard path.

The recommended installation already selects semantic through the default auto preset. Select it explicitly in automation when the artifact contract must not depend on the installed environment:

codenib wiki /path/to/repository --preset semantic

The semantic preset downloads CodeRankEmbed on first use. CodeNib pins the built-in model to an immutable revision and enables remote model code only for that revision; caller-supplied models or revisions are not trusted implicitly. Custom Hub code requires both an explicit trust_remote_code=True and a full 40-character commit SHA. Local model directories may opt in without a Hub revision. To keep embeddings out of the local process, use a BYO OpenAI-compatible embedding service:

python -m pip install "codenib[semantic-remote]==0.2.3"
export EMBEDDING_API_KEY=...
codenib doctor --require semantic \
  --embedding-provider openai \
  --embedding-endpoint https://inference.example.com/v1 \
  --embedding-api-key-env EMBEDDING_API_KEY \
  --probe-embedding
codenib wiki . --preset semantic \
  --embedding-provider openai \
  --embedding-endpoint https://inference.example.com/v1 \
  --embedding-api-key-env EMBEDDING_API_KEY

The remote default is text-embedding-3-small with dimension 1536. Select another model with --embedding-model and declare its vector width with --embedding-dimension; omit --embedding-api-key-env only when the endpoint is intentionally unauthenticated. Provider, model, endpoint, dimension, and vector-shaping options become part of the vector artifact identity. Credentials, retries, timeouts, and batching stay process-local, and CodeNib refuses to reopen an artifact through a different provider or endpoint.

Credentials And Tokens

The default local CodeRankEmbed route, BM25 fallback, static export, and Wiki shell need no credential. GitHub Pages also uses GitHub's short-lived workflow token for deployment; users do not provide a personal token for the default workflow.

Use environment variables for the capabilities that do need authentication:

Capability Credential How CodeNib receives it
BYO OpenAI-compatible embeddings Provider API key Name the variable with --embedding-api-key-env
Generated Wiki pages and Ask LiteLLM provider key Use the provider's normal variable or --api-key-env
Download a GitHub Actions context artifact Fine-grained token with Actions: read Export it as GH_TOKEN

For example:

# Remote embeddings. The key value never appears in the command line.
export CODENIB_EMBEDDING_API_KEY=...
codenib wiki . --preset semantic \
  --embedding-provider openai \
  --embedding-endpoint https://embeddings.example.com/v1 \
  --embedding-api-key-env CODENIB_EMBEDDING_API_KEY

# Agent-authored pages through an OpenAI-compatible chat endpoint.
export OPENAI_API_KEY=...
codenib wiki . --generate \
  --model openai/gpt-4o-mini \
  --api-key-env OPENAI_API_KEY

# Reuse the token already managed by GitHub CLI for artifact download.
export GH_TOKEN="$(gh auth token)"

For GitHub Actions, create CODENIB_EMBEDDING_API_KEY under Settings > Secrets and variables > Actions, then map it to the reusable workflow's embedding_api_key secret. CodeNib records provider identity and the name of the credential variable, never its value. Secrets are excluded from manifests, context artifacts, generated MCP configuration, and static Pages output.

Language Toolchains

The graph extra supplies the Python graph and protobuf runtimes. SCIP, clangd, and live LSP providers are language-specific executables, so CodeNib plans them from the detected repository rather than installing every language:

python -m pip install "codenib[graph]==0.2.3"
codenib toolchain status /path/to/repository --scope graph
codenib toolchain install /path/to/repository --scope graph
codenib doctor /path/to/repository --require graph

Package-managed providers are pinned under ~/.codenib/toolchains and are automatically visible to CodeNib processes; no shell PATH export is needed. The installer never invokes sudo and never silently edits the target checkout. It reports system dependencies such as clangd or a JDK, and project-local requirements such as compile_commands.json or scip-php, for the user to satisfy explicitly.

Static graph construction and live incremental navigation are separate surfaces. Install live language servers only when that path is needed:

codenib toolchain install /path/to/repository --scope lsp
codenib toolchain status /path/to/repository --scope all

The full preset also needs zoekt-git-index and zoekt-webserver on PATH. codenib doctor --require graph checks language-specific graph providers, not Zoekt. Follow SCIP Indexing, check the Language Capabilities matrix, and verify the Zoekt commands separately:

command -v zoekt-git-index
command -v zoekt-webserver

Override individual views or language detection:

codenib index . --view bm25 --view vector
codenib index . --language python --language typescript

Both options may also use comma-separated values.

Enable Agent-Authored Pages

Static Wiki pages are the default. To generate conceptual page narratives through a LiteLLM-supported provider:

python -m pip install "codenib[agent,semantic]==0.2.3"
export OPENAI_API_KEY=...
codenib doctor --require agent \
  --model openai/gpt-4o-mini --api-key-env OPENAI_API_KEY --probe-model
codenib wiki . --generate --model openai/gpt-4o-mini

For an OpenAI-compatible local or hosted endpoint:

export LOCAL_LLM_KEY=...
codenib wiki . --generate \
  --model openai/local-model \
  --api-base http://127.0.0.1:8080/v1 \
  --api-key-env LOCAL_LLM_KEY

CodeNib passes BYO credentials only to the running client. They are never written to repo_manifest.json, vector configuration, Wiki caches, or a static Pages export.

Provider-native LiteLLM routes use their normal model prefix and credentials:

export ANTHROPIC_API_KEY=...
codenib wiki . --generate --model anthropic/claude-sonnet-4-5

Vertex AI additionally requires CodeNib's vertex extra:

python -m pip install "codenib[agent,semantic,vertex]==0.2.3"
gcloud auth application-default login
codenib wiki . --generate \
  --model vertex_ai/gemini-2.5-flash \
  --model-option vertex_project=my-project \
  --model-option vertex_location=us-central1

Choose the route that matches the server actually receiving the request:

Backend --model shape Endpoint and authentication
OpenAI openai/<model> OPENAI_API_KEY
Anthropic anthropic/<model> ANTHROPIC_API_KEY
OpenAI-compatible gateway or vLLM openai/<served-model> --api-base .../v1; add --api-key-env only when the gateway requires it
Ollama ollama/<model> --api-base http://localhost:11434
Azure OpenAI azure/<deployment> API base and key, plus --model-option api_version=...
Vertex AI vertex_ai/<model> vertex_project, vertex_location, and Google Application Default Credentials

The provider prefix is required even when --api-base points to a custom gateway. For example, use openai/qwen3, not bare qwen3, for an OpenAI-compatible Qwen endpoint.

Repeat --model-option KEY=VALUE for provider-specific LiteLLM parameters. Values are JSON-decoded and dotted keys create nested payloads. This flag is available on codenib wiki and codenib doctor; configure the standalone codenib-web service through YAML or CODENIB_DEMO_* environment variables.

codenib wiki . --generate \
  --model openai/qwen3 \
  --api-base http://127.0.0.1:8080/v1 \
  --model-option extra_body.chat_template_kwargs.enable_thinking=false

CodeNib manages model, credentials, token budgets, messages, and tools; those fields cannot be overridden through --model-option. Keep secrets in provider environment variables or --api-key-env, not option values. Run the same model arguments through codenib doctor --probe-model before generating pages. The static doctor validates provider routing, endpoint shape, explicit options, and known environment requirements. The probe then sends three tiny requests to verify plain completion, tool calling for Ask, and structured output for generated Wiki pages.

Provider and model configuration is documented in Web UI and the LiteLLM provider documentation. Search, source links, and deterministic pages remain available without this extra. Ask is model-backed: if its configured provider cannot authenticate or cannot be reached, the question request fails while the rest of the Wiki continues to work.

Serve The Index Over MCP

python -m pip install "codenib[mcp,semantic]==0.2.3"
codenib index /path/to/repository
codenib mcp /path/to/repository

codenib mcp accepts either a repository directory or the generated repo_manifest.json. It uses stdio transport, so configure it as a local process in an MCP-capable client. See MCP Server for an example.

Troubleshooting

Run the capability report first:

codenib doctor
codenib doctor . --require semantic --require graph

Common fixes:

  • Install the named extra when a command reports a missing optional module.
  • Use --rebuild after intentionally changing index profiles or builders.
  • Check that frontend port 3000 and API port 8000 are free, or select alternatives. Run a local OpenAI-compatible model on a separate port such as 8080.
  • Pass --language when a repository contains no detectable supported source extension.