v0.6.0

Highlights

• Review architecture changes: the comparison hierarchy lists changed components and relationships with counts. Switch between Changes and All to keep the review focused or see the full architecture.
• Focus on the changes: unchanged map elements fade, and the camera fits the changed components when a comparison opens.
• Readable source diffs: source readers use opaque backgrounds and let you step between changed files without returning to the file list.

Web map

• Change navigation: filter Added, Modified and Removed changes, then step through them with the previous/next controls or J/K.
• Modified components: details explain which fields, files and relationships changed. Before/after text highlights rewritten descriptions.
• Status colors: map marks and code diffs share change colors across Light, Dark and Blueprint. Blueprint uses lime for additions.

Fixes

• Embedding: the map preserves inset= when updating its URL, so the header and panels stay inside the host page's frame.
• Layers: live map updates finish while the view is orbiting.

Scanners

• Angular 0.2.1: imported output providers outside the selected files no longer contribute callback evidence.
• Vue 0.2.1: excluded callback providers and receivers no longer contribute evidence or cause an unknown-file scan error. Callbacks between selected files remain available.
• Scanner patch release: these packages were published separately on September 26, 2026, after the initial Groma 0.6.0 release, through PR #111. Other scanner versions are unchanged.
• Updating existing projects: run groma scanner update angular or groma scanner update vue for the scanners your project uses. Both patches work with Groma 0.6.0; no CLI update is needed.

Full Changelog: v0.5.0...v0.6.0

v0.5.0

Highlights

• Time machine: browse any commit from the header, compare two revisions on the map with component, relationship and source changes, and export a working tree, a commit or a comparison as a static site.
• Visible file selection: each scanner declares include and exclude lists in groma/scanners.json, beside your own global exclude and a useGitignore switch. Groma lists the repository once and hands each scanner its files.
• Scanners tested on public projects: all 12 official scanners were run against ten public repositories each and fixed where they failed or reported wrong facts. Many fresh-checkout scans that failed now complete.
• Automatic application containers: entry points reported by every official scanner become containers on the first scan. Repeat scans keep your curation.

Scanners

• Go: reports gorilla/mux, httprouter and Prometheus routes; large generated files scan in seconds instead of minutes.
• TypeScript: workspace packages resolve to source without node_modules; a missing extended config warns instead of failing; large repositories scan 3 to 9 times faster.
• C#: loads each project once with Directory.Build.props and C# 14 extension blocks; seven repositories that failed now scan.
• HTTP evidence: more clients and routes, including Retrofit, OkHttp, WebClient, Undici, Axios, IHttpClientFactory, Angular httpResource, Rocket and Axum.
• Express, Koa and Hono: middleware no longer blocks later routes or loses route order.
• Symlinks: a symlinked source file is scanned once.

Web map

• Motion: map changes animate between updates, drags glide to a stop, and touch screens zoom with a two-finger pinch.
• Speed: large maps and comparisons lay out in about 2 s instead of 16 s, view switches no longer rebuild the map, and buildings pack tighter.
• Safari: pans start without a stutter, zooming out and flow mode no longer freeze, and the map stays sharp after a zoom.
• Embedding: a host page can switch the embedded map to another view without reloading, and inset= keeps the map's header and panels inside the page's frame.
• First scan: the map and groma scan suggest asking your coding agent to curate the result.

Fixes

• groma export continues when a scanner cannot outline its files.
• Revision history and commit export work on Windows.
• Comparing commits where an element changed kind no longer crashes; comparisons always run from older to newer.
• The project title plate stays readable on small and empty maps.

Upgrading

Official scanners are now 0.2.0 and require groma.md 0.5.0. Scanner entries from 0.4.0 have no include list and are rejected. Delete groma/scanners.json, run groma scanner setup, then add back any exclude patterns of your own.

v0.4.0

Highlights

• New scanners: official PHP, JavaScript and Swift scanners bring Groma to 12 languages and frameworks. Swift runs on macOS, Linux and Windows (TASK-401, TASK-418, TASK-431, TASK-443).
• Scan fresh checkouts: official scanners carry their own analysis tools, so a scan needs no project dependencies or language SDKs. Java reads Gradle projects without running Gradle (TASK-396, TASK-417).
• HTTP relationships: Groma connects a request to its server endpoint when the method and route identify one destination. Uncertain requests stay unresolved. Every official scanner except Swift reports them (TASK-416).
• Source outlines: every official scanner lists the types, functions and methods behind a component (TASK-410).
• Duplicate logic in every language: groma lint and Project review compare named operations across all official language scanners, with less noise from callbacks and small bodies (TASK-395, TASK-423, TASK-424).
• Share your map: groma export --url adds social previews with Light, Dark and Blueprint covers, generated without a browser. Published maps take their theme from /architecture/{theme}/ (TASK-453, TASK-454, TASK-456).

