codebaseGraph

codebaseGraph turns a local source repository into a searchable code graph for AI coding agents. It indexes Python, Rust, Go, C, C++, Fortran, Markdown, and MDX, then exposes compact context, schema information, query helpers, and bounded read-only graph queries through a native CLI and MCP server.

This workspace also ships k-wiki, an optional subsystem for curated repository knowledge. The graph and wiki have separate source and generated state.

Quick start

For a crates.io install, you need Rust 1.82 or newer and Cargo. Run these commands from the repository you want to index:

cargo install codebase-graph
codebase-graph install
codebase-graph check-health --repo-root .

Setup is healthy when the first output line includes health ok=true. Try a search by replacing the example text with a symbol or concept from your repository:

codebase-graph codebase-search "your search term" --repo-root .

For development from this checkout:

cargo install --path . --bin codebase-graph

What setup changes

codebase-graph install:

• materializes the first graph;
• creates repository-local configuration and managed graph state under .codebaseGraph/;
• writes or updates one marked codebaseGraph block in AGENTS.md or CLAUDE.md; and
• installs a Codex MCP client entry unless you skip registration.

The managed MCP service refreshes the graph automatically. Do not rerun install to refresh it. Use codebase-graph reinstall only when setup state must be recreated; reinstall preserves unrelated MCP client entries.

Choose a workflow

Understand the two tools

knowledge/ is curated intent. .kwiki/ is disposable wiki projection state, and .codebaseGraph/ is graph runtime state. Do not edit either generated root as source.

Use the graph

Retrieval commands emit compact block output by default. Use --json --pretty or --format json when you need structured output.

Freshness is automatic while the managed MCP daemon, explicit mcp start, or watch is running. build is for an explicit manual rebuild; use plan first when you want to see what it would touch.

To tune discovery, use .codebaseGraphignore, --include, --exclude, or the materialization include/exclude arrays in .codebaseGraph/config.json. Git discovery respects .gitignore by default and falls back to filesystem scanning when Git is unavailable.

Run a read-only graph query

codebase-graph graph-query \
  "MATCH (n) RETURN count(n) AS total_nodes LIMIT 1" \
  --repo-root .

Write-like graph statements are blocked.

Connect an MCP client

Setup registers Codex by default. To add or refresh registrations explicitly:

codebase-graph mcp install --client codex
codebase-graph mcp install --client all --mcp-transport http-daemon

Supported clients are codex, claude, claude-project, github-copilot, lmstudio, hermes, openclaw, generic, copilot-studio, and microsoft-copilot.

For local clients, the default auto transport resolves to one repository-scoped Streamable HTTP daemon. Local harnesses share the persisted http://127.0.0.1:<port>/mcp endpoint, coordinator, and watcher. Use --mcp-transport stdio only for compatibility, or --mcp-daemon-port to override the stable repository-derived port.

Check or control the daemon with:

codebase-graph mcp daemon status --config .codebaseGraph/config.json
codebase-graph mcp daemon start --config .codebaseGraph/config.json
codebase-graph mcp daemon stop --config .codebaseGraph/config.json

status keeps its original top-level fields and also reports the service manager state, running/controller versions, manifest drift, the latest bounded failure from .codebaseGraph/mcp-daemon-failure.json, and a directly executable recommended action. Rerunning start repairs an inactive service and reconciles stale daemon versions or supervisor manifests without changing the MCP URL.

Setup installs the user service through launchd on macOS, a systemd user unit on Linux, or Task Scheduler on Windows. A repository lock prevents a second daemon from starting. On macOS, launchd owns the configured loopback listener and starts or restarts the daemon when a client connects, including in on-demand-only user sessions.

Client-specific behavior

• github-copilot writes workspace configuration to .vscode/mcp.json.
• claude targets Claude Code; claude-project targets the repository .mcp.json.
• An explicit Claude Desktop configuration rejects loopback HTTP, but may be registered with explicit stdio.
• copilot-studio and microsoft-copilot report manual_remote_required because their cloud runtimes require a public HTTPS endpoint.

The installer does not publish a loopback URL or provision tunnels, TLS, OAuth, or remote deployment.

Use a lower-level transport

The managed daemon is the normal local path. Stdio and direct HTTP remain available for diagnostics and compatibility:

codebase-graph mcp start --config .codebaseGraph/config.json
codebase-graph mcp http \
  --config .codebaseGraph/config.json \
  --host 127.0.0.1 \
  --port 8765

Security: keep HTTP bound to 127.0.0.1 for normal use. Remote binding requires --allow-remote and a bearer token, but does not provide TLS, rate limiting, authorization scopes, or a multi-user security model. HTTP clients must initialize first and send the returned Mcp-Session-Id header on later requests.

The daemon exposes MCP at /mcp, local health metadata at /_codebasegraph/health, and authenticated shutdown using a rotating state-file token.

Available graph tools

Refresh a registration after upgrading

Upgrading the binary does not rewrite an existing client registration. If a client still invokes codebase-graph mcp start, rerun the installer for that registration, then restart the client:

codebase-graph mcp install --client codex --scope local \
  --config-path .codebaseGraph/config.json \
  --mcp-transport http-daemon \
  --verify

Add curated knowledge with k-wiki (optional)

Use k-wiki when your repository needs curated, searchable knowledge alongside the generated code graph.

k-wiki install
k-wiki mcp install --client codex

k-wiki install creates a starter source bundle at knowledge/index.md and generated state beneath .kwiki/. Rerunning it is safe. It also maintains the MCP-only k-wiki workflow block in AGENTS.md and CLAUDE.md while preserving surrounding instructions.

Wiki MCP registration records a stdio command; it does not start a persistent server process, so k-wiki must be on PATH when the client starts it.

See the Knowledge Wiki guide for other repository roots, static site builds, supported clients, registration locality and naming, validation, authoring, and upgrade steps.

Develop and verify

cargo fmt --check
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo test --workspace --locked
cargo build --locked --release --bin codebase-graph
cargo publish --dry-run --locked

Release maintainers also use the policy and packaged-artifact checks:

cargo run -p xtask -- release-gate --production \
  --confirm release-environment \
  --confirm hosted-ci-green \
  --confirm private-vulnerability-reporting
cargo run -p xtask -- smoke-artifact target/release/codebase-graph

Release and security

CI runs formatting, linting, tests, advisory scanning, package dry-run checks, native package builds, and artifact smoke tests. See the release process for the full workflow and conda-forge checklist.

Report suspected vulnerabilities privately. See the security policy for supported versions, reporting expectations, and the local-first MCP security boundary.

Troubleshoot