local code graph / ai context engine · v0.1.6 · MIT

AI agents hallucinate code. ctx gives them the real thing.

ctx indexes your repository into a local, deterministic code graph and answers the questions agents actually ask — where does this symbol live, what would break if I change it, which files does this task need. No embeddings. No API calls. Nothing leaves your machine.

Get started View on GitHub

Eliminating AI Hallucinationsmp4 · 1080p · click to play

one command · one local graph

ctx index

$ 
local · deterministic · offline

FILES: 206files indexed
SYMBOLS: 1,721symbols
EDGES: 594dependency edges
MCP TOOLS: 11MCP tools
TESTS: 111tests passing

measured on ctx's own repository · full command reference

01 / the problem

Agents guess. ctx doesn't.

Hallucinated paths

The agent writes imports that look right but don't exist. Plausible fiction, the highest-cost kind of error.

Context flooding

It dumps whole directories into the token window to be safe, and the signal drowns in the noise.

Missed ripple effects

It changes a symbol and breaks callers it never saw, because nobody told it what imports what.

02 / the solution

A real index. Not a guess.

ctx replaces confident estimates with a graph of what actually exists. Five steps, zero fabrication.

Scan

gitignore-aware crawler walks the tree, hashes every raw file with SHA-256.

Parse

Tree-sitter extractors read real syntax — symbols, kinds, signatures, scopes. No regex.

Resolve

Imports resolve to real files: relative, dotted, use paths, module-relative. Unresolved becomes external — never guessed.

Graph

Files, symbols, and dependency edges land in a transactional SQLite database.

Query

Search, impact, and context read the graph and answer with real file paths.

03 / the code graph

The map is the product.

Every file is a node. Every import, reference, and requirement is an edge. Hover a file and the graph shows you exactly what depends on it — in both directions, computed from real source.

— same rows are byte-identical for the same codebase
— incremental reindex: only changed files are re-parsed
— the whole thing is a portable SQLite file

graph · files → symbols → dependencieshover a node to trace its edges

Hover a node — connected edges are real import/reference relationships extracted by tree-sitter.

04 / deterministic context

Same codebase, same task, same answer.

Context ranking is name-based and deterministic. Token scoring, IDF damping, and hub bonuses pick the files a task needs — and every suggestion carries a machine-checkable reason.

— no embeddings, no LLM calls, no randomness
— keyword, hub, recency, path, and git scoring
— every file explains why it was chosen

ctx context “add Google OAuth”

$ ctx context "add Google OAuth"
Suggested files:
  src/auth/oauth.ts        (score 0.91)
      + path matches keyword `auth`
      + imported by 4 files (hub)
      + modified in working tree
  src/auth/service.ts      (score 0.87)
      + path matches keyword `auth`
  src/config.ts            (score 0.72)
      + path matches keyword `config`
Context budget: 1,842 / 12,000 tokens

reasons are machine-checkable

{
  "file": "src/auth/oauth.ts",
  "score": 0.91,
  "reasons": [
    "path matches keyword auth",
    "imported by 4 files (hub)",
    "modified in working tree"
  ]
}

impact · change src/auth/service.tshover a node to trace its edges

Cycle-safe BFS over the inverted graph. Direct dependents first, then indirect — grouped, never guessed.

depth arg · default 3 · buckets: direct / indirect / test files / unknown

05 / impact analysis

Know the blast radius before you edit.

Change a symbol and ctx walks every transitive dependent, in both directions, cycle-safe by construction. Direct callers, indirect callers, tests — and a visible UNKNOWN bucket for whatever truly can't be resolved.

direct dependents

src/api/user.ts · src/auth/token.rs

indirect

src/billing/invoice.ts · src/billing/pay.go

test files

tests/billing.test.ts

unknown

0 — everything resolved

06 / MCP over stdio

Plug into any MCP client.

A Model Context Protocol server that speaks JSON-RPC 2.0 over standard I/O. Wire it into Claude Desktop, Cursor, opencode, VS Code — anything that speaks MCP. No daemon, no port, no source leaving your machine.

ctx_projectctx_searchctx_skeletonctx_symbolctx_dependenciesctx_dependentsctx_impactctx_contextctx_changedctx_diffctx_stats

opencode / Claude Desktop

{
  "mcpServers": {
    "ctx": {
      "command": "ctx",
      "args": ["mcp", "-R", "/path/to/project"]
    }
  }
}

without a global install

{
  "mcpServers": {
    "ctx": {
      "command": "npx",
      "args": ["-y", "ctxai-cli", "mcp", "-R", "/path/to/project"]
    }
  }
}

Eleven read-only tools: project, search, skeleton, symbol, dependencies, dependents, impact, context, changed, diff, stats. Every path an agent receives comes from the graph.

07 / the CLI

Sixteen commands. One graph.

Every question an agent asks maps to a command. No submenus, no hidden state — `ctx <command> --help` is the whole story.

ctx --help

$ 
local · deterministic · offline

08 / architecture

Six modules. Zero mystery.

The whole system is open source and readable. These are the actual modules in the repository.

src/indexing/

Scanner

gitignore-aware walk, SHA-256 hashing, incremental reindex only on change.

src/parser/

Parsers

tree-sitter extractors for TS, JS, Python, Rust, Go — bounded on malformed input.

src/graph/

Graph

symbols, dependencies, and cycle-safe impact BFS over the inverted graph.

src/context/

Context

deterministic token scoring, IDF damping, hub bonuses. Same query → same answer.

src/git/

Git

symbol-level diff through the git binary. Never executes project code.

src/mcp/

MCP

JSON-RPC 2.0 over stdio. Eleven read-only tools, no daemon, no port.

09 / local first

Your code goes where agents can read it. Nowhere else.

No network

the binary opens no connections, anywhere

No telemetry

nothing is reported, ever

No embeddings

no model download, no API key

No exec

project code is never executed

Local index

one SQLite file in .ctx/

Portable

the .ctx folder is a self-contained graph

10 / supported languages

Five parsers. Real syntax trees.

Tree-sitter, not regex. Everything else is invisible to the index by design.

TypeScript / JavaScript

functions, methods, classes, interfaces, enums, types, constants, fields

import / require / dynamic import() · ./ ../ @/ aliases · index files

Python

functions, methods, classes, constants

dotted, relative & from-import resolution

Rust

fns, methods, structs, traits, impls, enums, constants, modules

use / crate:: / super:: / self:: / mod probing

Go

functions, methods, structs, interfaces

import paths, module-relative resolution

11 / get started

Up in three commands.

1 · install

npm install -g ctxai-cli
ctx --version   # → 0.1.6

2 · index

cd /path/to/project
ctx init        # create .ctx, write config, index
ctx doctor      # verify the index is healthy

3 · ask

ctx context "what does the payment module do?"
ctx impact BillingService.charge
ctx mcp         # expose the code graph to your agent

On Windows? winget install halloffame12.CTX works too, plus per-platform binaries on every release.