TopoDraft: Network Topology as Code — draw your network topology diagram with your AI agent

Network diagrams rot

Every network team has the same artifact: a network topology diagram in Visio,
PowerPoint, or a drawing tool — last updated three reorgs ago. Diagrams are
binary blobs. You can't git diff them, you can't review them in a PR, and no
automation can maintain them, so nobody does.

Code gets reviewed. Configs get reviewed. The diagram — arguably the most
load-bearing document in the room — doesn't.

I built a VSCode extension to change that: TopoDraft — Network Topology as
Code. The idea is simple: your network topology diagram is a plain text
file, you edit it on a canvas, and your AI agent edits the very same file —
live, right next to you.

• Marketplace: https://marketplace.visualstudio.com/items?itemName=kazukifujiwara.topodraft
• GitHub (Apache-2.0): https://github.com/kazukifujiwara/network-topo-draft

What it is

Open a *.topo.json file and you get a canvas editor with two views:

• Physical view — devices, cables, carrier circuits, and site frames. That's the cover image above: a two-site network across Tokyo-HQ and Osaka-DC.
• Logical view — VRF compartments, L3 adjacencies, and multi-access segments with HSRP/VRRP virtual IPs.

Logical view: VRFs, eBGP over each carrier circuit, and VRRP-backed LAN gateways.

Drag to place a node, drag a port to connect, double-click to rename
(references follow automatically), and undo is just VSCode's regular Ctrl+Z —
because every canvas action is really a plain text edit on the document
underneath.

That file is deliberately boring JSON, and the serializer is deterministic:
same content, same bytes. That one property is what makes a diagram reviewable
— a change to your WAN shows up as a three-line diff in a PR, not "binary files
differ."

{
  "version": 1,
  "devices": [
    { "name": "rt-tokyo-01", "role": "router", "site": "Tokyo-HQ",
      "interfaces": [{ "name": "Gi0/0/0", "ip_address": "10.255.0.1/30" }] }
  ],
  "circuits": [
    { "a": { "site": "Tokyo-HQ", "device": "rt-tokyo-01" },
      "b": { "site": "Osaka-DC", "device": "rt-osaka-01" },
      "cid": "CID-0001", "type": "leased line" }
  ]
}

The part I actually care about: your AI agent as a co-author

The goal was never "AI draws the diagram instead of you." It's an agent working
next to you, in the same file:

You ask; the agent writes the JSON; the open canvas draws every step. (Time-lapse.)

1. A toolbar button writes the complete file-format contract — rules, JSON Schema, and a worked example — into your workspace. It defaults to AGENTS.md, the file most coding agents read automatically, and Save as… lets you drop it under whatever name your agent expects (CLAUDE.md, GEMINI.md, …). Either way your agent learns the format without you explaining it, and rerunning is safe — an existing file is updated in place, not overwritten.
2. You ask your agent for something like "a two-site redundant WAN with VRRP gateways."
3. The agent writes *.topo.json; the open canvas renders each edit live.
4. You drag a few nodes to taste. Your edits are text edits too, so the agent can keep working after you.

Agents make mistakes, so the canvas is defensive by design: while an agent is
mid-edit and the JSON is momentarily broken, the canvas dims and waits — it
never crashes, and it never writes back over the agent's work. (There's also
validation with precise diagnostics and a headless CLI for CI — but that's a
topic for its own post.)

If you run NetBox

Field names follow NetBox where a counterpart exists (device_type, site,
tenant, cid, FHRP group_id, …), so a .topo.json can be a reviewable
view of one slice of your CMDB rather than yet another source of truth to keep
in sync.

Try it

No telemetry, no remote code, and the format is an open, published JSON Schema —
files embed $schema, so other tools and agents can validate and edit
*.topo.json too.

Search "TopoDraft" in VSCode extensions, or grab it here:

👉 https://marketplace.visualstudio.com/items?itemName=kazukifujiwara.topodraft

The +New menu ships templates (two-site WAN, HSRP segment, routed LAG pair)
— opening one is the fastest way to get a feel for it.

It's v0.1.0, built solo, and I'd genuinely love feedback: bug reports and
feature requests go to GitHub Issues,
and if it's useful to you, a Marketplace review or a GitHub star helps more than
you'd think.