codebaseGraph

codebaseGraph is a local knowledge graph for AI coding agents. It builds a syntax-level searchable graph from Python, Rust, Go, C, C++, Fortran, Markdown, and MDX files into a LadyBugDB-backed graph, then exposes search, compact context, schema, query helpers, and read-only MCP tools.

The shipped CLI and MCP server are native Rust binaries.

Quick Start

cargo install codebase-graph
codebase-graph install
codebase-graph mcp start --config .codebaseGraph/config.json

For local development from this checkout:

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

Install creates:

.codebaseGraph/
  config.json
  manifest.json
  <repositoryName>_graph.ldb

The install command performs first-time setup: it materializes the initial graph, writes or updates one marked codebaseGraph block in AGENTS.md or CLAUDE.md, and installs a Codex MCP client entry unless skipped. After setup, the MCP server watches the repo and refreshes the graph automatically; rerunning install is not part of the refresh workflow.

Use codebase-graph reinstall only when local setup state needs to be recreated. It moves aside the existing .codebaseGraph state, runs install again, and refreshes the selected MCP registration without removing unrelated MCP client entries.

MCP Install

codebase-graph mcp install --client codex

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

github-copilot writes VS Code workspace configuration to .vscode/mcp.json. copilot-studio and microsoft-copilot are metadata-only targets: they print stdio and local HTTP connection details for manual Copilot Studio onboarding and do not provision a hosted connector, TLS, OAuth, or remote deployment.

MCP Usage

Stdio is the default transport for local MCP clients:

codebase-graph mcp start --config .codebaseGraph/config.json

HTTP is available for local endpoint clients:

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

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.

Available MCP tools:

• graph_health
• graph_search
• graph_context
• graph_schema
• graph_query_helpers
• graph_architecture_queries
• graph_query with write-like statements blocked

CLI Workflow

codebase-graph check-health --repo-root .
codebase-graph codebase-context SampleService --repo-root . --profile definitions
codebase-graph graph-query "MATCH (n) RETURN count(n) AS total_nodes LIMIT 1" --repo-root .

Retrieval commands emit block format by default for agent-facing output. Use --json --pretty or --format json for structured inspection.

Freshness is automatic while codebase-graph mcp start or codebase-graph watch is running. Use build only for an explicit manual rebuild, and use plan to inspect what a manual build would touch:

codebase-graph plan --repo-root . --json
codebase-graph plan --repo-root . --git-diff --git-base main --json
codebase-graph watch --repo-root . --debounce-ms 250
codebase-graph build --repo-root . --mode full --parallel --progress --json

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

Development

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 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
cargo publish --dry-run --locked

Release and Security

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

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

Troubleshooting

• Missing LadyBugDB: install codebase-graph from crates.io, a release artifact, or this checkout.
• Stale graph: ensure codebase-graph mcp start --config .codebaseGraph/config.json or codebase-graph watch --repo-root . is running; use codebase-graph build --repo-root . --mode full only for an explicit manual rebuild.
• Broken setup state: run codebase-graph reinstall to recreate .codebaseGraph and refresh the selected MCP registration.
• Broken client config only: rerun codebase-graph mcp install --client <client> --verify.
• PATH or executable issues: ensure the native codebase-graph binary is on PATH.
• Unsupported files: binary, vendor, cache, virtualenv, build, dist, .codebase_graph, and .codebaseGraph paths are skipped.
• Lock errors: stop other graph build or install processes using the same .codebaseGraph/<repositoryName>_graph.ldb.