diagram turns ASCII art into hand drawn PNGs from a terminal editor

A terminal editor whose output is a handwritten diagram

ASCII art is a good drafting medium and a bad final format. Diagram takes the medium seriously enough to build a full application around it, described in the README as a full fledged CLI application to generate hand drawn diagrams from ASCII art, and the feature list names a full fledged content editor, an integrated GUI for image view, zooming and panning support for image inspection, an integrated file management system and layout customization.

The rendering is the point. The characters of your drawing are not the output; they are the input to a renderer that applies a handwriting font and produces a PNG that looks drawn rather than typed. That is what separates this from a terminal to PNG converter, and it is why the project needs a graphics stack at all.

The audience is two overlapping groups. Developers who design in ASCII, whether for a chat message, a commit description or a design document, and want a picture instead of a text block. And people who want to sketch something quickly in the terminal and get a shareable image without opening a graphics editor.

The attribution matters for provenance. The README states that the ASCII to PNG conversion was ported from shaky.dart, a JavaScript project, and the project is maintained by Endre Simo. So the rendering approach has a prior art that you can look at if you want to understand the technique behind the port.

Two ways to install: Homebrew or a Go build

The installation section is direct about the requirement. To run the application, Go has to be installed on your local machine, and $GOPATH/bin has to be included in the PATH directory, because the binary is installed there.

From source, the sequence is a clone, a build and a run:

$ git clone https://github.com/esimov/diagram
$ cd diagram
$ go build

# Start the application
$ diagram

If Homebrew is available, the README gives a shorter route, running `brew install diagram` to install the application.

The badges confirm that the Homebrew formula is a real distribution channel, with the release badge and the homebrew badge both showing v1.1.0.

There is a third path for people who want the binary for several platforms. A shell script is bundled into the library to mitigate the generation of binary files for the most common operating systems, with the caveat that different dependencies are needed for different operating systems, which the README points at the dependencies section. The Makefile target that runs it is:

all: 
	@./build.sh

The Makefile also has a clean target that removes the diagram binary, an install target that copies it into /usr/local/bin, an uninstall target, and a package target that runs the build script with NOCOPY=1 set. The same script is at the repository root as build.sh.

The Go version in use is not recent, by the standards of 2026. The module file declares go 1.22, so a toolchain that new enough to build it is required, and a much newer Go will also build it.

CTRL+g is the conversion, and the PNG lands in an output folder

Inside the terminal application you can create, edit or delete ASCII diagrams. The conversion itself is a single key press, CTRL+g, which converts the ASCII art into a handwritten diagram. The generated PNG file is saved into the output folder relative to the current path.

That detail about the output folder is worth pausing on, because it is a behaviour people trip over. The destination is relative to where you launched the process, not to the project you are editing, so the PNG appears in an output directory beside your current working directory. If you launch the binary from a different place than you expected, the image lands somewhere else.

The key binding list shows the rest of the interface. F1 shows and hides the help panel, Tab and Shift+Tab jump between panels, Ctrl+l changes the layout color, Ctrl+s opens the save diagram modal and then saves, Ctrl+g previews the generated ASCII diagram with zooming and panning, PageUp and PageDown scroll the editor content, Ctrl+x clears the editor content, Ctrl+z restores it, Home and End jump to the start and end of the line, Delete and Backspace delete the diagram, and Ctrl+q quits.

So there are two distinct actions for the same output. CTRL+g generates and previews, and Ctrl+s is the explicit save path through a modal. Which one you use decides whether the file lands in the output folder or where you asked for it.

The command line path skips the editor entirely

The application also supports generating hand drawn diagrams directly from the command line without entering the CLI application, and the help output lists the options. There are four of them.

The -font flag takes the path to the font file, and the -in and -out flags are the source and the destination. The -preview flag shows the preview window, and it is true by default, which is the option most likely to surprise you on a server or in a script.

The first example reads input from sample.txt and writes the image to sample.png, showing a preview window with the hand drawn diagram:

diagram -in sample.txt -out sample.png

The second does the same thing and exits immediately without a preview window:

diagram -in sample.txt -out sample.png -preview=false

The third shows how to change the font, which is the lever that controls how the result looks:

diagram -in sample.txt -out sample.png -preview=false -font /path/to/my/font/MyHandwriting.ttf

That last flag is the interesting one for anyone who wants a consistent house style. The default font path in the help output is a path on the author's own machine, which is a small sign that the default value in the shipped binary is not portable, so you should expect to pass -font explicitly if the default does not resolve on your system.

