ckg — deterministic code knowledge graph for coding agents

ckg turns a repository into a deterministic, local-first knowledge graph — files, classes, functions, their containment, references, and functional relationships — and serves it to coding agents over MCP. Instead of dumping your repo into a prompt, an agent navigates the graph: it asks "where does auth begin?" and gets the entry point, the call path, and just the source that matters.

• Deterministic. The same code always produces a byte-identical graph (two-hash Merkle design). No sampling, no drift.
• Zero-config. No network, no auth, no API key, no model download. Parsing is tree-sitter compiled to WASM — plain Node, all platforms.
• Self-healing. There is no build step to remember. Every query triggers an incremental refresh: unchanged files are reused via content hashes, so a clean tree costs a hash sweep, not a re-parse.
• Committable cache. Everything in .ckg/ is keyed by content hash. Commit it and every clone gets a warm graph — including LLM summaries one contributor paid for once.
• Local-first, zero egress. Nothing leaves your machine. The one optional outbound step (summaries) goes through your own Claude CLI.

Quickstart

Claude Code

ckg install

Run inside your repo — this writes .mcp.json (and configs for any other detected hosts). Or manually:

claude mcp add ckg -- npx -y ckg mcp

Cursor / Windsurf

ckg install detects them, or add to .cursor/mcp.json:

{ "mcpServers": { "ckg": { "command": "npx", "args": ["-y", "ckg", "mcp"] } } }

Codex CLI

ckg install writes .codex/config.toml, or:

codex mcp add ckg -- npx -y ckg mcp

That's it. The first query builds the graph (seconds on a mid-size repo); every later query self-heals incrementally.

Optional enhancements

ckg summarize   # LLM summaries on every node, via your Claude CLI (cached, resumable)
ckg embed       # local embeddings for semantic search (downloads a small ONNX model)

Both write into .ckg/, keyed by content hash. Commit .ckg/ and your whole team — and every fresh clone — inherits the summaries and vectors without re-running anything. (.ckg/models/ is machine-local and gitignored.)

CLI

The same engine the agents use, from your terminal:

ckg locate "where do we resolve import aliases"   # ranked hits + snippet of the top hit
ckg search "rate limiting"                        # hybrid symbol/lexical/semantic search
ckg map                                           # repo map ranked by PageRank
ckg build                                         # explicit (re)build — optional, for CI / prepaying

ckg --help for everything, --json on any query for machine-readable output.

MCP tools

locate, entry_point, search, get_context, get_source, neighbors, expand, get_repo_map, pack_neighborhood, get_minimal_context. Summaries are cheap; source is a deliberate separate call — the agent reads the map before it reads the territory.

How it works

Discovery → tree-sitter parse → containment tree → two-hash Merkle (identity + content) → reference resolution (pluggable per-language resolvers) → graph in .ckg/graphs/self/graph.json (canonical JSON, stable key across clones). Summaries and embeddings are separate content-hash-keyed caches layered on top. See plan/ for the full design docs.

Languages: TypeScript/TSX, JavaScript, Python, Go, Rust, Java, C, C++, C#. Adding one means adding a tree-sitter grammar + a small language spec (queries for definitions, imports, entries) — the core is language-agnostic.

Development

npm install
npm run typecheck
npm run build            # tsup → dist/, `node bin/ckg.mjs`
npm run test:determinism # byte-identical rebuild — the flagship invariant
npm run test:m3          # incrementality
npm run test:m6          # retrieval + MCP

The former Electron desktop shell is parked under legacy/electron/; its React graph explorer will return as ckg ui (localhost web page). Deferred designs (dominator-based entry points beyond what's shipped, graph version control, graph-driven review) live in plan/.

License

MIT