The name
ASCII Diagram is deliberately literal. It says what the tool is for: making diagrams that live comfortably in a world of monospaced text, code review, documentation, and plain files.
The goal is not nostalgia for terminals. The goal is durability. A diagram should still make sense when copied into a README, pasted into an issue, checked into Git, or opened years later without the original app running.
Structured source
The canonical document is a real .asciid file with objects, relations, groups, and metadata. That file is the source of truth.
Portable output
The rendered ASCII is easy to paste into docs, PRs, chat, and commit messages. You are not forced to ship a screenshot for every diagram change.
ASCII Diagram exists to make this workflow pleasant: draw visually, store the result as a file you own, and move between app, editor, and documentation without changing the underlying artifact.
Why text-shaped diagrams?
Text has unusual strengths. It survives copy and paste. It survives diff tools. It survives code review. It survives environments where a rich whiteboard or design tool is overkill.
ASCII Diagram is not limited to raw hand-edited ASCII art. The source file is structured JSON, which means the editor can offer snapping, routing, grouping, and metadata while still preserving a file-based workflow.
That gives you the best parts of both worlds: a real editor for making diagrams quickly, and an artifact that remains inspectable and easy to move around.
Human-readable
The output can be pasted directly into text-heavy workflows, and the source file can be opened in any editor.
Versionable
Diagram changes can be reviewed alongside code and documentation instead of disappearing inside an opaque binary format.
Portable
You do not need one specific app to preserve the work. The file stays yours even if the UI changes or the project disappears.
A diagram should survive the app that drew it.
file > app
The app should make diagrams easier to create, not harder to keep. In ASCII Diagram, the file is canonical. The app is a tool that reads, edits, renders, and exports that file.
That distinction matters. If the file is canonical, normal software hygiene works: Git diffs, backups, scripts, alternate editors, and future migrations. If the app is canonical, every one of those things becomes a special case.
We treat the .asciid document as the durable artifact and the rendered ASCII as a convenient projection of that artifact. The editor is there to help, not to hold the source hostage.
Typical diagram app
- Source trapped in an app-specific canvas blob
- Reviews happen through screenshots or exports
- Diffs are noisy or unavailable
- Leaving means reconstructing the diagram elsewhere
- The tool owns the workflow
ASCII Diagram
- The .asciid file is the source of truth
- Rendered ASCII can be copied anywhere
- Git can track meaningful diagram changes
- Any JSON-capable tool can inspect the file
- The file owns the workflow
Not screenshotware
A surprising number of technical diagrams end their life as a PNG in a wiki or a screenshot pasted into chat. That is convenient in the moment, but it is a bad long-term source format. The structure is gone. The diff is gone. Editing becomes a manual redraw.
ASCII Diagram takes the opposite route. The diagram stays structured, and the plain-text output is generated when you need it. That means the image-like representation is no longer the only representation.
This also keeps the tool honest. If the exported ASCII is useful and the underlying file is inspectable, the app has to earn its place by being faster and nicer to use, not by locking you in.
We think that is the right bargain: structured files you own, copy-friendly output when you need it, and an editor that stays replaceable by design.
Good tools help you produce artifacts that do not depend on the tool.
Compatible workflows, forever
ASCII Diagram should fit into the tools you already use. The file is JSON. The output is text. That makes it a good citizen in technical workflows that already revolve around source control and docs.
That is the point of file > app. You should not need permission from one UI to access your own diagram source.