OpenCodeHub

Code intelligence for AI coding agents, under Apache-2.0, on an all-OSS stack.

npm install -g @opencodehub/cli
cd /path/to/your/repo
codehub init && codehub analyze
# your agent now has impact, query, context, detect_changes — 28 tools over MCP

Why this exists

AI coding agents have a structural blind spot: they can see a file, but they can't see the graph the file lives in. This causes three recurring failures that anyone who has shipped with a coding agent has lived through:

1. Missed dependencies. The agent renames a function and doesn't touch the 14 callers it can't see, because grep found 3.

2. Broken call chains. The agent changes a return shape, the handler two hops downstream explodes at runtime, and neither the agent nor its tests flag it — the relationship was never in context.

3. Blind edits. The agent edits a critical-path function without knowing it's on the hot path of 8 production flows, because nothing computed that ahead of time.

Grep is textual. Language servers are per-file. Embeddings are lossy. None of them answer the questions an agent actually needs answered before it writes a diff: what breaks if I change this? what depends on this? where does this data flow?

Related MCP server: graqle

What OpenCodeHub solves

OpenCodeHub indexes your repository into a hybrid knowledge graph (structural + semantic) and exposes it to agents over the Model Context Protocol. Agents stop guessing and start asking:

impact(target: "validateUser")
→ direct callers: 14 · affected processes: 3 · risk: HIGH
→ fix direction: dependents (input validation boundary)

query("auth token refresh flow")
→ process: auth.refresh_token (7 steps, 4 files)
→ process: oauth.rotate_session (5 steps, 3 files)

context(name: "PaymentProcessor")
→ callers · callees · processes it participates in · ACCESSES edges · docstrings

The graph is precomputed at index time — clustering, execution-flow tracing, and blast-radius analysis are done once, not at every query. That means agents get complete relational context in one tool call, not ten round-trips.

flowchart LR
  A[Source tree] -->|tree-sitter parse| B[Symbol graph]
  B -->|resolve imports / MRO| C[Typed relations]
  C -->|BM25 + HNSW index| D[Hybrid graph store]
  C -->|detect communities + flows| E[Processes / clusters]
  D --> F[MCP server]
  E --> F
  F -->|28 tools| G[AI coding agent]

Design choices worth knowing

Platform support

Parsing is WASM and runs anywhere Node does. The storage and embedding tiers, however, depend on prebuilt native bindings — @ladybugdb/core (graph store), @duckdb/node-api (temporal store), and onnxruntime-node (local embeddings) — so OpenCodeHub runs on the platforms those bindings ship a prebuild for:

On an unsupported platform the lbug binding fails to load and open() throws GraphDbBindingError (there is no DuckDB-graph fallback — see ADR 0016). The five-target prebuilt matrix mirrors @ladybugdb/core's release artifacts; track its upstream for musl / win32-arm64 coverage.

Quick start

Install from npm (recommended)

Requirements: Node 22 or 24.

# global install — puts `codehub` on your PATH
npm install -g @opencodehub/cli

# or run without installing
npx @opencodehub/cli --help

Bootstrap any repo and start querying:

cd /path/to/your/repo

# writes .mcp.json so Claude Code / Cursor launch `codehub mcp`,
# installs the Claude Code plugin, appends .codehub/ to .gitignore,
# seeds opencodehub.policy.yaml
codehub init

# index the repo (WASM parser, no native binaries needed)
codehub analyze

# your agent can now call impact, query, context, detect_changes, …

Build from source

Requirements: Node 22 or 24; pnpm 11+; Python 3.12 (only needed for SCIP indexers on Python-heavy repos); mise recommended.

git clone https://github.com/theagenticguy/opencodehub
cd opencodehub
mise install
pnpm install --frozen-lockfile
pnpm run check          # lint + typecheck + test + banned-strings
mise run cli:link       # puts `codehub` on your PATH

MCP tool surface (28 tools)

Architecture decision records live in docs/adr/. A Claude Code plugin at plugins/opencodehub/ wraps the MCP tools into skills + a code-analyst subagent — install via codehub init.

Repository layout

The monorepo is organised as 18 workspace packages under packages/:

The retrieval / graph-quality evaluation harness and the per-language F1 regression gym used to live here as eval and gym; they were extracted into the sibling opencodehub-testbed repository so the production package set ships free of test-time dependencies.

Embedding backends

OpenCodeHub ships with three embedding backends — all serve the same gte-modernbert-base 768-dim space, all use CLS pooling + L2 norm — and picks one at runtime based on environment variables:

SageMaker-specific vars:

IAM: the caller needs sagemaker:InvokeEndpoint on the endpoint ARN — e.g. arn:aws:sagemaker:us-east-1:<account>:endpoint/gte-modernbert-embed.

