mpospirit/lazydraw

Source: https://github.com/mpospirit/lazydraw

lazydraw

lazydraw is a terminal ASCII editor for drawing quick diagrams and sketches, with options to export to text files or copy to the clipboard.

https://github.com/user-attachments/assets/ef0d2284-5a39-46ca-bd87-860584e53158

Acknowledgements

• ASCIIFlow by Lewis Hemens: the original, and the thing lazydraw is trying to be in a terminal.
• termDRAW by Ben Vinegar: showed that this class of editor is possible in the terminal, and shaped how the rendering loop is approached.
• OpenTUI by SST: the terminal UI engine the whole front end is built on.

Install

lazydraw runs on the Bun runtime, so Bun 1.3 or later has to be installed. You also want a terminal with mouse support.

bun install -g lazydraw
lazydraw

If the lazydraw command isn’t found afterwards, Bun’s global bin directory isn’t on your PATH. Add it to your shell profile:

export PATH="$HOME/.bun/bin:$PATH"

npm installs it just as well, and usually lands somewhere already on your PATH:

npm install -g lazydraw

Or skip installing altogether:

bunx lazydraw

Inside herdr

lazydraw ships a herdr plugin manifest, so it can live in your multiplexer as a pane split to the right of whatever you’re working on:

herdr plugin install mpospirit/lazydraw

The install step runs bun install --production in the clone, so Bun still has to be on your PATH.

Plugin manifests can’t declare their own keybindings — herdr owns that surface — so add this to your own config.toml (opened via herdr’s settings, or ~/.config/herdr/config.toml) and run herdr server reload-config:

[[keys.command]]
key = "prefix+ctrl+d"
type = "plugin_action"
command = "mpospirit.lazydraw.open"
description = "open lazydraw"

Ctrl+B Ctrl+D then opens the canvas as a right-hand split. Rebind it by changing key above.

Run

lazydraw                     # open the last drawing
lazydraw architecture        # open or create a drawing by name
lazydraw ./diagram.ld.json
lazydraw --import notes.txt

Export a drawing without opening the UI:

lazydraw export architecture --basic --comment hashes --fenced -o diagram.txt
lazydraw list

Toolbar

≡ │ box select arrow line text eraser │ export │ ⟲ ⟳ │ ⚙ │ help

Keys

In text mode, printable keys (including digits, q and ?) type text.

Selecting can also copy to the clipboard by itself — settings → copy on select, off by default.

Files

• Drawings: ${XDG_DATA_HOME:-~/.local/share}/lazydraw/drawings/<name>.ld.json
• Config: ${XDG_CONFIG_HOME:-~/.config}/lazydraw/config.json

Drawings autosave 500 ms after each change, and again on quit.

Terminal notes

• tmux: needs set -g mouse on. Copying via OSC 52 needs set -g set-clipboard on.
• macOS: Alt+digit needs “Option as Meta” (or use the bare digits).
• Colors: the default terminal theme reads your terminal’s own palette (OSC 10/11/4) and wears it — background, text and ANSI colors — so lazydraw is see-through and matches whatever your terminal looks like. settings → theme also offers ten IDE themes, which paint their own background: dracula, nord, tokyo-night, catppuccin, one-dark, gruvbox, monokai, night-owl, solarized-dark, github-light. Terminals that don’t answer the color query fall back to nord.
• Grid: the default lattice style draws 🭼 (U+1FB7C) in each empty cell, tinted 7% from your background toward the text color so it stays faint. If your terminal doesn’t render it as cell-edge hairlines, switch to checker in settings.

Development

bun install
bun start           # run from source
bun test            # unit, fixture, and end-to-end tests
bun run typecheck
bun run build       # standalone binary at dist/lazydraw

• src/core is pure TypeScript with no terminal code. Its drawing logic (glyph connection, snapping, line routing, box/line/select/move tools, export wrappers) is ported from ASCIIFlow’s client/.

• src/tui is the OpenTUI front end: one full-screen surface that paints the canvas, toolbar, popovers and dialogs.

• test/fixtures/asciiflow holds golden outputs captured by replaying test/scenarios/asciiflow.json through ASCIIFlow’s own code. To regenerate them:

  git clone https://github.com/lewish/asciiflow /tmp/asciiflow && (cd /tmp/asciiflow && bun install)
  bun run fixtures /tmp/asciiflow
  

• test/upstream runs ASCIIFlow’s own spec files against lazydraw’s core, through a small compatibility shim.