# 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](https://modelcontextprotocol.io). 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

```bash
ckg install
```

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

```bash
claude mcp add ckg -- npx -y ckg mcp
```

### Cursor / Windsurf

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

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

### Codex CLI

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

```bash
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

```bash
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:

```bash
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/](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

```bash
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/](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/](plan/).

## License

MIT