Groma.md: Stay in control of your architecture as AI agents write code

Your architecture, alive. A live C4 map of your repository, stored as OKF Markdown in Git.

groma.md scans your code into a first C4 architecture map. You can curate it into the architecture you would explain to a new teammate, either yourself or with your coding agent. The map stays open while you work. Save a file and the map updates. Work on a Backlog.md task and it appears pinned to the components it touches. Everything is plain Markdown in your repository, so architecture changes are reviewed in the same pull request as the code.

Want automatic architecture diffs on your PRs? Add them to your repository.

groma.md is free, MIT-licensed, and runs locally with no account or backend. Scans run offline once the scanners are installed, use deterministic code analysis, and call no AI service. You can use groma.md entirely without AI.

Get started

Three steps. Scan your code, then review and curate the map yourself or with your coding agent.

1. Install

        npm i -g groma.md backlog.md
      

Backlog.md provides the tasks shown on the map; groma.md works without it. To run without Node.js, download the standalone executable for your platform. macOS requires Apple Silicon.

2. Scan

        cd your-repo
groma web     # scans and opens the browser map on http://localhost:4747
      

groma web scans your repository automatically at startup and opens the map. On a new project, it first walks you through project setup and scanner selection in your browser.

3. Review and curate

The first scan gives you a starting map from what the scanners can detect. To turn it into your architecture, click Copy prompt on the map's first-scan notice and paste it into your coding agent:

        Curate this repository's architecture with Groma. Run groma agent-instructions and follow its curation workflow. Describe the architecture as it exists today; do not change application code.
      

You can also curate the map yourself with groma.md's commands (groma instructions and --help). Setup registers groma.md in your AGENTS.md or CLAUDE.md, so your agent knows where to start. Keep the map open while you work: changes appear live, and later scans keep your curation.

Work with your agent

Agents use the same CLI as people. groma agent-instructions prints an index of task-focused agent guides, and every command explains itself through --help. Any file resolves to the architecture that owns it, so an agent can start from the code it just changed:

        groma view src/orders.ts    # the owner of this file and its relationships
      

Agent guides

What you get

• A browser map you can walk. Zoom from systems to containers to components. Select anything to read what it does and open the source behind it. Browser guide

• Live updates. Saving code refreshes source evidence and detected relationships; new files become new components.

• Relationships and flows. Describe how components interact, then chain relationships into named flows readers can step through. Relationships and flows

• Drafts. Sketch systems, containers, and components before they exist. They appear dashed beside the real ones until a scan matches their code and you accept them. Draft lifecycle

• See work across the architecture. Backlog.md tasks pin where people and agents are working; select one to highlight the components it touches and inspect its changes without leaving the map. Task links

• Explore history and compare commits. Open any earlier revision with its source, or compare two commits (or uncommitted changes) on the map to see added, modified, and removed components and relationships.

• Publish a static site. groma export ./site exports a standalone, read-only map of your working tree, a commit, or a commit comparison that you can host anywhere. Static publication

Plain Markdown, C4, OKF

The architecture lives in a groma/ folder as an Open Knowledge Format 0.2 bundle: one Markdown document per element (with its relationships), plus records for flows and drafts. C4 gives the structure, OKF keeps it portable, and the documents stay readable without groma.md. Architecture Markdown contract

Languages

More languages arrive as scanner plugins; add your own with groma plugin add. Each scanner's page describes what it reads. See which relationships groma.md detects.

FAQ

Why can't I just ask my agent to draw an architecture diagram?

You can, and the diagram will be right on the day it is drawn. After that it is a static picture: it falls behind with every commit, and asking again gives you a new drawing that you cannot compare with the old one.

groma.md keeps the architecture live. Your agent's curation is saved as Markdown in your repository, and the map follows the code from there: saving a file updates it, later scans keep what your agent wrote, and you can compare any two commits, or your uncommitted changes, to see how the architecture changed.

Does groma.md send my code anywhere?

No. groma.md runs on your machine and needs no account. It reads your repository, writes Markdown into it, and serves the map on localhost. It calls no AI service. You can curate the map yourself; if you use a coding agent, check how that agent handles your code. groma.md's only network requests look up and download the scanner packages you install.

Won't the next scan overwrite what my agent wrote?

No. Once a document exists, scans refresh only its code references: the symbols in the files it owns. Names, descriptions, groups, the files your agent combined, and the relationships it added stay as written. New files arrive as new components for your agent to place.

Can I see architecture changes in pull requests?

Yes. The architecture is Markdown in the same repository, so its changes are part of the pull request. On public repositories, the groma.md GitHub Action comments on pull requests with change counts and a link to an interactive before-and-after map. See it on a pull request or add it to your repository.

What happens if I stop using groma.md?

Nothing breaks. The architecture stays in your repository as ordinary Markdown in the Open Knowledge Format: one document per element, linked to each other, readable on GitHub or in any editor. To remove groma.md, delete the groma/ folder and the block between <!-- groma:start --> and <!-- groma:end --> in your AGENTS.md or CLAUDE.md.

Which languages does it support?

Each language or framework runs through a scanner plugin; see Languages for the current list. For another language, write a scanner plugin or request one.

Documentation and contributing

• Documentation index

• Product model

• Contributing guide

• groma.md manifesto

• What is a groma?

License

groma.md is free and open source under the MIT license.