gocui for the interface, gg and Gio for the drawing

The dependency list is short and it explains the architecture.

The terminal user interface comes from jroimartin/gocui, and the graphics come from fogleman/gg and from gioui.org. The module file pins them at gocui v0.5.0, gg at a pseudo version, and gioui.org at v0.8.0, with go 1.22 as the language version.

The indirect dependencies fill in the rest of the picture. termbox-go is the terminal backend that gocui sits on, golang/freetype and go-text/typesetting are the font rasterisation stack, golang.org/x/image and golang.org/x/text handle image and text handling, and golang.org/x/exp/shiny appears as an indirect dependency, which is the Gio backend that talks to the window system. mattn/go-runewidth is there for the character width calculations that a monospaced grid editor needs.

Looking at the repository layout, the code is split along those lines. There is a canvas/ directory for the drawing surface, a color/ directory, a font/ directory that holds the default handwriting font, gui/ for the interface, io/ for input and output handling, ui/ for the user interface layer, and version/ for the version string that the help output prints. main.go ties it together.

The split between the GUI and the drawing layers is what makes the command line mode possible. The renderer does not need the editor, and the command line path exercises the renderer alone.

The browser based alternative and the limits of the terminal route

There is a genuine alternative, and the project names it in its acknowledgements. The conversion was ported from shaky.dart, a JavaScript tool that renders ASCII art through a browser canvas. The difference in approach is straightforward. A browser based renderer takes your text and paints it on a canvas you can see and save yourself, with no binary to install and no terminal user interface, but also no file management, no editor and no command line flags. Diagram takes the opposite trade: it requires a compiled binary and a terminal, and in return it gives you an editor, a preview with zooming and panning, a file management layer and a headless mode that writes a PNG to a path you name.

For a quick sketch in a chat window, the browser approach is less friction. For producing a set of diagrams as files in a repository, the command line mode is the one that fits.

There are real limits to be aware of. The README says the application was tested on Ubuntu, MacOS and Windows, but it also says that different dependencies are needed for different operating systems, which is the caveat attached to the bundled build script. Since the preview window is on by default, the tool expects a display, and the -preview=false form is what makes it usable over a remote shell or in a container.

The other limit is the font. The result is only as good as the handwriting font you point it at, and the default path in the help output points at a file on the original author's machine, so treat -font as a required argument in any scripted use.

MIT licensed, one author, and a slow release trail

The licence is MIT, and the README carries the copyright line, Copyright 2017 Endre Simo, with a pointer to the LICENSE file for the full text. The repository also holds the LICENSE file and a Makefile with install, uninstall and package targets for distribution.

The project is credited to a single author, Endre Simo, and the code is built by one person. That is a fair description of the risk profile for anyone depending on it.

The version history is thin. The recent releases are v1.1.0 on 2025-06-16, v1.0.6 on 2025-04-25 and v1.0.5 on 2022-01-11, and the last push to the repository was on 2026-04-21. The go.mod file still declares go 1.22, and the pinned dependency versions, gocui v0.5.0 and gioui.org v0.8.0, place the code base in an earlier era of its own dependencies.

In other words, the application is complete and usable, and the release trail shows long gaps, including a stretch from 2022 to 2025. For a tool whose output is a PNG, that matters less than it would for a library, because the risk is not that a dependency breaks but that nobody is fixing the next platform issue.

The build infrastructure is ordinary and healthy. There is a build workflow badge in the README, a Go Reference badge pointing at pkg.go.dev, a Go Report Card badge, and a release badge for v1.1.0. A sample.txt file sits in the root so you can try the command line mode without writing your own input.

Editorial conclusion

Adopt diagram if you sketch system layouts and diagrams in ASCII in a terminal and want a hand drawn PNG without leaving the shell, and if you are comfortable building a Go program or installing from Homebrew. Do not adopt it for a pipeline that needs a headless, reproducible renderer, because the interactive preview and the terminal UI are part of the design, and do not adopt it expecting a maintained release stream, since the newest release is v1.1.0 from 2025-06-16 and the last push was on 2026-04-21. Before you rely on it, read the dependencies section, because the rendering stack is gocui for the interface with gg and Gio for drawing, and try the -preview=false form of the command so the conversion runs without a preview window on a machine with no display.

Frequently asked questions

Official sources

1. esimov/diagram on GitHub
2. Issues
3. License: MIT
4. README
5. Releases