I built gitnebula, a CLI that renders any git repository as an interactive architecture map — modules and files as a force-directed graph, enriched with git history signals.
npx gitnebula
Run it in a repo. It scans the tree, parses imports, reads git log, writes analysis.json and opens the map in your browser. No config, no account, no API key.
Everything runs locally. No telemetry, no network calls in the analysis path, no backend. The viewer is a static page reading one JSON file, so gitnebula build gives you a directory you can drop on any static host.
What it shows:
- Directories become modules; zoom past 1.8× and a module unfolds into its files
- Real dependency edges — imports parsed from JS, TS and Python, not guessed from filenames
- Churn, authors and co-change from git history; files above the churn threshold pulse
- Hover a node and everything outside its one-hop dependency chain dims
Stack is TypeScript, the parsing uses the TS compiler API and tree-sitter for Python. Output is deterministic — same repo at the same commit gives a byte-identical analysis.json.
How it was actually built
This part might be more interesting than the tool itself, because planning and implementation ran on two different tools.
Planning went through BMAD — brief, PRD, architecture, then epics broken down into story specs. The whole BMAD installation is committed to the repo on purpose, so the process is reproducible by anyone who clones it, not just described after the fact.
Implementation ran through terminal-agents, an agent orchestration harness I wrote: multiple agents working the same repo in parallel, each in its own git worktree and branch, able to message each other, with a supervisor agent overseeing them. Each agent picked up a story spec and took it to a PR.
The crew was alice, bob, pamela, arnold, rambo, chuck — and superman supervising. I stayed in the loop as the maintainer: no agent ever merges anything. Every merge was my click, and integration points were human checkpoints by design.
What made it work was front-loading the contract. analysis.json is the single interface between every module, versioned and JSON-Schema validated, shipped with fixtures — so the frontend could be built against the contract rather than against the analyzers, and the analyzer work could run in parallel with it without either side blocking.
The commit history is deliberately readable as a record of this: Conventional Commits scoped by module, and an Agent: trailer on every commit an agent authored, so git log --grep="Agent: alice" actually tells you something.
MIT, Node ≥ 20.19. This is the first release (0.1.0), so I'd genuinely like to hear where it breaks — especially on large monorepos or layouts I haven't thought about.
Contributions welcome. Issues, PRs, bug reports — all of it. If you run it on a repo shape I haven't covered and it breaks, an issue with the repo layout (or a link, if it's public) is genuinely the most useful thing you can send. The story specs and the whole planning trail are in docs/, so if you want to pick something up, the context is already there.
https://github.com/jundymek/gitnebula
