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

Groma.md, an MIT-licensed tool from developer MrLesk, scans a code repository into a live C4 architecture map stored as OKF Markdown in Git, letting coding agents curate the map alongside the code. The tool runs locally with no account or backend, uses deterministic code analysis, calls no AI service, and can be used entirely without AI; it installs via `npm i -g groma.md backlog.md` and `groma web` serves the map at http://localhost:4747. Because the map is plain Markdown in the repository, architecture changes are reviewed in the same pull request as the code, and a companion GitHub Action adds automatic architecture diffs to PRs.

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 https://c4model.com 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 https://github.com/MrLesk/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. https://github.com/MrLesk/groma.md-action/pull/4 Note 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. Three steps. Scan your code, then review and curate the map yourself or with your coding agent. 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 https://github.com/MrLesk/groma.md/releases/latest for your platform. macOS requires Apple Silicon. 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. 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. 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 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 https://github.com/MrLesk/groma.md/blob/main/docs/viewers/web/index.md 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 https://github.com/MrLesk/groma.md/blob/main/docs/component-markdown.md 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 https://github.com/MrLesk/groma.md/blob/main/docs/product-model.md drafts 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 https://github.com/MrLesk/groma.md/blob/main/docs/agent-instructions/backlog.md 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 https://github.com/MrLesk/groma.md/blob/main/docs/viewers/web/index.md static-publication The architecture lives in a groma/ folder as an Open Knowledge Format 0.2 https://github.com/GoogleCloudPlatform/open-knowledge-format/blob/main/SPEC.md 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 https://github.com/MrLesk/groma.md/blob/main/docs/component-markdown.md | Language or framework | Status | |---|---| | TypeScript https://github.com/MrLesk/groma.md/blob/main/docs/scanners/typescript/index.md | ✅ Available | | JavaScript https://github.com/MrLesk/groma.md/blob/main/docs/scanners/javascript/index.md | ✅ Available | | Angular https://github.com/MrLesk/groma.md/blob/main/docs/scanners/angular/index.md | ✅ Available | | React https://github.com/MrLesk/groma.md/blob/main/docs/scanners/react/index.md | ✅ Available | | Vue https://github.com/MrLesk/groma.md/blob/main/docs/scanners/vue/index.md | ✅ Available | | C /.NET https://github.com/MrLesk/groma.md/blob/main/docs/scanners/dotnet-csharp/index.md | ✅ Available | | Go https://github.com/MrLesk/groma.md/blob/main/docs/scanners/go/index.md | ✅ Available | | Java Maven, Gradle https://github.com/MrLesk/groma.md/blob/main/docs/scanners/java/index.md | ✅ Available | | Python https://github.com/MrLesk/groma.md/blob/main/docs/scanners/python/index.md | ✅ Available | | Rust https://github.com/MrLesk/groma.md/blob/main/docs/scanners/rust/index.md | ✅ Available | | PHP https://github.com/MrLesk/groma.md/blob/main/docs/scanners/php/index.md | ✅ Available | | Swift https://github.com/MrLesk/groma.md/blob/main/docs/scanners/swift/index.md | ✅ Available | | C https://github.com/MrLesk/groma.md/blob/main/docs/scanners/c/index.md | 🧪 Experimental | | C++ https://github.com/MrLesk/groma.md/blob/main/docs/scanners/cpp/index.md | 🧪 Experimental | | Kotlin https://github.com/MrLesk/groma.md/blob/main/docs/scanners/kotlin/index.md | 🧪 Experimental | | Ruby / Rails https://github.com/MrLesk/groma.md/blob/main/docs/scanners/ruby/index.md | 🧪 Experimental | | Elixir / Phoenix / Ash https://github.com/MrLesk/groma.md/blob/main/docs/scanners/elixir/index.md | 🧪 Experimental | | Scala 3 https://github.com/MrLesk/groma.md/blob/main/docs/scanners/scala/index.md | 🧪 Experimental | | Dart Flutter and Serverpod source https://github.com/MrLesk/groma.md/blob/main/docs/scanners/dart/index.md | 🧪 Experimental | | R https://github.com/MrLesk/groma.md/blob/main/docs/scanners/r/index.md | 🧪 Experimental | | Ada https://github.com/MrLesk/groma.md/blob/main/docs/scanners/ada/index.md | 🧪 Experimental | | Mojo https://github.com/MrLesk/groma.md/blob/main/docs/scanners/mojo/index.md | 🧪 Experimental | | MQL5 https://github.com/MrLesk/groma.md/blob/main/docs/scanners/mql5/index.md | 🧪 Experimental | | COBOL IBM fixed format https://github.com/MrLesk/groma.md/blob/main/docs/scanners/cobol/index.md | 🧪 Experimental | | Assembly NASM x86-64, Linux ELF64 https://github.com/MrLesk/groma.md/blob/main/docs/scanners/nasm/index.md | 🧪 Experimental | | Your favorite language or framework | Submit an issue with your request https://github.com/MrLesk/Groma.md/issues | More languages arrive as scanner plugins https://github.com/MrLesk/groma.md/blob/main/docs/scanners/creating-a-plugin.md ; add your own with groma plugin add . Each scanner's page describes what it reads. See which relationships groma.md detects https://github.com/MrLesk/groma.md/blob/main/docs/relationship-inference.md current-inference-rule . 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. 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. 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. 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 https://github.com/MrLesk/groma.md-action/pull/4 or add it to your repository https://github.com/MrLesk/groma.md-action add-pr-comparisons . 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. Each language or framework runs through a scanner plugin; see Languages languages for the current list. For another language, write a scanner plugin https://github.com/MrLesk/groma.md/blob/main/docs/scanners/creating-a-plugin.md or request one https://github.com/MrLesk/Groma.md/issues . groma.md is free and open source under the MIT license https://github.com/MrLesk/groma.md/blob/main/LICENSE .