CodeGraphX (CGX)

<p align="center"> <img src="assets/logo.png" alt="CodeGraphX (CGX) logo — codebase graph engine and MCP server for AI coding agents" width="30%" border-radius="50%" /> </p> <p align="center"> <a href="https://www.npmjs.com/package/codegraphx"><img src="https://img.shields.io/npm/v/codegraphx.svg" alt="npm version" /></a> <a href="https://www.npmjs.com/package/codegraphx"><img src="https://img.shields.io/npm/dm/codegraphx.svg" alt="npm downloads" /></a> <a href="LICENSE"><img src="https://img.shields.io/npm/l/codegraphx.svg" alt="license" /></a> <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-blue.svg" alt="node version" /></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-server-8A2BE2.svg" alt="MCP server" /></a> <a href="https://techcraze00.github.io/CodeGraphX/"><img src="https://img.shields.io/badge/docs-website-2563eb.svg" alt="website" /></a> </p> <p align="center"><strong>Website:</strong> <a href="https://techcraze00.github.io/CodeGraphX/">techcraze00.github.io/CodeGraphX</a> · <strong>npm:</strong> <a href="https://www.npmjs.com/package/codegraphx"><code>codegraphx</code></a></p>

CodeGraphX (CGX) is a local, token-efficient codebase graph engine for AI coding agents and human developers. It parses your source with Tree-sitter, stores a bi-temporal semantic graph in SQLite, and serves it over a CLI and an MCP server — so an agent can ask "what breaks if I change this function?" and get an exact answer in a few hundred tokens instead of reading 50 files.

---

What is CodeGraphX?

Definition — CodeGraphX is a code intelligence layer: a persistent, queryable graph of your codebase's symbols (functions, classes, variables), their relationships (calls, called_by, imports, inherits, cross-language API_CALLS), and how they change over time.

What kind of tool is it? It sits in the same family as a Language Server (LSP) or a code-search index, but it is purpose-built for LLM agents:

• A Language Server answers "go to definition" for an editor, one symbol at a time.
• A grep / embedding search finds text, not structure.
• CodeGraphX answers structural, whole-repo reasoning questions — impact/blast-radius, dependency cycles, cross-language contracts, "does this symbol even exist?" — and serializes the answer in a token-optimized form an agent can drop straight into its context.

The core problem it solves — AI coding agents burn most of their token budget re-discovering a codebase: opening files, scrolling, grepping, re-reading the same modules every session. CodeGraphX indexes once and answers those questions from a graph, so the agent spends tokens reasoning instead of scanning.

---

Why it's useful (the token economics)

Every agent action has a token cost. Consider a common question: "What will break if I change validateInput?"

| Approach | What the agent does | Rough context cost | |---|---|---| | No CGX | Greps for validateInput, opens ~15–50 candidate files, reads each to trace call sites | tens of thousands of tokens, several tool round-trips | | With CGX | explain_impact({ symbol_name: "validateInput" }) → one small JSON of upstream callers + downstream callees | a few hundred tokens, one round-trip |

The savings compound because CGX serializes its graph in TOON (Token-Oriented Object Notation) instead of JSON — a compact tabular encoding that removes the repeated keys and braces that dominate JSON token counts.

Honest framing: the accuracy numbers below are measured against a hand-labeled corpus. The token figures above are an illustrative model of typical agent behavior, not a lab benchmark — the exact ratio depends on your repo and agent. The mechanism (one targeted graph query vs. many file reads) is what delivers the win.

Where CGX pays off most:

