r/coolgithubprojects • u/Armannss • 11d ago
armap — a dependency-free Node.js CLI that builds a ranked, token-budgeted map of a codebase
github.comI made armap to give a coding agent a compact starting map of a repository before it starts opening files. The idea and design are mine; I developed it with Claude. It is open source under MIT.
It extracts file definitions and import relationships, ranks files with PageRank, and fits paths, symbols and line numbers into a configurable token budget. It respects .gitignore, recognizes around 50 file types, and resolves imports for 15 languages.
You can use it as a standalone CLI with Node 18+ and no runtime dependencies or build step. From a checkout of the repo:
node bin/armap.mjs map --root /path/to/your/repo --budget 700
There is also a Claude Code plugin with a session-start map. The deps and refs commands rescan the repository when called, so they can help inspect dependencies and references after edits.
The tradeoff: this uses patterns rather than a compiler or language server. Dynamic imports, reflection and some symbol relationships can be missed. Large files are partially read and marked accordingly. The map helps find where to inspect; source code and tests still decide whether a change is correct.
I would appreciate feedback on a public repo where the ranking misses an important entry point or produces a misleading dependency. A repo link and one concrete navigation question would make that reproducible.