Groma.md
github.com/mrlesk/groma.md- Category
- Developer Tools
- Rank
- No. 1124Tools index
- Pricing
- Open Source
- Type
- TOOL
- GitHub
- 446 stars
- Latest release
- v0.7.8
- Date
About
Groma scans a repository with offline, deterministic code analysis into a first C4 architecture map. You or your coding agent then curate the map, and it is stored as plain Markdown in Git so architecture changes are reviewed in the same pull request as code. A browser view updates as files change, and later scans keep your curation.
What it does
Groma turns a codebase into a walkable C4 diagram: systems, containers and components you can zoom through in a local browser page or a terminal view. Language scanners do static analysis without calling any AI model and propose a starting map. People or coding agents then rename, merge, group and connect those pieces through the same command line, and every element is saved as its own readable document inside the repository. Saving a source file refreshes the map, and a rescan updates only the code links, leaving names, descriptions and hand-added relationships alone.
Why it's ranked here
The design answers the real failure of agent-drawn diagrams: they rot after one commit and cannot be compared. Here the architecture is versioned text with a stable identity per element, a rescan preserves curated work, and any two commits can be diffed on the map. It is MIT licensed, runs locally with no account, and agents get a dedicated instruction index plus self-describing help on every command. The scanner list is long, with twelve languages marked available and twelve more experimental, which makes it relevant beyond a single stack.
What's good
Curation survives rescans by rule: a rescan touches only the symbols an element owns. Unbuilt parts can be sketched as dashed drafts that stay drafts until a scan finds matching code and someone accepts them. Plain listings page fifty items at a time with git-style skip and count flags, which keeps agent output bounded. A static export produces a read-only site that leaves out tasks and editing controls. The scanner plugin contract validates its input strictly, rejecting duplicate files, unknown roots and cyclic hierarchies instead of guessing. Removing the tool means deleting one folder and one marked block from the agent instruction file.
Tradeoffs
Element documents are not meant to be edited by hand: the tool insists on being their only writer, so every change goes through its commands or the web editor. The command line is a TypeScript entry point run by Bun, with recent Bun and Node releases declared as required; the standalone binary on macOS needs Apple Silicon. Half the language scanners are labelled experimental. Scanner packages update from npm in the background by default, so offline claims hold only once they are installed. Loading fails outright when two elements claim the same file. The pull request comment action works on public repositories only.
How to use it well
Fits a team that already reviews code in pull requests and wants architecture changes reviewed alongside it, especially when coding agents do much of the work. Run the first scan, then have an agent curate the result with the supplied prompt, and commit the configuration so colleagues restore the same scanners. Turn off automatic updates if scans must be reproducible. Pair it with the author's task tracker to see work pinned to components. It does not generate design documentation from intent, and teams on an experimental-scanner language should expect a rougher starting map.
Technical notes+
src/cli.ts is a commander program with a bun shebang, exposed as the groma bin in package.json; subcommands cover init, web (default port 4747, retrying the next port on EADDRINUSE when interactive), export (--revision and --from for commit comparisons; --watch prints 'Coming soon.'), view, scan (--watch), instructions and agent-instructions, with scanner commands registered from src/scanner/cli.ts (setup, check, discover with --json, and a hidden refresh job). packages/scanner/src/index.ts defines the ScannerPlugin interface (scan plus optional checkReadiness, readCodeStructure, listSourceFiles) and createScanObservation, which emits schemaVersion 1, sorts output deterministically and throws on duplicate paths, unknown roots, root cycles and entry points missing their own file. docs/config.md documents one committed project configuration file with scanners, at most one work source, exclude, useGitignore and automaticUpdates (default true). docs/product-model.md states the tool is the only writer of element and draft files. package.json declares bun and node engines, workspaces for scanners and work sources, and node and bun test suites.
Observed
- License
- MIT
- Language
- TypeScript, run with Bun
- Install
- npm global package, or a standalone executable (Apple Silicon only on macOS)
- Interfaces
- CLI, local browser map, terminal map, static site export
- Storage format
- One Markdown document per element in an Open Knowledge Format bundle inside the repository
- Network use
- No AI service calls; network only to look up and download scanner packages
- Extensibility
- Language support through scanner plugins, installable from npm, Git or a local path
- Tests
- Node and Bun test suites declared in package.json
Read from README.md, package.json, src/cli.ts, docs/what-is-a-groma.md, docs/product-model.md, docs/config.md, packages/scanner/src/index.ts, src/scanner/cli.ts, LICENSE.
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.