It builds the graph from what is actually there.
index walks the workspace, reads each repository, and derives edges from real evidence (imports, manifests, references) rather than from hand-written declarations you have to maintain. Each edge carries the evidence that produced it, so you can inspect why any two repos are connected. Each node gets a structural role based on its position in the graph: a root, a leaf, a hub, a bridge. Nothing is inferred that cannot be shown.
A label that comes from the graph topology is more trustworthy than a label someone wrote in a config file and forgot to update.An atlas of code and knowledge.
The deeper idea behind index is a two-layer map: repos and docs as linked nodes, navigable the way a wiki is navigable. This site is, in that sense, a small atlas of the work. Each flagship page is a node; the connections between the projects are the edges. index makes that structure explicit and machine-readable for a whole workspace, not just a website.
Run it over the actual workspace and a drift signal emerges: places where the real dependencies no longer match the stated ones.
When index was run over the author’s own workspace it found around 80 repos and 32 edges, and it surfaced drift: dependencies that had shifted since the manifests were last written. That is the kind of signal that is invisible when you have to count it by hand but obvious the moment you have a graph.
It does not just draw the map. It checks it.
A map tells you the shape. The next questions are whether it is the shape you meant, and whether it is still that shape today. You write the rules a healthy codebase keeps into a small .index.toml: which layers may depend on which, edges that must never exist, a ceiling on cycles. index check measures the real graph against them and returns a certificate.
The verdict is one of three words, MATCH, DRIFT, or UNVERIFIABLE, and never a fourth. There is no TRUSTED.
You believe a certificate by re-running its own recheck command and recomputing its hashes, not because it told you to. It states its own coverage as well: the files it could not parse, the dynamic imports it could not follow, so a MATCH never claims more than it proved. index snapshot and index drift do the same across time. index freshness answers whether the ground truth has moved since a certificate was minted. index verify grounds a single claim, does A depend on B, against the real graph, so a model confirms a dependency instead of trusting its memory.
The same discipline, turned on one unfamiliar repo.
The atlas maps a whole workspace. index wiki is the other altitude, the one-repo view a newcomer actually needs. Wiki generators built on a model guess at the architecture and write confident prose about structure that is not there. Repo packers dump the source without understanding it. index wiki takes the third path: it derives a multi-page, self-contained wiki for one repo from the module dependency graph index already extracts, with no model and no generated prose, then seals it so the result can be re-checked instead of trusted.
Overview, one module page per module with every edge carrying its file and line, an architecture diagram rendered from the real graph, and your own markdown joined in verbatim. One offline HTML file.
Each page is sealed with a canonical hash, the artifact is pinned to the commit it was built from, and index wiki --verify recomputes the page hashes and re-derives the graph against the current tree. The verdict is the same three words as every other certificate: MATCH, DRIFT (a page was tampered with, a claimed edge is absent from the real graph, or the repo moved off its pinned commit), or UNVERIFIABLE. The test suite keeps the known-bad fixtures, a tampered page, a hash-consistent forged edge, hostile markdown, because a verifier that cannot fail on a known-bad input is not a verifier.
$ index wiki https://github.com/org/repo --out wiki.html # shallow-clone, derive from the module graph, remove the clone $ index wiki --verify wiki.html --root ./repo MATCH pages sealed, every claimed edge present, commit pinned
Point it at a git URL and index shallow-clones the repo to a temp directory, derives the wiki, and removes the clone, so you can read a repo you have not checked out. index serve puts the same thing behind a URL: a local server that derives a repo's verified wiki the moment you request it by its forge path (GET /github.com/org/repo) and not a moment sooner. It is consent-clean by construction. Nothing is crawled or pre-indexed, every page states that the wiki derives structure and generates no prose, robots.txt disallows indexing, and it binds loopback by default.
Built from what practitioners keep asking for.
These are real comments from developers talking about agent memory and code agents, each next to what index does about it.
“Claude can make a wrong assumption and that issue will compound for hours until I check.”
The MATCH / DRIFT / UNVERIFIABLE certificate is the mid-loop check that re-grounds an agent against the real structure each turn, instead of letting a wrong assumption ride.
“A brain that only ever adds slowly poisons itself with stale facts.”
index marks a superseded dependency as DRIFT, non-destructively, with the trail kept, rather than letting a stale claim compete with the truth.
“I am done with online AI. Double down on offline AI.”
index makes no model call and no network call at all. The same repo gives the same graph and the same certificate regardless of which model ran, so it is the deterministic fixed point in a stochastic stack.
“90,948 tokens to produce a 3,408-token answer.”
index precomputes the map once and hands an agent a compact pack instead of making each sub-agent re-read the code. index bench measures the saving on your own workspace: on a 47-repo, 50 MB workspace the structural pack came back about 70 times smaller than the source it distills.
See it run.
One dependency edge, with the evidence that drew it. One certificate, with the verdict you re-run. One number, the token economy on your own code.
Watch the recorded workflow: a real sanitized workspace, three repositories, evidence-backed edges, a re-run MATCH, and a budgeted context pack. Choose the 30-second cut or the full 118-second run.
$ index graph --root . --json # every edge carries the file and line that witnesses it {"from": "cli", "to": "core", "confidence": "high", "evidence": "cli/main.py:12 import + pyproject.toml:8 manifest"} $ index check --root . verdict=MATCH findings=0 # re-run the recheck command and confirm the hashes yourself $ index bench --root . # the structural pack vs the source it reads source read 49,880,045 bytes index pack 716,288 bytes 69.6x smallerRun any of these over your own workspace and the output is the same shape, with your repos in it.
What is done. What is next.
Done and public on PyPI as index-graph (the name index was already taken): the two-layer atlas, the dependency graph across nine ecosystems, the intra-repo module graph, the architecture certificate with snapshot, drift, and freshness, the claim oracle, the router for a CLAUDE.md or AGENTS.md, the MCP protocol face, the token-economy benchmark, and the budgeted, receipt-backed context envelope (index context-envelope --budget N, source-ref-only with a re-checkable freshness root). The verified-compression discipline is now turned on prose too: index wiki derives a sealed, commit-pinned, re-checkable single-repo wiki, from a local path or a git URL, and index serve hosts it on demand. The staleness contract is shipped: index invalidate pins a tree and names exactly which artifacts a later diff invalidates, with typed reasons, and index select splits candidate files into selected and rejected with a typed index.path-selection/v1 receipt on every rejection. All of it offline, with zero dependencies. Next: typed edges that say how A connects to B (defines, re-exports, replaces).
Saying what is not done yet is part of the design. A map that overstates its coverage is worse than no map at all.
Install it. Point it at the workspace.
One command to install, one command to run. If you find repos it missed, edges it drew wrong, or roles it assigned incorrectly, those are exactly the reports that sharpen the engine.
$ pip install index-graph Successfully installed index-graph-2.9.0 $ index atlas --root . --format html --out atlas.html # the two-layer code-and-knowledge map, one self-contained offline file