stackmapstackmap
Install

DocsGet started

Quick start

Install the skill, ask your coding agent for a diagram, and open the one HTML file it delivers.

  1. Step 1: Install the skill into your agent

    npx skills add omsimos/stackmap

    It installs into Claude Code, Cursor, Codex and the other agents that skills supports.

  2. Step 2: Ask for a diagram

    Make an architecture diagram of this repository, backed by evidence from the code.

    The agent writes .stackmap/<name>/diagram.json, validates it, repairs what the diagnostics name, and delivers .stackmap/<name>/diagram.html.

  3. Step 3: Open the file

    Open diagram.html in any browser. There is no server, no account and nothing to install. To change the diagram, ask again: the agent edits the JSON and delivers it again. The viewer itself is read-only.

What the agent writes

One small typed JSON file. The agent names the nodes, connections, groups and views; stackmap validates it and lays it out. There are no coordinates to write.

file:///…/.stackmap/bookshop/diagram.html
.stackmap/bookshop/diagram.json27 lines
{  "$schema": "https://unpkg.com/@omsimos/stackmap@0.4.0/dist/stackmap.schema.json",  "kind": "architecture",  "title": "Bookshop",  "direction": "DOWN",  "groups": [{ "id": "data", "label": "Data tier" }],  "nodes": [    {      "id": "api",      "type": "service",      "card": { "title": "shop-api", "subtitle": "REST API" },      "evidence": [{ "file": "services/api/src/server.ts", "line": 12 }]    },    {      "id": "db",      "type": "database",      "group": "data",      "card": {        "title": "Orders DB",        "subtitle": "PostgreSQL",        "brand": "postgresql"      }    }  ],  "edges": [{ "id": "api-db", "from": "api", "to": "db" }],  "views": [{ "id": "state", "label": "State", "nodes": ["db"] }]}
Point at a node in the JSON, or at its card, to find the other.

Nodes

Nine types set the colour, and lifecycles have seven state types of their own. Cards can add rows, stats, a footer, a link and one of 146 Simple Icons logos.

ClientServiceGatewayDatabaseCacheQueueStorageExternalSecurity

Connections

Plain for a call, async for queues and events, return for a reply or a roll back, with a tone for the main path, security crossings and failure paths.

No coordinates

stackmap lays everything out: ELK for architecture and dataflow, and its own layout for lanes and sequences. The same JSON always gives the same file.

When something is wrong

validate names each problem with a code, where it is (a JSON pointer) and the fixes it allows. The agent repairs only what is named and runs it again; deliver writes the file once nothing is wrong.

~/commerce-api
$ stackmap validate .stackmap/commerce-api/diagram.jsonerror  refs/unknown-node  /edges/6/to  Unknown node "orders-db"  fix: use "orders"  fix: add node "orders-db" or remove the edge✗ 1 error$ stackmap validate .stackmap/commerce-api/diagram.json✓ valid: no diagnostics$ stackmap deliver .stackmap/commerce-api/diagram.jsondelivered .stackmap/commerce-api/diagram.html · sha256 0a6f2ce5f590… · 500770 bytes

Warnings never block delivery. The exit code tells the agent which case it is in: 0 valid, 1 the diagram has errors, 2 a usage, file or internal error. Diagnostics, in full.

Next steps

The viewerSelect, trace, route, find, present and share what the file shows.Diagram kindsFive kinds, each with its own layout. Pick the one that answers the question.Schema referenceEvery field of diagram.json, with a real example beside each part.ExamplesSixteen diagrams, five of them written by coding agents.