ascii2svg

You sketch a diagram in plain text: in a README, a code comment, a chat with an AI. It looks right in a monospace font and falls apart everywhere else (Slack, email, Confluence, slides, a phone). ascii2svg turns it into a crisp SVG that draws itself, follows your reader's light or dark mode, and shows data moving along the arrows.

It never guesses. Every run reads its own SVG back and checks it against your text, cell by cell, so what you drew is exactly what you get. And the banner at the top of this page? That's plain text too.

Highlights

• Faithful, provably // every character lands in its exact cell, verified by reading the SVG back. A mismatch is an error, never a quiet surprise.

• Fixes LLM diagrams // --repair lines up the walls, connectors and arrowheads a chat model got one column wrong, without touching a word.

• Alive // lines draw themselves, pulses flow along arrows, tall diagrams unfold as you scroll. Nothing moves for readers who ask for reduced motion.

• More than boxes // flowcharts, sequence and state diagrams, C4, UML, ER crow's feet, Gantt and bar charts, diamonds, dashed lines.

• Agent-native // one JSON report for every outcome, hints that say exactly what to move, an MCP server and a Claude skill.

• Zero dependencies // one Python file for Python 3.9+. The same file runs in your browser and on npm via WebAssembly.

Related MCP server: MCP SVG Animator

Quick start

New here? The guide walks you through it in plain language: how to run it, how to draw diagrams that render well, which look to pick, and what to do when something doesn't come out as you meant.

In your browser, nothing to install: open the playground, paste a diagram, pick where it's going, download SVG, PNG or a web page. Nothing is uploaded.

From the command line:

pip install ascii2svg
ascii2svg diagram.txt -o diagram.svg --preset readme     # colour, light/dark, animation

From JavaScript, no Python needed: npm install @satyadip28/asciitosvg (see Install).

With Claude: add the skill, then just ask "turn this diagram into an image for my slides". Or connect the MCP server: claude mcp add ascii2svg -- ascii2svg --mcp.

Type this…

+------------+     +------------+     +------------+     +-------------+
|    Idea    |---->|   Draft    |---->|   Review   |---->|   Publish   |
+------------+     +------------+     +-----+------+     +-------------+
                         ^                  |
                         |                  |
                         +------------------+
                           needs changes

…get this

Plain + - | became real lines, v ^ < > became arrowheads, and the words stayed words. Unicode box characters (┌─┐ │ └─┘ ╭╮ ═║ ▶) work just as well.

LLM diagrams, fixed

Ask any chat model for an architecture diagram and the boxes rarely line up: an emoji counted as one column instead of two, a wall one space short, a connector that drifts sideways between rows. --repair puts them back:

• Boxes: walls, corners and edges up to 12 columns off move into line. A box whose words don't fit (a long label, or emoji counted as one column) grows to fit them, all rows at once.

• Connectors: a piece one or two cells to the side moves into line, and so does a whole half of a line that drifted 3-6 columns. Gaps of a cell or two are filled, and an arrow that stops short of its box is carried on until it touches (short_arrow warns about it first).

ascii2svg diagram.txt -o diagram.svg --repair --json

{"status": "ok", "summary": "Repaired 5 misalignments. Rendered 5 boxes and 3 arrows (22x51); 1:1 self-check exact.",
 "repair": {"edits": [{"line": 2, "col": 23, "fix": "moved the right wall '│' 1 col left"},
                      {"line": 6, "col": 12, "fix": "moved '│' 1 col left to line it up"}, "..."],
            "text": "┌─────────────────────┐\n│  📱 Mobile app      │\n..."}}

• What it never does: change your words. Only line characters and spaces move or appear: into empty cells, or, when a box grows, along that box's own connector, which gets shorter. A test strips every line character from each row, before and after, and checks that what remains is identical.

• What you get back: every edit with its line and column, and the corrected text in repair.text, ready to paste back where the diagram came from. Diagrams that were already right come back untouched.

In the playground, a diagram with warnings shows a Fix alignment button.

Gallery

All plain text, all 1:1. The sources are in docs/examples/, and every one is in the playground's example picker.

The flows follow the real wiring: through junctions, down both branches of a fan-out, and across the edge of a container. The text is tests/fixtures/complex_unicode.txt.

Pick a look

Same diagram, same guarantee, five ways:

Or let the destination decide: --preset readme|slides|chat|print|dark|page.

The animation is careful about where it runs:

• It never changes what's drawn. An animated file is the static file plus timing. When the animation ends, you're looking at exactly what the self-check verified; tools that don't play animation (PNG export, most editors) show the finished drawing.

• It respects the reader. With reduce motion turned on in the OS, nothing moves.

• draw and flow need no JavaScript. They use CSS and SVG <animate> only, so they play inside a plain <img> tag, which is how GitHub, Notion and most docs sites show images.

