GitHub - isacikgoz/cligram

Mermaid flowcharts, drawn in your terminal: laid out to fit it, and live as a run moves through them.

The cligram playground: a Mermaid flowchart and the terminal drawing of it

Try the playground: paste a flowchart, see it drawn.

Use it

brew install isacikgoz/tap/cligram
# or a binary from https://github.com/isacikgoz/cligram/releases, or
go install github.com/isacikgoz/cligram/cmd/cligram@latest

cligram -width 80 <<'EOF'
flowchart LR
  task([Task]) --> plan[Plan] --> act[Run tools]
  act --> check{Done?}
  check -->|no| plan
  check -->|yes| done([Answer])
EOF

                ┌───[ no ]────────────────────┐
                ▼                             │
┏━━━━━━━━┓  ╭────────╮  ╭─────────────╮  ╔════╧════╗              ┏━━━━━━━━━━┓
┃   Task ┠─►│   Plan ├─►│   Run tools ├─►║   Done? ╟───[ yes ]───►┃   Answer ┃
┗━━━━━━━━┛  ╰────────╯  ╰─────────────╯  ╚═════════╝              ┗━━━━━━━━━━┛

Without -width it fits the terminal it prints to. Subgraphs draw as titled frames, and a graph of links with no arrowheads (a --- b) is drawn as a network, laid out by its links. It reads state diagrams (stateDiagram-v2) and sequence diagrams (sequenceDiagram) too, and cligram's YAML (examples/release.yaml), and cligram md README.md prints Markdown with its mermaid blocks drawn.

cligram watch shows a run live: pipe it events, one a line.

(echo "build active"
 if make >build.log 2>&1; then echo "build done"; else echo "build failed"; fi
) | cligram watch flow.mmd

From Go

d := cligram.New()
d.Node("triage", "Triage")
d.Node("ready", "Ready to ship?", cligram.As(cligram.Decision))
d.Node("ship", "Ship it")
d.Node("fix", "Fix it", cligram.Class("agent"))
d.Edge("triage", "ready")
d.Edge("ready", "ship", cligram.Label("yes"))
d.Edge("ready", "fix", cligram.Label("no"))
d.Edge("fix", "ready")

l := d.Layout(cligram.Fit(80, 24))
fmt.Println(l.Render(cligram.State{
	Status: map[string]cligram.Status{"triage": cligram.Done, "ready": cligram.Active},
	Taken:  []cligram.EdgeRef{{From: "triage", To: "ready"}},
}, cligram.Plain))

Lay out once per size, then repaint as the run moves: boxes never move. Package bubble is a Bubble Tea component with keyboard focus and sub-diagrams, and Goto to put the reader back after the host rebuilds them; go run ./examples/live shows it.

For agents

Skill: npx skills add isacikgoz/cligram
MCP: claude mcp add cligram -- cligram mcp gives a draw tool
JSON: cligram -json returns the drawing, its size and its warnings

AGENTS.md is the full guide. MIT licensed.