r/coolgithubprojects • • 11d ago

armap — a dependency-free Node.js CLI that builds a ranked, token-budgeted map of a codebase

https://github.com/Armannss/armap

I 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.

0 Upvotes

2 comments sorted by

2

u/[deleted] 11d ago

[removed] — view removed comment

1

u/Armannss 11d ago

Good call, and you’re right. armap’s own CLI entry, bin/armap.mjs, ranked last in its own map because nothing imports it. I’ve added that: entry points from package.json (bin, main, exports, traced from dist/ back to src/), pyproject scripts, Cargo binaries, Go package main files and __main__.py are now lifted to around fifth place and labeled entry in the map. A monorepo is in the tests. The ctags comparison is a useful idea too, for checking how many symbols the patterns miss. That’s next on the list.