Install OpenCodeHub for any MCP agent

This page is editor-agnostic. It gets codehub on your PATH, indexes a target repo, and points you at the per-editor wiring. If you only use Claude Code, you can stop after step 5 — codehub init writes the right config and links the plugin.

1. Prerequisites

• Node 20, 22, or 24. Parsing is web-tree-sitter (WASM) on every supported version — no native parser, no build step.
• pnpm 10 or newer.
• git.
• Optional: mise — recommended for the per-project tool versions and the cli:link task.

2. Clone and install

clone the repo and install workspace deps

git clone https://github.com/theagenticguy/opencodehub
cd opencodehub
pnpm install --frozen-lockfile

3. Put codehub on your PATH

link the CLI

mise run cli:link

cli:link resolves the workspace @opencodehub/cli package and links its bin into your shell. Verify with codehub --version.

If you do not use mise, run pnpm -F @opencodehub/cli link --global inside the checkout.

4. Initialize a target repo

run inside the repo you want to index

cd /path/to/your/repo
codehub init

codehub init is idempotent. It writes:

• .mcp.json — local-scope MCP server entry pointing at the codehub binary. Picked up by Claude Code, Cursor (when symlinked into .cursor/mcp.json), and any other agent that reads the standard project-scope MCP file.
• .claude/ — links the OpenCodeHub plugin so Claude Code gets slash commands, the code-analyst subagent, and 11 skills.
• .gitignore — appends .codehub/ so the local graph and temporal store stay out of version control.
• opencodehub.policy.yaml — seed policy file (license tiers, risk thresholds). Edit to taste, commit if you want repo-wide policy.

5. Build the first index

initial analyze

codehub analyze

Expect 30 seconds for a small TypeScript service, 1–3 minutes for a medium monorepo, 5–10 minutes the first time on a large repo (after which incremental analyzes are sub-second per file). Output is written to .codehub/ next to the project root.

Storage is split across two always-present files under .codehub/: the graph tier is LadybugDB (graph.lbug) and the temporal tier is DuckDB (temporal.duckdb). There is no selection knob and no fallback — if the LadybugDB binding fails to load, the operation aborts with a GraphDbBindingError. See ADR 0016.

6. Verify the install

health check

codehub doctor

codehub doctor prints the active toolchain: the web-tree-sitter (WASM) parse runtime, the DuckDB native binding (@duckdb/node-api), the LadybugDB graph binding (@ladybugdb/core), and which embedding backend is in effect (SageMaker → HTTP → local ONNX, in that precedence). Parsing is WASM-only on every supported Node version, so there is no native parser binding to probe; the DuckDB and LadybugDB bindings ship prebuilds and should report OK on Node 20, 22, and 24.

7. Wire your editor

The per-editor pages give you the config snippet, the path it goes into, and the verification step.

Claude Code The deepest integration. Plugin, slash commands, subagent, skills.

Cursor .cursor/mcp.json — local stdio.

Codex codex.toml — applies to CLI and IDE extensions.

Windsurf mcp_config.json — Cascade picks it up after restart.

OpenCode opencode.json — embeds the same stdio entry.