Do not mix backends against the same index. Backends are pinned to a single model identity via the modelId stamp in the embeddings table; switching mid-project requires codehub analyze --rebuild-embeddings. --offline refuses SageMaker and HTTP backends, so offline mode is compatible only with the local ONNX path.

Storage backend — lbug graph + DuckDB temporal

The graph tier is always @ladybugdb/core (<repo>/.codehub/graph.lbug); the temporal tier — cochanges, structured symbol summaries, and the codehub query --sql escape hatch — is always DuckDB (<repo>/.codehub/temporal.duckdb). Both files are written on every analyze. There is no CODEHUB_STORE env var, no backend probe, no single-file graph.duckdb layout, and no mtime arbitration; if the lbug binding fails to load, open() throws GraphDbBindingError and the operation aborts.

IGraphStore lives only on GraphDbStore; DuckDbStore implements ITemporalStore only. The segregated interfaces stay because they are the v1.0 contract for community-fork adapters (AGE / Memgraph / Neo4j / Neptune target IGraphStore; DuckDB owns ITemporalStore). Embeddings live in graph.lbug and stream into a per-call DuckDB temp table at pack time so the byte-identical Parquet sidecar still works.

See docs/adr/0016-duckdb-graph-rip.md for the rationale behind ripping out the DuckDB graph backend; it supersedes ADR 0013 and the DuckDB-as-graph passages of ADR 0011.

Parse runtime — WASM-only, vendored grammars

@opencodehub/ingestion runs web-tree-sitter (WASM) as the only parse runtime on the supported Node range (22 and 24). There is no native opt-in: the native tree-sitter N-API addon and all 14 tree-sitter-<lang> npm packages are gone from the install graph, so parsing pulls zero native builds and zero GitHub fetches at install time. (Storage and embeddings load prebuilt native bindings — see Platform support.)

All 15 grammar .wasm blobs are vendored at packages/ingestion/vendor/wasms/, built from the grammar sources pinned in package.json. Re-vendoring is a one-shot operation via bash scripts/build-vendor-wasms.sh (requires docker, podman, finch, or local emcc); consumers never build grammars at install time. The complexity phase (cyclomatic-complexity metrics) is also WASM-backed, so it runs on every install instead of degrading to a no-op.

See docs/adr/0015-wasm-only-parser-at-the-npm-distributed-boundary.md for the WASM-only rationale and the bulletproof-install plan; ADR 0013 records the prior WASM-default + native-opt-in posture and is now superseded.

Status

v1 — feature-complete on M1–M7. Tracks A (M7 graph-DB default + the IGraphStore / ITemporalStore interface segregation), B (19-scanner fleet incl. betterleaks), C (debt sweep — embedder fingerprint, SCIP REFERENCES + TYPE_OF), and D (dogfood polish) have all merged. The published package is @opencodehub/cli (currently 0.7.0; the monorepo root tracks 0.8.0); 1.0.0 is cut once schema + tool-surface stability is signed off.

While on 0.x, any release may contain breaking changes to the graph schema, MCP tool shapes, CLI flags, or storage layout. Breaking changes are called out with ! or a BREAKING CHANGE: footer in the commit log and summarised in each release's generated CHANGELOG.

Troubleshooting

codehub analyze runs out of memory on a large repo

The in-memory graph (KnowledgeGraph) holds the full node and edge set in two JavaScript Maps for the duration of analyze, and bulkLoad materializes transient copies before persistence — there is no spill to disk during the build. A real index is already in the 96k-node / 291k-edge range; a monorepo roughly 10x that size can exhaust Node's default heap and exit with an out-of-memory error (FATAL ERROR: Reached heap limit / JavaScript heap out of memory), sometimes without a clear message.

Raise Node's old-space ceiling for the run via NODE_OPTIONS (nothing is set by default):

# 8 GB heap — bump higher for very large monorepos
NODE_OPTIONS=--max-old-space-size=8192 codehub analyze

Pick a value comfortably below your machine's free RAM. If you still hit the ceiling, analyze a subtree at a time rather than the whole monorepo in one pass.

Supply-chain posture

• CycloneDX SBOM at SBOM.cdx.json (regenerated on every release)

• Third-party license inventory at THIRD_PARTY_LICENSES.md

• CI gates: license allowlist, banned-strings grep, OSV vulnerability scan, CodeQL SAST, OpenSSF Scorecard

• Zero open CVEs on the lockfile at release time

Documentation

Architecture decision records live in docs/adr/ — the durable record of design tradeoffs (storage backend, SCIP adoption, hierarchical embeddings, CI toolchain pins, etc.).

The user guide + MCP reference is published at https://theagenticguy.github.io/opencodehub — an Astro Starlight site whose source lives in-repo at packages/docs/ and deploys to GitHub Pages on every push to main.

Contributing

See CONTRIBUTING.md. Issues and discussions welcome; PRs must pass pnpm run check and have a filled-out PR template.

License

Apache-2.0. See LICENSE and NOTICE.