Groma scans your code, draws it as a C4 architecture map, and keeps that map open while you and your coding 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, backend, or AI service required.

Install

npm i -g groma.md backlog.md
cd your-repo
groma init

groma init sets up the repository and offers a first scan. Then open the map:

groma web     # browser map on http://localhost:4747
groma view    # terminal map

Backlog.md provides the tasks shown on the map; Groma works without it. macOS requires Apple Silicon.

Use it with your agent

The first scan gives you components and detected relationships. Your coding agent turns them into architecture: it reads the code, names responsibilities, merges records that belong together, and adds the relationships the scanner cannot see. Always do this after the first scan.

Agents use the same CLI as people. groma init registers Groma in your AGENTS.md or CLAUDE.md, groma agent-instructions prints the curation guide, and every command explains itself through --help. Ask your agent:

Read the current Groma 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's CLI for architecture changes, then summarize what you changed.

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 architecture record that owns this file

Later scans keep what your agent wrote. Curation guide

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
• A terminal map with the same architecture, scanning and watching from your shell. Terminal 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 an interactive site. groma export ./site writes a standalone map with flows, tasks, diffs, and source; --watch regenerates it as the repository changes. 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, plus records for relationships, flows, and drafts. C4 gives the structure, OKF keeps it portable, and the documents stay readable without Groma. Architecture Markdown contract

Languages

| Language or framework | Status | | --- | --- | | TypeScript | ✅ Available | | C#/.NET | ⏳ Coming soon | | Java | ⏳ Coming soon | | Your favorite language or framework | Submit an issue with your request |

More languages arrive as scanner plugins; add your own with groma scanner add. See TypeScript support for what the scanner reads and which relationships it detects.

Experimental

Groma 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 can include source code and task details. Report problems in Issues.

Documentation and contributing

• Documentation index
• Product model
• Contributing guide
• Groma manifesto

License

Groma is free and open source under the MIT license.