Install

Requirements

• OS: macOS, Linux, or Windows. WSL is recommended on Windows for parity with the Linux dev path, but native Windows now works without the MSVC build chain because OpenCodeHub does no native compilation at install time.
• Node.js: Node 20, 22, or 24. The parse runtime is web-tree-sitter (WASM) on every supported version — there is no native opt-in (ADR 0015).

Supported platforms

OpenCodeHub installs with zero native compilation — the parse runtime is WASM, and the two native bindings (@ladybugdb/core for the graph store, @duckdb/node-api for the temporal store) ship prebuilt per platform. The graph store is the narrowest matrix and is mandatory (there is no fallback), so its prebuilt coverage defines where OpenCodeHub runs:

Platform	Supported
macOS arm64 (Apple Silicon)	✅
macOS x64 (Intel)	✅
Linux x64 (glibc — Debian/Ubuntu/RHEL)	✅
Linux arm64 (glibc)	✅
Windows x64	✅
Windows arm64	❌ no @ladybugdb/core prebuilt
Linux musl (Alpine)	❌ no @ladybugdb/core prebuilt

On an unsupported platform the CLI fails fast with a GraphDbBindingError that names the case. For containers, use a glibc base image (node:22, node:22-slim, debian, ubuntu) rather than an Alpine/musl image (node:22-alpine). Windows-on-ARM users should run under x64 emulation or WSL2 with an x64/arm64-glibc Linux until upstream ships the missing prebuilts (tracked upstream in @ladybugdb/core).

• pnpm: >=10.0.0 (the workspace lockfile is generated with 10.33.2).
• Python 3.12: optional, only used by auxiliary tooling (the harness packages do not ship as runtime dependencies). Not required for the CLI or MCP server.
• mise: recommended. It pins Node, pnpm, and Python from the committed mise.toml in one command.

Install paths

Recommended: mise-managed toolchain

clone, pin tools, install, build, link

git clone https://github.com/theagenticguy/opencodehub
cd opencodehub
mise install
pnpm install --frozen-lockfile
pnpm -r build
mise run cli:link          # puts `codehub` on your PATH

mise install activates the Node 22, pnpm 11.1.0, and Python 3.12 pins from mise.toml. pnpm install --frozen-lockfile installs exactly the lockfile-pinned dependencies. pnpm -r build compiles every TypeScript package so the CLI entrypoint at packages/cli/dist/index.js is runnable. mise run cli:link wraps pnpm link --global inside packages/cli/ so codehub resolves from any directory; remove with mise run cli:unlink.

If you would rather install a packed tarball instead of a pnpm symlink (useful in CI images, devcontainers, or when pnpm’s global link conflicts with another tool), run mise run cli:install-global instead — it builds the CLI, runs pnpm pack, and installs the tarball globally.

Without mise: manual toolchain

If you already manage Node and pnpm another way:

1. Install Node 20, 22, or 24 (nvm install 22, fnm install 22, or from nodejs.org). Every supported version uses the same web-tree-sitter (WASM) parse runtime — there is no native parser and no opt-in (ADR 0015).

2. Install pnpm >=11.0.0 (corepack enable pnpm, or npm install -g pnpm@11).

3. Clone, build, and link:

   git clone https://github.com/theagenticguy/opencodehub
   cd opencodehub
   pnpm install --frozen-lockfile
   pnpm -r build
   pnpm --filter @opencodehub/cli link --global

From npm

Global npm distribution of codehub is not yet published. For now, link (or install the packed tarball) from a cloned checkout as shown above. A published @opencodehub/cli package is planned.

Verify the install

After mise run cli:link (or pnpm --filter @opencodehub/cli link --global) finishes, codehub should be on your PATH:

verify the CLI is runnable

codehub --help

Then probe your environment:

probe the dev environment

codehub doctor

codehub doctor checks your Node version, pnpm version, native-module bindings (the DuckDB and LadybugDB prebuilds — parsing is WASM-only, so there is no native parser to probe), and writable paths in ~/.codehub/ and .codehub/. It exits non-zero if anything looks off.

Fallback for unlinked checkouts

If you cannot or will not link the CLI (locked-down CI images, a throwaway clone, etc.), every codehub <subcommand> in these docs works as node packages/cli/dist/index.js <subcommand> from the checkout root. Same arguments, same behaviour. For example:

node packages/cli/dist/index.js --help
node packages/cli/dist/index.js doctor

Optional environment toggles

Storage has no toggle — the graph tier is always LadybugDB (.codehub/graph.lbug) and the temporal tier is always DuckDB (.codehub/temporal.duckdb); both are written on every analyze and there is no backend-selection env var (ADR 0016). Parsing has no toggle either — web-tree-sitter (WASM) is the only runtime (ADR 0015).

Variable	Default	Effect
OCH_VERBOSE	unset	Set to 1 to surface the one-shot advisory the CLI emits when a removed legacy parser env var is still set, in non-TTY environments.

See Configuration for the full inventory.

Next

• Quick start — index this repository and run your first MCP call in 5 steps.
• Your first query — walk through query, context, and impact.