ascii2svg 1.8.0

Your text diagrams, drawn properly. Every character stays exactly where you put it.

Playground · Quick start · Gallery · Fix LLM diagrams · For agents · Claude skill

_{The playground runs entirely in your browser: fix a model's misaligned diagram, type one live, browse the gallery.}

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 via WebAssembly.

Quick start

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

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:

As the model wrote it	--repair
2 of 5 boxes recognised, 10 warnings	5 boxes, 0 warnings, 5 fixes

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 fixes: ragged right walls (the top corner, every row and the bottom corner vote on where the wall belongs), drifted left walls, edges one character too long or short, connector pieces and arrowheads one or two columns off, arrowheads that stop a cell short, and gaps of one or two cells before a box.
• What it never does: change your words. Only line characters and spaces move or appear, and only into empty cells. 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.

Flow → decision tree → flow	C4 with a dashed boundary
UML inheritance △	ER crow's feet --||--o<
Gantt with block characters ██░░	Pivot table with a callout
Sequence → decision → reply	Swimlanes
ASCII diamonds / \	State machine

Pick a look

Same diagram, same guarantee, five ways:

Default	Colour	Dark	Print	Alive
(no options)	--color	--theme dark --color	--style flat --square	--animate --color --theme auto

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

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.

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

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]

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.
• 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.

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

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
• Vertical ER connectors, ASCII UML heads (<|--), ASCII dashed lines (- - ->)
• Repairing bigger misalignments (today: pieces up to two cells off, walls up to three)
• ASCII rounded corners (.-') and free-floating connectors between plain words
• A JS/npm port
• Every look checked in Firefox, Safari and cairo (--png); today: Chromium, with the static look in cairo and resvg

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        # 57 tests over 25 test diagrams; or: python3 -m pytest tests
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.

License

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

_{Every diagram on this page was drawn by ascii2svg from plain text, and checked cell by cell against it.}