Behavior changes

• Conservative boundaries: a first scan creates one project-named system only when none is declared. Source folders and scanner project groups no longer become containers; components without an identifiable container appear in an Unidentified container group (TASK-441).
• Multi-file components: Angular classes keep their templates and styles, Vue components their external files, and C# partial classes form one component. Curated ownership stays authoritative (TASK-397, TASK-398, TASK-399, TASK-400).
• TypeScript placement: imported helpers stay inside their application, and file or symbol names no longer decide placement (TASK-403, TASK-407).
• Web startup: the map opens once, after the first scan finishes. Startup names the scanners still running and reports actual progress (TASK-429, TASK-446, TASK-470, TASK-472).
• Paged CLI output: groma view --plain prints the context level; pass an element ID to drill down. Long lists stop at 50 items and print the command for the next page (--max-count, --skip, --count) (TASK-412, TASK-420).
• File lookups: groma view <file> answers with the owner and the file's relationships, or explains why the file has no owner (TASK-413, TASK-425).
• Agent guides: groma agent-instructions prints an index of five task-focused guides; add a guide name to read one (TASK-415).
• Quieter scans: diagnostics are summarized per scanner and code, groma scanner discover prints one line per technology, and curated multi-file components no longer warn (TASK-411, TASK-422, TASK-428).
• Scanner compatibility: official scanners declare a minimum Groma version, so they keep working on newer stable releases (TASK-474).
• Terminal map: setup offers only the browser map. groma view remains available (TASK-468).

Improvements

• Map reading: filter by C4 element type, see a selected component's neighbors highlighted, and read larger system, container and group titles. Relationship lists show each pair once (TASK-402, TASK-419, TASK-437, TASK-438, TASK-466, TASK-467).
• Live Backlog work: To Do tasks appear as drafts, pins travel between touched components, and active tasks highlight everything they touched. Task details update in place and show the plan first (TASK-432, TASK-434, TASK-435, TASK-440, TASK-442).
• Curation: rename element IDs, detach files from a component, combine systems, and move containers between systems (TASK-421, TASK-426, TASK-427).
• Scanner setup: compact scanner choices with searchable matching files, in setup and in Settings. An empty project opens with a Set up scanners action (TASK-429, TASK-433, TASK-448, TASK-449).
• Web header: shows the project title instead of the first system's (TASK-414).

Fixes

• Rust workspaces: shared module paths and implicit workspace members now load, and scanning no longer needs Cargo dependencies (TASK-444).
• Setup retries: a retry after a failed installation keeps the scanners already installed and continues with the rest (TASK-436).
• Excluded sources: a scanner whose sources are all excluded is skipped instead of failing (TASK-448).
• Readable titles: scanned components no longer show generated IDs as titles, and repeated callback relationships are combined (TASK-404).
• Map rendering: actor and external-system islands fit their content, and arrows attach to visible shapes in 2D (TASK-409).
• Selection: clicking the map with a component selected clears the selection before selecting the system underneath (TASK-469).
• Safari: zooming stays smooth after panning (TASK-462).
• Large exports: static export no longer terminates on projects with many Backlog tasks (TASK-473).

Full Changelog: v0.3.3...v0.4.0

v0.3.3

Fixes

• Project review: expand duplicate comparisons below each row, with compact filters and no enlarge button (TASK-392).
• Scanner updates: update npm scanners from the CLI or web without entering an exact version (TASK-393).

Improvements

• Plugin settings: show available upgrades beside the installed version, with an Update button (TASK-394).

Full Changelog: v0.3.2...v0.3.3

v0.3.2

Fixes

• Live scans: watch source files before the first scan so edits made during startup are kept (TASK-391).
• Scanner failures: one failed scanner no longer blocks the others. Empty TypeScript projects and inactive framework projects no longer stop a scan (TASK-380, TASK-382).
• C# scanning: generated files outside the project no longer block source analysis (TASK-383).

Improvements

• Python scanner: scan Python projects for files, classes, and functions with the new official plugin. Requires Python 3.11 or newer; call targets remain unresolved (TASK-390).
• Project review: review possible duplicate code from the toolbar. Open plugin settings from the Settings menu (TASK-377, TASK-384, TASK-385).
• Map controls: use the floating view tabs and smooth transitions between Iso, 2D, and Layers (TASK-386–TASK-389).
• Release builds: run independent build steps in parallel (TASK-379).

