Draw from your code

The archgram skill turns your code into a diagram. This guide explains what the agent reads, how it decides what to draw, and how to check its work. To add the skill, start with Quickstart with your agent.

Say what the diagram is for#

Before it reads any code, the agent decides who the diagram is for and the three to five questions it must answer for them. If you know, say so, and it draws that.

Draw how an order goes from the checkout to the warehouse, for a new backend engineer.

If you only ask for "the architecture", it takes the reader from your README and your words. You can name a flow, a part of the system or a direction, and it keeps to it.

What it reads#

It reads the code and the docs the diagram describes. It recognises the style the system follows and reads what that style needs, then follows each entry point to what it calls, reads and writes.

The styles it recognises are layered, ports and adapters, client and API, microservices, event-driven, pipelines, serverless, plugin hosts, compilers and CLIs, monorepos of libraries, and LLM, retrieval and agent systems. A system can follow several at once.

What it draws#

• A part only where a file backs it, such as a module, a route, a script or a store. The part is named after the file that decides, found by following the imports.
• A line only where a line of code makes it. The agent notes that line and a few words of it.
• Labels that say what the code shows. What only the README says goes into the report as a question, never into the drawing.
• About 10 parts and 12 lines, what a reader takes in within thirty seconds. Over that, it merges parts with the same relations, leaves out what the questions do not need, or splits the drawing in two.

When it asks you#

Only when the architecture is unclear. For example, when the README describes a part the code does not have, when two readings of the code are equally likely, or when you named something it cannot find. It says what it found and what it needs to know. Everything else it decides itself.

Check what it drew#

Each part and each line in the spec names the code behind it, in source.

nodes:
  - { id: worker, kind: service, label: Worker, source: ../../src/worker.ts }
  - { id: db, kind: database, label: Postgres, tech: postgresql }
edges:
  - { from: worker, to: db, source: "../../src/worker.ts#db.insert(order)" }

The agent's report lists the same, each part with its file and each line with its code. Open a few of them. A box no file backs, or a line no code makes, is a mistake worth pointing out.

Sources are never drawn, but archgram reads them. archgram check tells you when any of that code is gone, which is how the diagram stays true. Keep a diagram true explains it.

Change it#

Ask in plain words, and the agent changes the spec and draws it again.

Merge the two workers into one, and leave out the admin panel.

Or change the spec yourself. It is a short YAML file, and every field is in the spec format.

On a new diagram the agent lets archgram choose the direction, then writes that direction into the spec. A later change keeps it, so the drawing does not turn on its side from one version to the next. It turns the drawing only when you ask, or when the drawing no longer fits where it is shown.

Where the diagram is shown#

archgram keeps the text readable in a GitHub README by default. If the diagram is shown somewhere narrower, such as a docs site or a blog, tell the agent how wide that place is, and it writes it into the spec as shownWidth. Put it in a README or a site explains why.