termchart

termchart

Deterministic Mermaid → ASCII/Unicode diagrams in your terminal. No PNGs, no browser, no Mermaid handoff — just aligned text that pastes cleanly into PRs, issues, and chat.

Ships as two things that install together:

• a CLI (termchart) that renders Mermaid to text, and
• a Claude Code plugin (a termchart skill + /termchart:diagram command) that teaches an agent to emit supported Mermaid and render it.

Built on beautiful-mermaid — a synchronous, no-DOM grid renderer, so the same input + flags always produce the same bytes.

Quick look

$ printf 'graph LR\n A[Client] --> B[API] --> C[(DB)]' | termchart
┌────────┐     ┌─────┐     ┌──────┐
│ Client ├────►│ API ├────►│  DB  │
└────────┘     └─────┘     └──────┘

Install

As a Claude Code plugin (gets the skill + command + CLI)

/plugin marketplace add ivanmkc/termchart
/plugin install termchart@termchart

On session start the plugin ensures the termchart CLI is on your PATH (installing it via npm if missing).

Standalone CLI (any agent, or just you)

npm i -g termchart

Requires Node 18+.

CLI usage

termchart [file]            # render a Mermaid file, or stdin if omitted
termchart lint [file]       # check source is within the renderable subset
termchart --version

Flags:
  --ascii                   # pure ASCII (+,-,|) instead of Unicode box-drawing
  --color <auto|none|16|256|truecolor>   # default auto (color on a TTY, plain when piped)
  --theme <name>            # zinc-dark, tokyo-night, dracula, nord, github-dark, …
  --padding-x <n> / --padding-y <n>
  --fit                     # auto-compact spacing to fit terminal width (80 if piped)
  --width <n>               # fit within <n> columns (implies --fit)

--fit/--width shrink spacing to fit; they can't reflow an inherently wide graph, so termchart warns and uses the tightest spacing when a target is impossible (switch TD⇄LR, shorten labels, or use --ascii).

Exit codes: 0 ok · 1 lint/unsupported · 2 parse error · 3 bad usage.

Supported diagram types

flowchart · stateDiagram-v2 · sequenceDiagram · classDiagram · erDiagram · xychart-beta.

termchart lint warns about constructs the renderer drops (e.g. sequence note/loop/alt/opt).

Using it from other agents

Point any agent's rules/skill file at the same CLI: have it write Mermaid in the supported subset, run termchart lint, then termchart to render. See plugin/skills/termchart/SKILL.md — it's written to be agent-agnostic.

Development

npm install          # installs workspace deps
npm run build        # tsc → packages/cli/dist
npm test             # vitest (lint, render, golden snapshots, CLI smoke)

Design notes: docs/specs/2026-05-31-termchart-design.md.

License

MIT