• Large / unfamiliar repos where "read everything" is infeasible.
• Long agent sessions (the graph is a cache the agent doesn't have to rebuild).
• Cross-language stacks (React ⇄ Express/Flask/FastAPI) where call graphs don't span files.
• Refactors and reviews, where blast-radius and dead/broken-import detection matter.

---

Full capabilities

| Capability | What it gives you | |---|---| | 🧠 Symbol graph | Every function/class/method with calls, called_by, imports, inherits edges | | ⚡ O(1) symbol lookup | Bloom filter answers probable_yes / definite_no without touching the DB | | 💥 Impact tracing | Recursive upstream (callers) / downstream (callees) blast-radius via a SQL CTE | | 🌉 Cross-language linking | Matches frontend fetch/axios calls to backend routes as confidence-scored API_CALLS edges | | 🕑 Bi-temporal history | Append-only graph — query the codebase as of any commit; nothing is ever destroyed | | 🩺 Doctor diagnostics | Reports missing/unresolvable imports, unresolved call targets, circular dependencies, syntax errors | | ✅ Task verification | Compares a task description against a commit's actual symbol changes; flags untested additions | | 🔀 Session / branch diff | Structural summary of added/removed/modified symbols vs. HEAD or a branch | | 🌐 Interactive dashboard | D3.js force graph of the whole codebase in the browser | | 📦 TOON artifacts | Token-optimized graph + file-index exports for agent context injection | | 🔐 100% local | No cloud, no telemetry, no network — code never leaves the machine | | 🤖 MCP server | 6 tools exposed to any MCP-compatible agent, with zero-config auto-indexing |

---

Tech used in this project

| Layer | Technology | |---|---| | Parsing | Tree-sitter with per-language grammars (tree-sitter-python, -javascript, -typescript, -html, -css) | | Storage | SQLite via better-sqlite3 (default) or Postgres (pg), through the Kysely type-safe query builder | | Agent protocol | Model Context Protocol SDK (@modelcontextprotocol/sdk) over stdio | | Probabilistic lookup | bloom-filters | | Token-optimized output | TOON (@toon-format/toon) | | CLI | Commander + @clack/prompts for the interactive setup | | File watching | chokidar | | Runtime | Node.js ≥ 18, CommonJS |

---

Supported languages

| Language | Extensions | Extracts | |---|---|---| | Python | .py | functions, classes, calls, imports (incl. package-relative . / ..), Flask/FastAPI routes | | JavaScript | .js, .jsx | functions, classes, arrow fns, calls, imports/require, local bindings, fetch/axios calls, Express routes | | TypeScript | .ts, .tsx | same as JS plus TS-specific declarations | | HTML | .html | elements / structural symbols | | CSS | .css | selectors (classes, ids) |

---

Installation

# Global (recommended)
npm install -g codegraphx

# Or per-project
npm install --save-dev codegraphx

# Verify
codegraphx --version        # 1.2.4

The CLI is available as codegraphx, cgx, and the MCP entrypoint cgx-mcp.

---

Quick start

cd your-project

# 1. Index the codebase → writes .codegraphx/ + .codegraphx.db
cgx init

# 2. Ask questions
cgx query authenticateUser                       # where is it, what calls it, what it calls
cgx impact authenticateUser --direction downstream --depth 5
cgx impact authenticateUser --direction upstream
cgx stats                                        # files / symbols / edges
cgx doctor                                       # health report

# 3. Optional live view
cgx watch                                        # re-index on file change
cgx dashboard                                    # open the D3 graph in a browser

Re-scanning is a full rewrite. Each cgx init / cgx scan rebuilds .codegraphx/ from scratch: files deleted from disk are evicted from the graph, stale artifacts are wiped, and the database temporal-closes removed symbols — so the graph always matches your working tree. Unchanged files are still served from cache, so it stays fast.

CLI command reference

| Command | Purpose | |---|---| | cgx setup | Wire the MCP server + skill into your coding CLIs (see below) | | cgx init / cgx scan | Full index of the codebase | | cgx query <symbol> | Show a symbol's file, type, calls, and called_by | | cgx impact <symbol> [--direction up/downstream] [--depth N] | Trace the blast radius | | cgx doctor [--json] [--strict] [--no-calls] | Diagnostics: imports, calls, cycles, syntax | | cgx stats | Counts of files / symbols / functions / classes / edges | | cgx watch | Auto-update the graph on file changes | | cgx dashboard | Open the interactive codegraph.html | | cgx git-hook <install\|remove> | Auto-scan on post-commit / pre-push | | cgx session summary [--branch <b>] | Structural change summary for the current session | | cgx verify --task <desc> --commit <hash> | Task-vs-commit verification evidence |

---

MCP server (for AI agents)

CodeGraphX ships an MCP stdio server exposing 6 tools. Zero-setup: you don't have to scan first — on its first start in a project, the server indexes the codebase in the background. While indexing, get_graph_status reports "indexing"; once "ready", all tools are live.

Available MCP tools

| Tool | Description | Parameters | |---|---|---| | get_graph_status | Readiness: indexing / ready / error, plus file count | — | | list_files | List indexed files | filter?: string | | check_symbol_exists | O(1) Bloom lookup → probable_yes / definite_no | name: string | | explain_impact | Upstream callers + downstream callees of a symbol | symbol_name: string | | verify_task | Compare a task description to a commit's real changes | task_description: string, commit_hash?: string | | get_session_diff | Structural summary of the current session/branch | branch?: string (default HEAD) |

Example agent workflow

User: "What breaks if I change the validateInput function?"

Agent (via MCP):
  1. check_symbol_exists({ name: "validateInput" })   → { exists: "probable_yes" }
  2. explain_impact({ symbol_name: "validateInput" })
       → { used_by_upstream: ["src/auth.js::login"],
           breaks_downstream: ["src/api.js::handleRequest"] }

Result: exact answer, no file scanning.

Picking the project root

The server indexes the directory it starts in. If your client doesn't set one, pass it explicitly:

cgx-mcp --project-root /path/to/project
# or
CGX_PROJECT_ROOT=/path/to/project cgx-mcp

---

Setup — how easy is it?

One command

cgx setup

It auto-detects the coding CLIs you have installed, lets you multi-select which to configure, and wires each one — no hand-editing config, no hunting for absolute paths. It registers the MCP server (via each CLI's native command where available, with a JSON-file fallback) using an absolute Node path + the bundled cgx-mcp, so it works for both global and local installs, and it installs the CGX usage skill/instructions in each CLI's format.

cgx setup                                   # interactive multi-select
cgx setup --agents claude,gemini --yes      # non-interactive (CI / scripted)
cgx setup --project                         # register for the current repo only

Registration is user/global by default, so you run it once and it works in every project — cgx-mcp resolves the project from wherever your CLI launches. Existing config is preserved; a backup is written before the first edit.

Support