cg / code-graph
Start

Installing and updating cg

cg is a Python package (Python 3.11+). The PyPI name is cg-code-graph; the commands are cg and cg-mcp. It installs as a user-level tool. No checkout and no sudo.

New here? Quick start indexes a sample app and runs the first queries in a few minutes.

Install

Recommended.

uv tool install cg-code-graph

Virtual environment

Inside a venv, pip works too.

pip install cg-code-graph

cg doctor

cg doctor

It lists the tools it found, whether extractor dependencies are installed, and for each language whether indexing is exact or heuristic. Pass a project path to check that project. The MCP doctor tool prints the same report.

One MCP server for many graphs

cg install --host cursor registers one project graph. In a project it also writes a short "use cg first" rule for agents: a marked section in AGENTS.md and .cursor/rules/cg.mdc (--no-rules skips both; see Install into a host). When several repos would each add their own cg-* server, register them once and run a single cg-mcp:

cg install --global --registry --host cursor
cg install --global --migrate --host cursor          # dry run
cg install --global --migrate --apply --host cursor  # write ~/.config/cg/graphs.toml and the host config

--registry writes one cg entry with no --db. The server reads ~/.config/cg/graphs.toml (CG_GRAPHS overrides the path). --migrate folds existing per-repo cg-* entries into that file. It prints the plan and writes nothing until --apply, which also saves a .bak of each config it changes. Details: MCP server.

JavaScript runtime

TypeScript / JavaScript indexing needs Node.js 20+ or Bun (tested with Bun 1.4.2). Lookup order: CG_NODE, then node, then bun on PATH. Extractor dependencies install with npm ci, or bun install when npm is missing. A Bun-only container (oven/bun) needs nothing else. cg doctor names the runtime it found.

Update and uninstall

Update.

uv tool upgrade cg-code-graph

Uninstall.

uv tool uninstall cg-code-graph

The old package name codegraph (through v0.9.0) is removed by the install scripts. By hand: uninstall codegraph, then install cg-code-graph.

Upgrading to 0.17

0.17 renames the import package to cg_code_graph. Two other PyPI projects (codegraph and codegraph-py) already ship a top-level codegraph package, and another project uses the older environment prefix, so this project no longer uses either.

  • Environment variables are CG_* (CG_JOBS, CG_CACHE, …). The CODEGRAPH_* names were removed in 0.19.0: rename CODEGRAPH_<NAME> to CG_<NAME>, and rename CODEGRAPH_CACHE and CODEGRAPH_CACHE_DIR to CG_CACHE.
  • The cache root is ~/.cache/cg (%LOCALAPPDATA%\cg on Windows, or $XDG_CACHE_HOME/cg). The first command that uses the default root moves ~/.cache/codegraph there and drops swift-build/ (SwiftPM build directories embed absolute paths, so the next Swift index rebuilds). Extractor installs, SCIP output and fact caches move with it. Set CG_CACHE to keep a cache where it is.
  • python -m cg_code_graph.cli replaces python -m codegraph.cli. python -m cg_code_graph works the same way. The cg and cg-mcp commands are unchanged. MCP entries that cg install wrote with an absolute cg-mcp keep working. An entry that still runs python -m codegraph.mcp_server is reported by cg doctor; re-run cg install.
  • Git hooks that still run python -m codegraph.cli stop refreshing until you re-run cg hooks install. cg hooks status and cg doctor name an outdated hook.

Elsewhere

  • Extractors install on the first index that needs them, or with cg setup. Cache and prune: cg setup -h and clean.
  • Exact mode for Rust, C / C++, Kotlin and Swift needs optional indexers: Rust, C and C++, Kotlin, Swift. Java heuristic mode needs no JDK; cg setup java / install.sh --with java print the JDK 17+ hint for scip-java (Java).
  • What the install scripts do: install.sh --help. Working on a checkout of cg: Contributing.

Generated, copied and vendored files

cg keeps generated files out of the graph by default and lists them in cg coverage. A copy points back at the file you edit.

Java

What .java adds beyond Install, CLI specs, and Graph schema: the heuristic syntax layer and the ids those pages do not spell out. Toolchain fit: cg doctor. Why a file stayed heuristic: cg coverage.