ASCII diagrams in code comments, drawn by a program

Packet layouts, state machines, module maps: embedded, systems, and protocol engineers keep them in header comments because that is the only format that ships with the code. Hand-drawn boxes drift, and agents mangle them. mdd computes the layout from JSON and splices it behind your comment prefix.

Open App Read the Docs

A state machine in a header comment

A connection state machine as it appears at the top of a C file. Every line carries the comment prefix, and re-rendering replaces exactly this block.

// mdd:begin id=conn-states src=conn_states.diagram.json
//
//    ┌─────────┐
//    │  IDLE   │
//    └┬───────▲┘
//  open()  timeout
//     │       │
//  ┌──▼───────┴─┐
//  │ CONNECTING │
//  └──────┬─────┘
//        ack
//         │
//   ┌─────▼─────┐
//   │ CONNECTED │
//   └─────┬─────┘
//      close()
//         │
//    ┌────▼───┐
//    │ CLOSED │
//    └────────┘
//
// mdd:end

The model your agent edits

{
  "version": 1,
  "boxes": [
    {
      "id": "idle",
      "label": "IDLE",
      "row": 0,
      "connections": [
        {
          "to": "connecting",
          "arrow": "to",
          "label": "open()"
        }
      ]
    },
    {
      "id": "connecting",
      "label": "CONNECTING",
      "row": 1,
      "connections": [
        {
          "to": "connected",
          "arrow": "to",
          "label": "ack"
        },
        {
          "to": "idle",
          "arrow": "to",
          "label": "timeout"
        }
      ]
    },
    {
      "id": "connected",
      "label": "CONNECTED",
      "row": 2,
      "connections": [
        {
          "to": "closed",
          "arrow": "to",
          "label": "close()"
        }
      ]
    },
    {
      "id": "closed",
      "label": "CLOSED",
      "row": 3
    }
  ]
}

Your agent draws it, you review it

Model the state machine as JSON next to the source file.
Run mdd render with --prefix "// " to splice the diagram into the header comment.
When transitions change, your agent edits the JSON and re-renders — it never redraws box characters by hand.
mdd check in CI fails the build if the comment block goes stale relative to the JSON.

A prompt to hand your agent

Keep the state machine diagram in src/conn.c current with mdd. Edit conn_states.diagram.json, then run: npx mdd render --json conn_states.diagram.json --file src/conn.c --id conn-states --prefix "// ".

Why mdd here

This is the purest case for a program computing the layout instead of a model eyeballing characters: comment blocks have no renderer, so alignment is the format. mdd's comment-prefix splicing keeps every line behind // or # and regenerates the block idempotently.

More use cases

AGENTS.md architecture maps — An architecture map in your agent context file: ASCII for humans, JSON ground truth for the agent.
Runbook flowcharts — Decision flows and failure maps readable in any terminal, drafted and updated by your incident tooling.
Design docs, RFCs & ADRs — RFC and ADR system diagrams that stay legible in diffs across every revision round.
ASCII sequence diagrams — Auth flows and call chains as plain text: message order in the JSON is the layout.
Data pipeline lineage maps — A curated lineage map your agent keeps current as pipeline models change.
Multi-agent orchestration maps — Agent hand-offs, tool wiring, and memory flow — documentation the agents themselves can update.
Docs-as-code threat models — Data-flow diagrams with trust boundaries, drafted from the code and reviewed in the diff.
Tutorials & conceptual docs — Conceptual diagrams that survive every downstream medium: docs site, README, PDF, chat.
comment-prefix splicing docs