Full Changelog: v0.3.1...v0.3.2

v0.3.1

Fixes

• Open saved maps: fixed overlapping connection exits that could prevent cloned architecture from opening (TASK-376).
• Connection spacing: map placement and routing now share spacing rules based on connection demand, giving crowded maps more room (TASK-378).
• Visible version: startup, setup and error screens now show the running Groma version (TASK-376).

Full Changelog: v0.3.0...v0.3.1

v0.3.0

Highlights

• Scanner plugins: official TypeScript, React, Vue, Angular, Java, C#, Go and Rust scanners, with support for third-party packages and pinned Git sources (TASK-326, TASK-360).
• Scanner settings: install, update and remove plugins from the terminal or browser. See recommendations, missing team selections and actionable errors in one place (TASK-365, TASK-372).
• Clearer maps: switch between Iso, 2D and Layers without losing unsaved edits. Surface labels now sit outside their boundaries (TASK-328, TASK-166).

Behavior changes

• TypeScript is optional: install it through scanner settings. Saved architecture remains available without installed scanners (TASK-362, TASK-364).
• Scan nested projects: scanners find supported applications and libraries from the repository root (TASK-363).
• Exact team versions: restore committed scanner selections; updates happen only when explicitly requested (TASK-360, TASK-361).
• Static export: reads saved architecture, writes one snapshot and exits. Scan first to refresh source evidence (TASK-357).
• Remove empty components: scanned components can be removed after a scan clears their deleted source references (TASK-374).

Full Changelog: v0.2.0...v0.3.0

v0.2.0

Highlights

• Duplicated-logic findings: a TypeScript scan reports named operations that look like copies — exact clones after renaming locals, and near-duplicates with the tokens that differ. Findings appear under Code in How it's built, in the scan listing, and in the terminal details pane. They are review questions, not map relationships, and they are not written into the architecture Markdown (TASK-321)

Behavior changes

• Empty projects invite TypeScript: a live map with no components no longer offers a Draft system form. Web, terminal, and plain output say no component was found, to go build something fun, and that Groma.md only supports TypeScript. The first scanned component still replaces that invitation without a reload (TASK-322)
• An empty live map does not draft a system. The overlay and the terminal empty world use the shared TypeScript invitation instead of a system editor or a draft-system command (TASK-322)
• A source file occupies the web details Back slot. During a flow visit, Back to flow is hidden while a file is open and returns when the file is closed; the flow reader still offers return to the originating component (TASK-323)
• One Back while reading source: opening a file from a flow endpoint shows Back to the component only. Leaving the file restores Back to flow with the same scenario and origin return (TASK-323)

Full Changelog: v0.1.0...v0.2.0

v0.1.0

Welcome to the world, Groma.md

Your architecture, alive. Groma scans your repository, 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.

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

What is in v0.1.0

Maps

• 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.
• A terminal map with the same architecture, scanning and watching from your shell.
• Live updates: saving code refreshes source evidence and detected relationships, and new files become new components.
• History: open the architecture as it was at an earlier commit.
• Static export: groma export ./site publishes a read-only map that needs no server.

Architecture as Markdown

• 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. Readable without Groma, diffable in Git.
• Relationships and flows: describe how components interact, then chain relationships into named flows readers can step through.
• 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.
• People and external systems, groups, and hand-written overviews survive every rescan.

Scanning

• TypeScript scanner built in, powered by the native TypeScript 7 compiler. It reads your .ts and .tsx files as Git sees them, records exported symbols and how operations are wired between files, and Groma derives the relationships between the components that own them. No annotations, IDs, or comments needed in application code.
• Scanner plugins: groma scanner manages additional scanners per project. C#/.NET and Java are next; request your language.

Tasks in context

• Backlog.md tasks are pinned where they last touched the architecture, with acceptance criteria and diffs one click away.

Built for agents

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

Install

• npm: npm i -g groma.md (Node 20.19 or later; a platform package supplies the binary).
• Standalone binaries for Linux x64 and arm64, macOS Apple Silicon, and Windows x64 and arm64 are attached below, with SHA256SUMS. Each is a single file with the scanner, the TypeScript worker, and the browser renderer embedded; no Node, Bun, or node_modules needed.

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 · Manifesto · Contributing

Test release on NPM

This is just a test to check if the CI/CD pipeline works end to end