Codegraph: The Code Knowledge Graph That Slashes LLM Token Costs

Ollama: 137K+ Stars — Run LLMs Locally with One Command • Headroom: Compress LLM Inputs by 60-95%

┌──────────────────────────────────────────────────────┐
│              Codegraph Knowledge Graph Engine           │
│                                                      │
│  ┌────────────┐    ┌────────────┐    ┌───────────┐   │
│  │ Source Code │    │  Configs   │    │   Docs    │   │
│  │ (.py,.ts)  │    │  (.yaml)   │    │   (.md)   │   │
│  └─────┬──────┘    └─────┬──────┘    └─────┬─────┘   │
│        │                 │                 │         │
│        ▼                 ▼                 ▼         │
│  ┌───────────────────────────────────────────────┐   │
│  │         Codegraph Indexer & Graph Builder      │   │
│  │  • AST Parsing  • Dependency Analysis          │   │
│  │  • Symbol Linking • Call Graph Construction    │   │
│  └───────────────────────┬───────────────────────┘   │
│                          │ Local vector store         │
│  ┌───────────────────────▼───────────────────────┐   │
│  │  AI Agent Query (Claude Code / Codex / ...)   │   │
│  │  Returns: relevant code snippets, not entire repo │
│  └───────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────┘

Codegraph: source code → knowledge graph → precise agent queries

Introduction #

Every AI coding agent wastes hours sifting through entire codebases — reading thousands of irrelevant files, drowning in context windows, and burning tokens on code it never touches. Codegraph (48,117 GitHub stars) solves this by pre-indexing your code into a local knowledge graph that AI agents query instead of blindly scanning. Result: 40-60% fewer tokens, fewer tool calls, and answers that actually reference the right files. Works with Claude Code, Codex CLI, Cursor, Copilot, Gemini CLI, and any OpenAI-compatible agent. 100% local, zero data leaves your machine.

What Is Codegraph? #

Codegraph is a pre-indexed code knowledge graph that transforms your codebase into a structured, queryable graph database. Instead of an AI agent reading every file in a repo, Codegraph indexes the AST (Abstract Syntax Tree), symbol definitions, function calls, imports, and dependencies — then serves precise results to the agent on demand.

Key capabilities:

• Pre-indexing — Index entire codebases once, query repeatedly
• Local-first — 100% local processing, no code ever leaves your machine
• Agent-agnostic — Works with Claude Code, Codex CLI, Cursor, Copilot, Gemini CLI, and 5+ other agents
• Symbol-aware — Understands function definitions, class hierarchies, imports, and call chains
• Token reduction — Returns only relevant code snippets, not entire files
• Incremental updates — Re-indexes changed files automatically

Built with Python, uses networkx for graph operations and local vector stores (ChromaDB or SQLite) for embedding storage. Indexing a 100K-line codebase takes ~2 minutes.

How Codegraph Works #

Stage 1: Installation #

# Install Codegraph globally
npm i -g @colbymchenry/codegraph

Stage 2: Indexing #

# Index any project
codegraph index /path/to/project --output ./codegraph-data

Codegraph parses source code, configuration files, and documentation to build a structured knowledge graph. It extracts function definitions, class hierarchies, imports, call chains, and file relationships.

Stage 3: Querying #

# Query the indexed graph
codegraph query "How does the user login flow work?" \
  --data ./codegraph-data

The query engine returns relevant code snippets, not entire files. Results include the file path, symbol name, code snippet, and relevance score.

Installation & Setup #

Quick Start #

# Install Codegraph
npm i -g @colbymchenry/codegraph

# Index your project
codegraph index /path/to/project --output ./codegraph-data

# Query the index
codegraph query "Where is the authentication middleware defined?" \
  --data ./codegraph-data

Integration with AI Agents #

# For Claude Code: index before running
codegraph index . --output ./cg-indices

# For Codex CLI: set as codebase index
export CODEGRAPH_INDEX=./codegraph-data
# Codex automatically queries graph before reading files

# For Cursor: use codegraph plugin
# Install from Cursor extensions marketplace

Benchmarks / Real-World Use Cases #

Token Reduction Benchmark #

Testing on a 50K-line Node.js monorepo across 200 agent queries:

| Configuration | Avg Tokens per Query | Total Monthly Tokens | Cost (OpenAI @ $10/M) | |