Skip to content

index 2.8.0

Choose a tag to compare

View all tags
@HarperZ9 HarperZ9 released this 25 Jun 10:26
· 149 commits to main since this release
v2.8.0
a8f78d6

index 2.8.0

A workspace of many repositories has a shape, and past a handful of repos that shape lives only in someone's head. index draws it from evidence: how your repositories depend on each other, the architecture you meant, and whether the code still matches it. Deterministic, fully offline, zero dependencies. No API, no account, no model, no network.

pip install index-graph
index atlas --root /path/to/workspace --format html --out atlas.html

This is the first 2.x release published as a GitHub release, so the notes below cover the whole arc since 1.2.0: index grew from a dependency map into a re-checkable architecture brain.

What index does now

  • The two-layer atlas. index atlas renders repos and your markdown docs as one navigable, self-contained HTML map. Pan, zoom, search repos and docs together, read a doc rendered in place with clickable wiki-links. One offline file.
  • A dependency graph from real evidence. Every edge is derived from a manifest line and a source import, and carries the file and line that witnesses it, graded by confidence. Nothing enters the graph on faith. Nine ecosystems: Python, JavaScript and TypeScript, Rust, Go, Java, C#, Ruby, PHP, and C and C++. Zero runtime dependencies for any of them.
  • Module graph (internals). index internals builds the dependency graph inside one repo, where architecture actually erodes. Python is exact, read from the syntax tree; others best-effort. It reports internal cycles and what every module leans on, and it is honest about what a static scan could not verify (parse failures, dynamic imports).
  • Architecture conformance with a re-checkable certificate. Declare the layers, forbidden edges, a cycle ceiling, and required edges in .index.toml. index check measures the real graph against that and returns a certificate whose verdict is one of three words, MATCH, DRIFT, or UNVERIFIABLE, never a fourth. There is no TRUSTED. You believe it by re-running its recheck command and recomputing the hashes, not because it told you to.
  • Drift across time. index snapshot then index drift records the shape today and diffs it tomorrow: repos and edges added or removed, cycles introduced or cleared, role changes.
  • Freshness. index check --freshness stamps the certificate with a content fingerprint; later index freshness answers whether the ground truth has moved, FRESH or STALE, naming the repos that changed. The mid-loop "has anything changed since I verified?" check.
  • Claim grounding. index verify --depends "A -> B" or --exists NAME grounds a claim against the real graph and returns MATCH with the file:line, REFUTED, or UNVERIFIABLE. The anti-hallucination check: confirm a dependency instead of trusting memory.
  • The router. index router emits a deterministic, evidence-carrying workspace map for your CLAUDE.md or AGENTS.md, replacing the index plus read-first plus brief that teams maintain by hand.
  • A protocol face. index mcp serves an MCP-shaped, zero-dependency JSON-RPC stdio server, so an agent host calls index's deterministic tools by name.
  • Token economy you can reproduce. index bench measures how much smaller the structural pack is than the source it distills. On a 47-repo, ~50 MB workspace the pack came back about 70x smaller. Run it on your own workspace.

Why it is built this way

Every verdict is re-checkable by anyone holding only the artifact and the evidence, with no model in the loop. The whole tool runs offline and is agnostic to whatever produced the code it reads. Specified in docs/PROTOCOL.md.

Install and read

pip install index-graph        # Python 3.11+, zero dependencies

Fair source (FSL-1.1-MIT): source-available, converts to MIT two years after each release.

Assets 2
Loading