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. Your coding agent curates it into the architecture you would explain to a new teammate, and the map stays open while you and your agents 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.
Free, MIT-licensed, and local. No account or backend, and groma.md itself calls no AI service: curation uses the coding agent you already work with.
Want automatic architecture diffs on your PRs? Add them to your repository.
Three steps. The scan gives you a first map; your agent turns it into your architecture.
npm i -g groma.md backlog.mdBacklog.md provides the tasks shown on the map; groma.md works without it. macOS requires Apple Silicon.
cd your-repo
groma web # browser map on http://localhost:4747On a new project, groma web walks you through project setup and scanner selection, then runs the first scan. The scan is deterministic: it turns your source into components and the relationships a scanner can detect. That first map is a starting point you can recognize and navigate, not your architecture yet.
Your coding agent turns the first scan into architecture. It reads the code, names responsibilities, merges records that belong together, and adds the relationships the scanner cannot see. Keep the map open while it works: every change it makes appears on the map. Ask your agent:
Read the current groma.md architecture with `groma agent-instructions` and `groma view --plain`. Compare it with the source code, then annotate the architecture so it reflects the code: combine records that share a responsibility, add missing overviews and relationships, and keep Backlog.md task links current. Use groma.md's CLI for architecture changes, then summarize what you changed.
Setup registers groma.md in your AGENTS.md or CLAUDE.md, so your agent knows where to start. Later scans keep what your agent wrote.
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
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 past architecture with its code. Open an earlier revision and inspect the source from that same commit, down to functions and methods.
Publish a static site. groma export ./sitecaptures the working tree with architecture, flows, and source. Add--revision <commit>for one commit or--from <base> --revision <head>for a comparison. Exports contain no task data. Scanning and hosting run separately. Static publication
The architecture lives in a groma/ folder as an Open Knowledge Format 0.2 bundle: one Markdown document per element, plus records for relationships, flows, and drafts. C4 gives the structure, OKF keeps it portable, and the documents stay readable without groma.md. Architecture Markdown contract
| Language or framework | Status |
|---|---|
| TypeScript | ✅ Available |
| JavaScript | ✅ Available |
| Angular | ✅ Available |
| React | ✅ Available |
| Vue | ✅ Available |
| C#/.NET | ✅ Available |
| Go | ✅ Available |
| Java (Maven, Gradle) | ✅ Available |
| Python | ✅ Available |
| Rust | ✅ Available |
| PHP | ✅ Available |
| Swift | ✅ Available |
| Your favorite language or framework | Submit an issue with your request |
More languages arrive as scanner plugins; add your own with groma scanner add. Each scanner's page describes what it reads. See which relationships groma.md detects.
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; curation runs in the coding agent you already use. Its 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 every pull request with the number of changed components and relationships and a link to a before and after map. Add it to your repository.
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.
TypeScript, JavaScript, Angular, React, Vue, C#/.NET, Go, Java, Python, Rust, PHP, and Swift, each through a scanner plugin; see Languages. For another language, write a scanner plugin or request one.
groma.md is an early prototype. Review the first scan before treating it as your architecture, expect rough edges, and check exports before sharing them, since they include source code. Report problems in Issues.
groma.md is free and open source under the MIT license.