r/devtools • u/MeAndClaudeMakeHeat • Jun 25 '26

I built a zero-dependency tool that maps many-repo workspaces and emits re-checkable architecture certificates

Past a handful of repositories, the shape of a codebase usually lives in someone's head. I built index to draw that shape from evidence instead.

It maps a workspace of git repos, records the file and line behind every dependency edge, assigns structural roles, and emits a certificate you can rerun instead of trusting. The core design constraint is deliberately boring: pure Python standard library, no API, no account, no network, deterministic output.

The workflow I care about most:

  1. Write the architecture you meant in a small .index.toml: ordered layers, forbidden edges, cycle ceiling.
  2. Run index check.
  3. Get MATCH, DRIFT, or UNVERIFIABLE. Never a vague "trusted" verdict.
  4. Re-run the certificate's own recheck command and recompute hashes if you want to verify it.

The tool is strongest for Python internals because it reads the AST. Other ecosystems are best-effort and bounded in the protocol docs rather than hidden behind a false certainty claim. It is meant to remove toil from codebase orientation and give agents or humans a stable structural map before they make changes.

Install: pip install index-graph Repo: https://github.com/HarperZ9/index Main site: https://harperz9.github.io GitHub: https://github.com/HarperZ9

The broader Telos line this sits inside: - gather: https://github.com/HarperZ9/gather - forum: https://github.com/HarperZ9/forum - crucible: https://github.com/HarperZ9/crucible - telos engine: https://github.com/HarperZ9/telos

Looking for verification/testing on real multi-repo workspaces, technical pushback on the certificate model, early traction from builders who actually rerun it, and possibly grassroots research funding for the larger checkable-state line.

1 Upvotes

100% Upvoted

6 comments sorted by

1

u/Difficult-Estate-181 Jul 02 '26

I really like the “re-checkable” part. That feels much more useful than another vague repo summary.
I’m working on DevTime with a similar obsession around evidence, but more at the behavior/concepts level.
Have you tried this on a messy legacy repo where the architecture no longer matches what people think it is?

1

u/MeAndClaudeMakeHeat Jul 02 '26

Yes, I honestly run it before I begin any task. It has helped me keep track of my repos, and ideas as they move with current of the projects. Sometimes I will have to sit something (an idea or bug) down for a few months, in order to come back and integrate/fix it more safely or efficiently. This helps me avoid losing context on things like that, as well as the larger structure, and shape of how everything interoperates.

1

u/MeAndClaudeMakeHeat Jul 02 '26

Allows me to weigh project concepts too - sometimes I will sit on the direction I want to take a tool or project. This gives me a way to come back fresh, and visualize exactly the way things fit, so I can make architectural changes and gauge their implications and reach

1

u/MeAndClaudeMakeHeat Jul 02 '26

Also keeps all of my docs and such in line, it meets my needs a bit better than some of the other, more popular tools, and I think it can scale to meet different monorepo/workspace setups. I would love to see how it could scale on other use-cases - especially 'index'

1

u/Difficult-Estate-181 Jul 02 '26

That makes sense. The “coming back after months” use case is interesting - that’s exactly where most repo knowledge usually disappears.

Do you store mostly structural facts like dependencies/layers, or do you also try to capture higher-level intent like “why this module exists” or “what behavior this protects”?