FeatureCodeGraph
A map of your code, and proof it still matches
CodeGraph is a local code index for AI coding: one node per module, class, function and method, anchored to file and line, built deterministically from the Python standard library on your own machine. A content hash tells you whether the map still matches the code. Python only, and a repository in another language produces an empty graph.
Last updated:
What you get
Where is this defined, and is that answer still true?
The first question every index answers. The second one decides whether the answer is worth anything, and it is the one an index built once and never checked quietly gets wrong.
codegraph/index (excerpt)
Example – illustrative, not real index datamodule src/checkout/validation
class PostcodeValidator src/checkout/validation.py:14
def validate src/checkout/validation.py:31
def _normalise src/checkout/validation.py:58
def validate_address src/checkout/validation.py:77
nodes 412 files 63 built from content hashesThe index is deterministic: the same code produces the same graph, with no ranking step and no model in the path. Every node carries its file and line, so an answer can be opened rather than believed.
Freshness
A stale map is worse than no map. So it tells you.
Staleness is the failure mode that costs the most, because a stale index is confidently wrong instead of visibly missing.
| State | What produced it | What it means for the next run |
|---|---|---|
| Fresh | Every indexed file hashes to what the graph recorded. | Lookups can be relied on for the files the graph covers. |
| Stale | At least one file's content hash no longer matches. | Rebuild before you trust a lookup. Reality Graph reports it; it does not rebuild behind your back. |
| Incomplete | Files under the declared roots were not indexed, for example non-Python sources. | The map has edges. Treat a missing symbol as unknown rather than as absent. |
The check is computed when a command runs. There is no watcher, no daemon and no incremental update: every rebuild re-parses every file under the declared roots.
By design
Python only, and you hear it from us first
A map trusted past its edges is worse than no map at all. So the edges are printed here rather than discovered in week three.
What you get
- Index every declared Python module, class, function and method, anchored to file and line.
- Run on your machine using five standard-library imports, with a self-test that blocks sockets.
- Report fresh, stale or incomplete by content hash, so a clone is not falsely stale.
- Record lessons locally, anchored to real symbols and scored for relevance to the current task.
What it is not
- Read any language but Python. There is no second parser, and other repositories index to nothing.
- Update incrementally or watch the filesystem. Every rebuild re-parses everything under the declared roots.
- Answer what the code means, only where it is declared.
- Inject a lesson into a prompt. Lessons stay candidates you look at, and nothing is shared anywhere.
The local guarantee covers the indexing layer specifically. A coding run as a whole involves whichever tool you use, and that tool has its own data path.
What a coding tool actually receives is decided in the context pack, and what leaves your machine at all is traced on the data-path page.
Questions people actually ask
- Which languages does the index read?
- Python, and only Python. The file walker accepts .py and there is no second parser, so a repository in any other language produces an empty graph. That is a real limit rather than a roadmap note, and it should decide whether this page is relevant to you.
- Does building the index send my code anywhere?
- No. The indexing layer imports argparse, ast, hashlib, json and os, and nothing else, and the tokenizer self-test blocks sockets to prove it never downloads. That statement covers the indexing layer specifically, not a coding run as a whole.
- How does the freshness check avoid a false stale after a clone?
- It hashes content rather than reading timestamps. A fresh clone resets file times but not the bytes, so it is not falsely reported stale, and an edit that preserved its timestamp is still caught. The check runs when a command runs; nothing watches the filesystem in the background.
- Does the index decide what the model gets to see?
- No. It answers where something is defined. What a coding tool receives is decided by the mission contract and assembled into a context pack, and the index does not add files to it.
Ask your codebase where something is defined
Then ask whether that answer is still true. The second question is the one most indexes cannot answer at all.