termchart

termchart — Mermaid → terminal ASCII/Unicode

Render diagrams as plain text that displays in any monospace terminal and pastes cleanly into PRs, issues, and chat. You write Mermaid; the termchart CLI renders it deterministically.

When to use this

Reach for this whenever you would otherwise describe a flow in prose, draw freehand ASCII (which misaligns), or produce a PNG/Mermaid block the user can't see inline. Good for: architecture diagrams, request flows, state machines, decision trees, sequence/interaction diagrams, simple bar/line charts.

Workflow

1. Write Mermaid for one of the six supported diagram types (see grammar below).
2. Lint it (optional but recommended): pipe the source to termchart lint.
3. Render to a file with --color none, redirecting stdout to a file.
4. Read that file, then paste its contents into your reply inside a fenced code block.

CRITICAL — never leave the diagram as raw command output. Coding-agent harnesses (Claude Code, etc.) collapse long tool/command output behind a +N lines fold, so the user sees a truncated, broken diagram. You MUST read the rendered file back and reproduce it verbatim in your own message text. The diagram only displays correctly when it is part of your reply, not when it is left sitting in the terminal/tool output.

# 1+2: lint, then 3: render to a file (NOT straight to the terminal)
printf 'sequenceDiagram\n A->>B: hi' | termchart lint
termchart --color none diagram.mmd > /tmp/diagram.txt

Prefer a heredoc for multi-line diagrams, still redirecting to a file:

termchart --color none > /tmp/diagram.txt <<'EOF'
graph TD
  A[Idea] --> B{Good?}
  B -->|yes| C[Ship]
  B -->|no| A
EOF

Then read /tmp/diagram.txt and paste its exact contents into your reply in a ``` code block. Do not summarize or re-draw it — copy it byte-for-byte.

Flags

Flag	Effect
--ascii	Pure ASCII (+ - |) instead of Unicode box-drawing
--color <auto|none|16|256|truecolor>	Color output (default auto: color on a TTY, plain when piped)
--theme <name>	One of: zinc-light, zinc-dark, tokyo-night, catppuccin-mocha, nord, dracula, github-dark, one-dark, …
--padding-x <n> / --padding-y <n>	Spacing between nodes
--fit	Auto-compact spacing to fit terminal width (or 80 cols when piped)
--width <n>	Fit within <n> columns (implies --fit); warns if impossible

Note: --fit/--width only adjust spacing — the grid layout cannot reflow, so a graph that is inherently wider than the target will warn and use the tightest spacing. For those, switch graph TD⇄graph LR, shorten labels, or use --ascii.

When showing output inside chat, prefer --color none (or just rely on the piped default) and wrap the result in a code block so alignment is preserved.

Supported diagram types & grammar (the renderable subset)

Stay within these — the renderer draws them reliably:

• Flowchart: graph TD|LR / flowchart TD|LR, nodes A[label] B{decision} C[(db)], edges -->, labeled edges -->|yes|.
• State: stateDiagram-v2, [*] --> S1, S1 --> S2.
• Sequence: sequenceDiagram, A->>B: msg, B-->>A: reply.
• Class: classDiagram, A <|-- B, A : +int field.
• ER: erDiagram, CUSTOMER ||--o{ ORDER : places.
• XY chart: xychart-beta, bar [1,2,3], line [1,2,3].

Not rendered (avoid — lint will warn)

In sequence diagrams these are silently dropped: note, loop, alt, opt, par, activate/deactivate. Keep sequence diagrams to plain messages. If you need that structure, model it as a flowchart instead.

Authoring tips for clean output (from a UX comprehension study)

• ER relationship labels: one short word. Long/multi-word labels (e.g. "ordered in") get clipped to the inter-entity gap (→ ordere). lint warns. When the cardinality is the real point, a flowchart with A -->|many| B reads more clearly in a terminal than ER crow's-foot glyphs.
• State start/end ([*]) render as empty boxes (border convention only). If the start/end need labels, model the lifecycle as a flowchart with explicit Start / End nodes.
• Avoid database/cylinder nodes [(x)] with --ascii — they render with .--. corners that read as a broken box. Use the default Unicode mode for cylinders.
• For wide graphs, use --fit (or swap graph TD⇄LR) rather than letting the diagram overflow the terminal.

Rules

• Always run the source through termchart and show its actual output — never hand-draw ASCII yourself; the whole point is deterministic, aligned rendering.
• Render to a file, read it, and paste the contents into your message. Never rely on the raw terminal/tool output to display the diagram — it gets collapsed and the user sees a broken fragment. (See the CRITICAL note in Workflow.)
• Use --color none for diagrams shown in chat/PRs/issues so ANSI escapes don't corrupt the text. Reserve color modes for live interactive TTY use.
• If a diagram is very wide or tall, tighten it with --padding-x 2 --padding-y 1 and/or shorten node labels so it stays readable.
• If termchart lint reports an error (exit 1), fix the header/grammar before rendering. If it only warns, the diagram still renders minus the warned lines.
• One diagram per invocation.