• scroll is a web page, not just an SVG, because an image can't see how far you've scrolled (and CSS scroll timelines don't drive SVG shapes: we tested it). The page adds about 2 KB of plain JavaScript; the SVG inside it is the same self-checked drawing.

How it compares

Choose a DSL when you want the layout done for you. Choose ascii2svg when the text diagram already exists, or when an LLM writes it, and you want it to look designed without changing it. Related projects such as svgbob and goat also turn ASCII art into SVG and draw more freeform shapes; ascii2svg focuses on box diagrams, a verified 1:1 result, and agent workflows.

What gets drawn

When unsure, a character stays text, so the worst case is the character itself in its own cell, never a wrong shape. a->b, --dry-run, user_id, C:\temp, yes/no, TCP/IP, markdown tables and |-- file trees all stay exactly as written.

How 1:1 is guaranteed: every run parses the SVG it just wrote (lines, curves, diagonals, arrowheads, rectangles, rings, feet, text positions) back into a character grid and compares it with the input, cell by cell. ASCII characters may only appear as the line they stand for (-→─, |→│, +→corner or junction, v→▼, /→╱). Any mismatch is exit code 2. This covers every look, including animated ones and the still frame used for PNGs.

Install

Python 3.9+ and nothing else:

pip install ascii2svg                 # adds the `ascii2svg` command and the `ascii2svg` module
pip install "ascii2svg[width,png]"    # optional: wcwidth (character widths) + cairosvg (--png)

It is a single file with no dependencies, so you can also just copy scripts/ascii2svg.py into your project.

Node and the browser, with no Python install:

npm install @satyadip28/asciitosvg
npx @satyadip28/asciitosvg diagram.txt -o diagram.svg --preset readme

import { render } from "@satyadip28/asciitosvg";
const { markup, report } = await render(diagram, { preset: "readme", repair: true });

The npm package runs this same Python module in Pyodide (CPython on WebAssembly). Its tests render every test diagram in five looks both ways and require byte-identical SVG and reports. The CLI and the MCP server (npx -y @satyadip28/asciitosvg --mcp) work as with pip; only --png needs the Python package. Details: npm/README.md.

import ascii2svg

svg, report = ascii2svg.render(open("diagram.txt").read(), color=True, theme="auto", animate="flow")
assert report["roundtrip"] == "exact"          # the 1:1 self-check passed
open("diagram.svg", "w", encoding="utf-8").write(svg)

page, report = ascii2svg.render(text, color=True, animate="scroll", html=True)   # a scroll-reveal page

render() takes the same options as the CLI and returns the markup plus the same report as --json. It raises ValueError for empty or oversized input and for unknown options.

Download ascii2svg.skill from the latest release (or build it: python3 tools/package_skill.py), then:

• claude.ai / Claude desktop: Customize → Skills → upload ascii2svg.skill.

• Claude Code: unzip it into ~/.claude/skills/ (you get ~/.claude/skills/ascii2svg/).

SKILL.md tells Claude when to use it, which look fits which destination, to add --repair for model-drawn diagrams, and how to read the report before handing you the file.

ascii2svg [INPUT ...] [-o OUT.svg|OUT.html|DIR/] [--preset NAME] [--json] [--check] [--describe] [--brief]
          [--color] [--theme light|dark|auto] [--animate [draw|flow|scroll]] [--html] [--repair]
          [--style glow|shadow|flat] [--square] [--accent #HEX] [--font NAME] [--width PX]
          [--all-blocks] [--block N] [--unescape] [--strict] [--schema] [--mcp]
          [--png [PATH]] [--text TEXT] [--tab-size N] [--title TEXT]

stdout is always exactly one thing: the SVG (or the page, with --html), or (with --json) the report. A one-line summary goes to stderr.

Built for agents

Every outcome is machine-readable, nothing hangs, and every problem comes with a fix. The loop: draft the diagram, check it, fix what the hints say, then render.

ascii2svg draft.txt --check --describe      # validate + structure; writes nothing
ascii2svg draft.txt -o out.svg --preset readme --json --brief

{"status": "warnings",
 "summary": "Rendered 2 boxes and 0 arrows (8x8); 1:1 self-check exact. 1 warning, first: row 4 col 4 (dangling_line): the arrowhead 'v' at row 5 col 5 is one column right; move one of them so they line up",
 "exit_code": 0, "...": "..."}

• One JSON object on stdout for every outcome with --json (or --check), including usage errors: {"status": "usage_error", "hint": "'--colour': did you mean --color?"}. status and summary come first, so a truncated report still says what happened.

• Warnings you can act on: each has a stable code, a 1-based row/col, the source line, and a hint. When a line misses its partner by one cell, the hint says where it is.

• No false alarms on well-formed diagrams: a line may end at a label, meet another line side-on (sequence messages │───▶│), or stop in open space (axis ticks, lifeline ends).

• --describe says what the diagram means: boxes (name, title, text, position, parent) and edges (Gateway → Orders), with a kind where the notation says more: inheritance, aggregation, composition, relationship with ER cardinality (["one", "zero or many"]), or link for a plain line, and the label set into a line (--HTTP-->). An endpoint that is not a box is the word it points at ({"text": "Postgres"}).

• No hangs: if you forget the input and stdin stays silent, it fails after 5 seconds with bad_input.

• --schema prints every option, preset, exit code, warning code and report field as JSON: enough to build a correct tool definition without reading docs.

As an MCP server (Claude Code, Claude Desktop, Cursor, any MCP client):

claude mcp add ascii2svg -- ascii2svg --mcp

{"mcpServers": {"ascii2svg": {"command": "ascii2svg", "args": ["--mcp"]}}}

Two tools, no dependencies: check_diagram validates and describes, render_diagram writes .svg or .html with any preset or style option, and both take repair. The diagram travels as a JSON string, so the escaped-newline problem can't happen. Tested against the official MCP Python SDK.

Many diagrams at once:

ascii2svg README.md --all-blocks -o diagrams/ --preset readme   # every diagram in the file
ascii2svg docs/*.txt -o out/ --check                            # several files, one report each
ascii2svg README.md --block 3 -o flow.svg                       # just the third code block

Code blocks without lines or boxes are skipped and listed under skipped. Every warning carries source_line/source_col: its position in the file you passed.

As a tool in any agent framework: pass the diagram on stdin, never through --text (escaped newlines are the most common way agents break diagrams):

import json, subprocess

def render_ascii_diagram(diagram, output_path, preset="readme", describe=False):
    args = ["ascii2svg", "-", "-o", output_path, "--preset", preset, "--json", "--brief", "--repair"]
    p = subprocess.run(args + (["--describe"] if describe else []), input=diagram.encode(), capture_output=True)
    return json.loads(p.stdout)          # always one JSON object, including on errors

Roadmap

• Boxes, arrows and junctions, in ASCII and Unicode, verified 1:1

• Colour, light/dark/auto themes, draw and flow animation, scroll-reveal pages

• Agent CLI: JSON reports, hints, --describe, presets, --schema, MCP server, Claude skill

• Browser playground (Pyodide), with share links and PNG export

• --repair for LLM-drawn diagrams

• Block-element charts, diagonals and diamonds, dashed lines, UML heads, ER crow's feet

• ER crow's feet on vertical connectors (-+- ticks, o rings, /|\ and \|/ feet)

• ASCII UML heads (<|-- <>-- *--) and ASCII dashed and dotted lines (- - -> ....> :)

• Repairing bigger misalignments: boxes that must grow, walls and edges up to 12 columns off, lines split 3-6 apart, arrows that stop short

• ASCII rounded corners and bends (.--. '--')

• Arrows between plain words (A --> B, A --HTTP--> B, | and v under a label)

• Vertical ASCII UML heads (/_\ <> * under or over a box)

• On npm: @satyadip28/asciitosvg, the same module in WebAssembly, byte-identical by test

Everything planned has shipped. Have an idea, or a diagram that doesn't render the way you meant? Open an issue.

Contributing

Issues and pull requests are welcome, and a diagram that renders wrongly is the most useful bug report there is: paste the text and say what you expected.

python3 tests/test_ascii2svg.py        # 65 tests over 32 test diagrams (or: python3 -m pytest tests)
cd npm && npm install && npm test      # the npm package: byte-identical to Python on every test diagram
python3 docs/build.py                  # regenerate every image on this page and the playground files

New shapes come with a test diagram in tests/fixtures/, and every fixture must round-trip exactly in every style and look. That's the one rule: never a wrong picture.

• round-trip in every style and every look; animation that ends on the static drawing and respects reduced motion

• flow routes that start at the right box; scroll reveal driven by the page, with no script inside the SVG

• colour groups; glow never behind a label; planted faults that must be caught; byte-identical repeat runs

• the ASCII traps; width fallback vs wcwidth; UTF-8 output on Windows consoles; the render() library API

• the agent contract: JSON usage errors, status and summary, near-miss hints, escaped-newline and broken-box detection, --describe edges, presets, --schema, no hang on a forgotten input

• every diagram in a markdown file, several inputs, positions mapped back to the file, the MCP protocol

• the browser playground runs exactly this module, and every playground example round-trips

• no false alarms on sequence diagrams, timelines, charts and dashed boundaries; real mistakes still warn

• --repair: every LLM fixture repaired to ok, text provably unchanged, good diagrams untouched; a box grows for a long label or emoji, a split line is joined (never doubled), a short arrow reaches its box

• block elements as exact rectangles; / \ only as runs, never inside yes/no or C:\Users

• dashed lines keep their dash count, form boxes and carry arrows; ASCII - - ->, ....> and : too, while Loading..., dot leaders and - - - stay text; ASCII UML heads <| <> * are drawn and described

• UML triangles and diamonds, ER ticks, rings and crow's feet across and up and down; --describe names each relationship and its cardinality

• ASCII UML heads up and down (/_\ <> *), drawn and described; rounded ASCII boxes and bends; arrows between plain words and labels set into lines, while a-->b, x -> y, p->next, --dry-run, markdown tables and print(" -->") stay text

They pass with and without the optional packages.

License

MIT. Use it, change it and ship it, commercially too; keep the copyright notice.