Groma.md - Keeping humans in the loop

Groma is a living map of your system's architecture, stored inside your repository. It helps you understand unfamiliar codebases and describe where the architecture should go next.

Comment

Software is going dark

Agents can write more code, faster but humans cannot keep reviewing every generated line. The problem is no longer producing code. It is retaining understanding and being in the loop.

Groma.md is an Open-source CLI that creates real-time architecture diagrams from your codebase.

Three commands for generating a system blueprint

  1. groma init
  2. groma scan
  3. groma web And you can immediately navigate your codebase in a visual and meaningful way, add annotations and plan future changes.

Deterministic scanners

Most of the power of Groma sits in the scanners plugin system. Each codebase is one-of-a-kind: different languages, different libraries and frameworks make the understanding it a unique challenge. Groma ships with a built-in TypeScript scanner and more scanners will come in the future.

Scanners measure the topography of your codebase and find evidence about boundaries, connections and structure. This is fast, offline and deterministic so each scan will produce the same results.

Groma is meant for humans and AI Agents

There is no dedicated MCP, the only interface for using Groma is the CLI and the Web interface. Humans and Agents share the same commands and instructions. Both can add meaning and intent on top of the data that the scanners already provide via plain text CLI commands. Each new scan keeps your existing annotations and only provides evidence of changes.

Groma was complex to build but not to use

Finding the right information in a large codebase is a very complex operation. Sure, agents can do this very easily but you cannot run agents continuously to try to understand your files also because of latency limitations. Groma uses a very similar approach to the Cognitive Complexity code analyzers: it tries to find true meaning behind the files the same way a human would do. It looks for imports, exports, complex functions, simple functions and many more signals that are put together to create the components graph of your codebase.

The future: an open blueprint ecosystem

My goal is that scanners, plugins and blueprint plans can be shared via the Groma website and the community can contribute with open-source scanners for each of the languages and frameworks that exist.

Built With

Share this project:

Updates