diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index b345704..0850bc3 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -8,18 +8,18 @@ { "name": "termchart", "source": "./plugin", - "description": "A live canvas your AI draws on — instead of walls of text, your agent pushes rich, native visuals to a browser / iPad / second screen in real time: React Flow graphs (architecture, sequence, call-graph, ER/class, state machine, PR-review, journeys, recursion trees), Vega-Lite charts (incl. scientific + Big-O), Mantine dashboards & product comparisons, deep-code walkthroughs, markdown, and split panes, with animated edges and live status overlays (toasts, progress bars, loaders). Deterministic Mermaid → ASCII/Unicode is the terminal fallback. Persona recipes, a showcase gallery, and fullscreen panes.", - "version": "0.14.0", + "description": "A live canvas your AI draws on — instead of walls of text, your agent pushes rich, native visuals to a browser / iPad / second screen in real time: React Flow graphs (architecture, sequence, call-graph, ER/class, state machine, PR-review, journeys, recursion trees), Vega-Lite charts (incl. scientific + Big-O), Mantine dashboards & product comparisons, deep-code walkthroughs, markdown, and split panes, with animated edges and live status overlays (toasts, progress bars, loaders). Persona recipes, a showcase gallery, and fullscreen panes. (A deterministic Mermaid → ASCII/Unicode terminal renderer is still bundled but deprecated.)", + "version": "0.15.0", "license": "MIT", "keywords": [ - "mermaid", - "ascii", - "diagram", - "terminal", + "viewer", "react-flow", "vega-lite", - "viewer", - "charts" + "dashboard", + "charts", + "diagram", + "mantine", + "ipad" ] } ] diff --git a/AGENTS.md b/AGENTS.md index 755a742..6cf973d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,10 +1,10 @@ # termchart — agent guide -termchart draws diagrams for you: **inline ASCII/Unicode in the terminal**, or **rich live -visuals pushed to a web viewer** (React Flow graphs, Mantine UI dashboards, Vega-Lite charts, -markdown, split panes) plus **status overlays** (toasts / progress bars / loaders). Prefer it -over describing a diagram in prose, hand-drawing ASCII (which misaligns), or emitting a raw -Mermaid block the user can't see inline. +termchart draws diagrams for you: **rich live visuals pushed to a web viewer** (React Flow +graphs, Mantine UI dashboards, Vega-Lite charts, markdown, split panes) plus **status overlays** +(toasts / progress bars / loaders). Prefer it over describing a diagram in prose or emitting a +raw Mermaid block the user can't see. (A deterministic Mermaid→ASCII terminal renderer is still +bundled but **deprecated** — use the viewer.) This is the cross-tool [`AGENTS.md`](https://agents.md) standard — read natively by Antigravity, Cursor, Codex, Copilot, Gemini CLI, Windsurf, Zed, Aider, and others (and by Claude Code via @@ -15,24 +15,6 @@ there are no per-agent install steps. - The `termchart` CLI must be on PATH (npm, Node ≥18). Self-heal before first use: `command -v termchart >/dev/null || npm i -g @ivanmkc/termchart` -- **Always render to a file** with `--color none`, read it back, and paste it **verbatim** into - your reply. Agent terminals fold long tool output behind a `+N lines` collapse, so a diagram - left in the terminal shows up broken — it only displays correctly inside your message. - -## Inline diagrams (terminal) - -Write Mermaid in the supported subset (flowchart / sequence / state / class / ER / xychart), -lint it, render to a file, then paste the file's contents: - -```bash -printf 'graph LR\n A[Client]-->B[API]-->C[(DB)]' | termchart lint -termchart --color none diagram.mmd > out.txt # then READ out.txt and paste it byte-for-byte -``` - -Supported subset: `graph TD|LR` nodes `A[x]` `B{decision}` `C[(db)]` edges `-->`/`-->|label|`, -`stateDiagram-v2`, `sequenceDiagram` (`A->>B: msg` only — no note/loop/alt/opt/par), -`classDiagram`, `erDiagram`, `xychart-beta`. Full grammar + flags: -. ## Rich visuals + progress (the live viewer) @@ -57,7 +39,9 @@ sequence/ER/class/state graphs) from the formats + copy-paste examples here: | Want | Use | |---|---| -| an inline ASCII diagram in chat | `termchart` render (terminal) | | a live rich visual on a screen / iPad | `termchart push --type …` | | show activity the instant work starts | `termchart begin …` (placeholder + focus + loader) | | narrate long work (toasts / progress / loaders) | `termchart status …` | + +_Deprecated: `termchart ` still renders Mermaid → terminal ASCII, but it's no longer the +recommended surface — push to the viewer instead._ diff --git a/README.md b/README.md index ec69080..6ed5b1b 100644 --- a/README.md +++ b/README.md @@ -7,14 +7,14 @@ it pushes *native* visuals to a browser tab in real time — architecture maps, reviews, charts, call graphs, live progress — so you glance at a **companion screen** (a second monitor or an iPad) and just *see* what your agent is doing and thinking, no scrolling required. It ships as a **CLI** (`termchart`) plus a **Claude Code plugin** (skills + the -`/termchart:diagram` and `/termchart:diagram-remote` commands): +`/termchart:diagram-remote` command): -- **The canvas (primary).** Run the viewer **locally** (or deploy it); agents push rich, - *native* visuals over SSE — React Flow graphs, Vega-Lite charts, Mantine UI dashboards, - markdown, and split panes — plus live **status overlays** (toasts / progress bars / loaders). - Best on a second monitor or an iPad. -- **Inline terminal text (secondary).** Deterministic **Mermaid → ASCII/Unicode** that pastes - cleanly into PRs, issues, and chat — no PNGs, no browser, no Mermaid handoff. +- **The canvas.** Run the viewer **locally** (or deploy it); agents push rich, *native* visuals + over SSE — React Flow graphs, Vega-Lite charts, Mantine UI dashboards, markdown, and split + panes — plus live **status overlays** (toasts / progress bars / loaders). Best on a second + monitor or an iPad. +- **Inline terminal text (deprecated).** A deterministic **Mermaid → ASCII/Unicode** renderer is + still bundled (`termchart `), but it's no longer the focus — push to the viewer instead. ![termchart viewer rendering a narrative PR review — before/after cards, a timeline, a validation banner, and an FAQ, with a link out to the pull request](packages/viewer/docs/gallery/pr-review-summary.png) @@ -39,7 +39,7 @@ the right visual and draws it: ``` /termchart:diagram-remote a sequence diagram of the OAuth login flow → on the canvas -/termchart:diagram a state machine for an order's lifecycle → inline ASCII +/termchart:diagram-remote a state machine for an order's lifecycle → on the canvas ``` Or just say it in any message — *“put that on the termchart canvas”*, *“draw that as a diagram”* — @@ -245,7 +245,11 @@ GCS env are set, GitHub wins and a line is logged). --- -## In the terminal +## In the terminal (deprecated) + +> ⚠️ **Deprecated.** The terminal Mermaid → ASCII/Unicode renderer still works but is no longer +> the focus of termchart — prefer the live viewer above (`termchart serve` + `termchart push`). +> It remains bundled for backward compatibility; this section is kept as reference. Deterministic Mermaid → ASCII/Unicode from the same `termchart` CLI. Built on [`beautiful-mermaid`](https://github.com/lukilabs/beautiful-mermaid) — a synchronous, no-DOM @@ -343,24 +347,23 @@ below is an alternative for Claude users. ``` On session start the plugin ensures the `termchart` CLI is on your PATH (installing it from -npm if missing). Then use **`/termchart:diagram`** (inline terminal) or -**`/termchart:diagram-remote`** (live viewer). +npm if missing). Then use **`/termchart:diagram-remote`** to draw on the live viewer. #### Optional: a bare `/diagram` alias -Claude Code namespaces plugin commands (`/termchart:diagram`). For a plain `/diagram`, drop a -one-line user command: +Claude Code namespaces plugin commands (`/termchart:diagram-remote`). For a plain `/diagram`, +drop a one-line user command that draws on the viewer: ```bash mkdir -p ~/.claude/commands cat > ~/.claude/commands/diagram.md <<'EOF' --- -description: Render a diagram as terminal ASCII via termchart -argument-hint: [mermaid source OR a description of the diagram you want] +description: Draw a diagram on the termchart live viewer +argument-hint: [a description of the diagram you want] --- -Render the following as aligned terminal text with the `termchart` CLI, following the -`termchart` skill: write Mermaid in the supported subset, `termchart lint` it, then -`termchart --ascii --color none` it and paste the output verbatim. +Push the following to the termchart viewer, following the `diagram-recipes` skill: pick the +right rich type (component / flow / vegalite / panes / …), author its JSON, and +`termchart push --type …`. $ARGUMENTS EOF diff --git a/packages/cli/README.md b/packages/cli/README.md index 6c55bfe..ae4d435 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -1,12 +1,13 @@ # termchart -Diagrams for coding agents, two ways: - -- **In the terminal** — deterministic **Mermaid → ASCII/Unicode** that pastes cleanly into - PRs, issues, and chat. No PNGs, no browser, no Mermaid handoff. -- **To a live viewer** — `termchart push` / `termchart status` send rich, native visuals - (React Flow, Vega-Lite, Mantine UI, markdown, panes) and progress overlays to a browser tab - you run locally or deploy. See the [repo](https://github.com/ivanmkc/termchart). +Diagrams for coding agents: + +- **To a live viewer (the focus)** — `termchart push` / `termchart status` send rich, native + visuals (React Flow, Vega-Lite, Mantine UI, markdown, panes) and progress overlays to a + browser tab you run locally or deploy. See the [repo](https://github.com/ivanmkc/termchart). +- **In the terminal (deprecated)** — a deterministic **Mermaid → ASCII/Unicode** renderer + (`termchart `) is still bundled for backward compatibility, but it's no longer the + focus; prefer the viewer. Terminal rendering is built on [`beautiful-mermaid`](https://github.com/lukilabs/beautiful-mermaid), a synchronous no-DOM grid diff --git a/packages/cli/package.json b/packages/cli/package.json index 1f51b4a..54ad03d 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -1,7 +1,7 @@ { "name": "@ivanmkc/termchart", "version": "0.7.0", - "description": "Push native diagrams, charts, dashboards & live status to the termchart viewer (browser/iPad) in real time — the CLI for the live canvas your AI draws on; also renders deterministic Mermaid → ASCII/Unicode in the terminal.", + "description": "Push native diagrams, charts, dashboards & live status to the termchart viewer (browser/iPad) in real time — the CLI for the live canvas your AI draws on. (Also bundles a deprecated Mermaid → ASCII/Unicode terminal renderer.)", "type": "module", "bin": { "termchart": "dist/cli.js" @@ -38,12 +38,13 @@ "url": "git+https://github.com/ivanmkc/termchart.git" }, "keywords": [ - "mermaid", - "ascii", - "terminal", + "viewer", "diagram", + "react-flow", + "vega-lite", + "dashboard", + "charts", "cli", - "unicode", - "flowchart" + "mermaid" ] } diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts index 2b721c3..7f99960 100644 --- a/packages/cli/src/cli.ts +++ b/packages/cli/src/cli.ts @@ -23,11 +23,9 @@ import { VERSION } from "./version.js"; const DEFAULT_NON_TTY_WIDTH = 80; -const USAGE = `termchart — deterministic Mermaid → ASCII/Unicode for terminals +const USAGE = `termchart — push rich diagrams to a live viewer (browser / iPad) Usage: - termchart [file] Render a Mermaid file, or stdin if omitted - termchart lint [file] Check source is within the renderable subset termchart serve [flags] Start a local viewer + print its URL and env exports (--port --token --wsid --bucket) termchart begin [flags] Show a scope as "composing" instantly — placeholder + focus + loader in one call (--project --agent --description) termchart push [flags] Push a diagram to the remote viewer (--project --agent --type --description --focus [--schema to make it template-able]) @@ -45,7 +43,11 @@ Usage: termchart run Refresh a scheduled board now — enforce lifecycle, assemble its prompt + run its agent, which pushes the board (--timeout , default 600) termchart --version -Render flags: +Deprecated (terminal Mermaid → ASCII render — prefer the viewer above): + termchart [file] Render a Mermaid file, or stdin if omitted + termchart lint [file] Check source is within the renderable subset + +Deprecated terminal-render flags: --ascii Pure ASCII (+,-,|) instead of Unicode box-drawing --safe, --portable Alias for --ascii — guaranteed alignment in any terminal (Unicode box glyphs are ambiguous-width; width-2 terminals misalign) @@ -236,6 +238,14 @@ export function main(argv: string[]): number { return 3; } + // The terminal Mermaid → ASCII renderer (and its lint) is deprecated: termchart is now a + // viewer-first tool. Still functional for backward compatibility, but nudge to the viewer. + // Notice goes to stderr so it never contaminates the rendered output on stdout. + process.stderr.write( + "termchart: the terminal Mermaid → ASCII renderer is deprecated — prefer the viewer " + + "(`termchart serve`, then `termchart push`). See the README.\n", + ); + if (args.command === "lint") { const result = lint(source); for (const w of result.warnings) process.stderr.write(`warning: ${w}\n`); diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 1e0341d..5493ead 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,23 +1,21 @@ { "name": "termchart", "displayName": "termchart", - "description": "A live canvas your AI draws on. Instead of walls of text, your agent pushes rich, native visuals to a browser tab / iPad / second screen in real time — React Flow graphs (architecture, sequence, call-graph, ER/class, state machine, PR-review, journeys, recursion trees), Vega-Lite charts (incl. scientific + Big-O), Mantine UI dashboards & product comparisons, deep-code walkthroughs, markdown, and split panes — with animated edges and live status overlays (toasts, progress bars, loaders). Deterministic Mermaid→ASCII/Unicode is the terminal fallback. Ships persona recipes, a showcase gallery, fullscreen panes, and a collapsible sidebar. Adds /termchart commands + skills, backed by the termchart CLI.", - "version": "0.14.0", + "description": "A live canvas your AI draws on. Instead of walls of text, your agent pushes rich, native visuals to a browser tab / iPad / second screen in real time — React Flow graphs (architecture, sequence, call-graph, ER/class, state machine, PR-review, journeys, recursion trees), Vega-Lite charts (incl. scientific + Big-O), Mantine UI dashboards & product comparisons, deep-code walkthroughs, markdown, and split panes — with animated edges and live status overlays (toasts, progress bars, loaders). Ships persona recipes, a showcase gallery, fullscreen panes, and a collapsible sidebar. Adds /termchart commands + skills, backed by the termchart CLI. (A deterministic Mermaid→ASCII/Unicode terminal renderer is still bundled but deprecated.)", + "version": "0.15.0", "author": { "name": "Ivan Cheung" }, "repository": "https://github.com/ivanmkc/termchart", "license": "MIT", "keywords": [ - "mermaid", - "ascii", - "unicode", - "diagram", - "terminal", - "flowchart", + "viewer", "react-flow", "vega-lite", - "viewer", - "charts" + "dashboard", + "charts", + "diagram", + "mantine", + "ipad" ] } diff --git a/plugin/commands/diagram.md b/plugin/commands/diagram.md deleted file mode 100644 index 5f2f492..0000000 --- a/plugin/commands/diagram.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -description: Render a diagram as terminal ASCII/Unicode via the termchart CLI -argument-hint: [mermaid source OR a description of the diagram you want] ---- - -The user wants a diagram shown as ASCII/Unicode text (not an image) using the -`termchart` CLI. Invoked as `/termchart:diagram`. - -Input: -$ARGUMENTS - -Do this: -1. If the input is already Mermaid source, use it as-is. Otherwise, write Mermaid - for what the user described, staying within termchart's supported subset - (flowchart, sequenceDiagram, stateDiagram-v2, classDiagram, erDiagram, - xychart-beta). Avoid sequence notes/loops/alt/opt — they are not rendered. -2. Lint it: pipe the source to `termchart lint`. If it exits non-zero, fix the - header/grammar and try again. -3. Render to a file with `--ascii --color none`: - `termchart --ascii --color none diagram.mmd > /tmp/diagram.txt` (or via heredoc). - ASCII (`+ - |`) is used by default because it stays aligned in **any** terminal, - regardless of its East-Asian ambiguous-width setting; Unicode box-drawing can - render double-width and misalign. If the user explicitly asks for Unicode/box - characters, drop `--ascii` (and optionally add `--rounded`). -4. **Read `/tmp/diagram.txt` and paste its exact contents into your reply** inside - a fenced code block. - -CRITICAL: never leave the diagram as raw command/tool output — harnesses collapse -long output behind a `+N lines` fold and the user sees a broken fragment. The -diagram only displays correctly when reproduced verbatim in your message. Copy it -byte-for-byte; do not summarize or re-draw it. - -If a diagram is too wide/tall, add `--padding-x 2 --padding-y 1` and/or shorten -node labels. See the `termchart` skill for the full grammar and flags. If -`termchart` is not on PATH, tell the user to run `npm i -g @ivanmkc/termchart`. diff --git a/plugin/skills/diagram-recipes/SKILL.md b/plugin/skills/diagram-recipes/SKILL.md index 63b6b34..225454f 100644 --- a/plugin/skills/diagram-recipes/SKILL.md +++ b/plugin/skills/diagram-recipes/SKILL.md @@ -14,6 +14,64 @@ Push a type with `termchart push --type --description "" --agent --type --description "" board.json --focus`. +The per-type detail files + `examples/` below add richer knobs (zones, swimlanes, legends, …), +but the shapes above are enough to draw a correct diagram right now. + **No viewer reachable? Run `termchart serve`, export the printed vars, retry.** If `push`/`status`/ `patch`/`list`/`pull` exits **4** — *"no termchart viewer configured"* (`TERMCHART_VIEWER_URL` unset) or *"cannot reach the termchart viewer at …"* (the URL is set but the server is down) — spin up a @@ -51,7 +109,7 @@ step-by-step / live-evolving views. | `datatable` | a sortable table with **Copy** (TSV → Sheets/Excel) + **Download CSV** | `{title?,columns,rows,note?}` | exact tabular data the human will read precisely or pull into a spreadsheet | | `markdown` | formatted prose (GFM, raw HTML) | markdown text | notes, summaries, docs | | `panes` | a split layout | `{layout,panes:[{title?,type,content}]}` | several of the above side-by-side/stacked | -| `mermaid` / `text` | ASCII/Unicode (terminal-style) | mermaid source / text (`ansi` is an alias of `text`) | low-fidelity, monospace | +| `mermaid` / `text` | ASCII/Unicode (terminal-style) | mermaid source / text (`ansi` is an alias of `text`) | **last-resort fallback only** — low-fidelity monospace; always prefer a rich type above | ## Choose the diagram (decision guide) @@ -70,7 +128,7 @@ type + the knobs that make it read, and adapt the named recipe (in `examples/`). | Step an algorithm live (search / traversal / sort) | `flow` `change` tiles + `legend`; push once, then `patch` (`setNodeData`) one step at a time, recoloring the active element in place | `binary-search` (array, `LR`) · `bfs-traversal` (graph, `TB`) | | SQL / query plan | `flow` cost-colored operator tree (`TB`) | `query-plan` | | Call graph / call hierarchy / "how X calls Y" (incl. before/after) | `calltree` — emit ONE tree (`roots[]` with `children`); the viewer toggles a compact diff **outline** ⇄ a dagre **graph**. Set `change` per node (`added`/`removed`/`modified`) for a before-after. Never emit positions. | `call-hierarchy.calltree` | -| Sequence / protocol / handshake | **`mermaid`** `sequenceDiagram` — renders as clean, aligned Unicode lifelines (no hand-positioning). Prefer this over the legacy hand-placed `flow` lifelines. | `sequence` | +| Sequence / protocol / handshake | `flow` **`"layout":"manual"`** hand-placed lifelines (`lifeline`+`point` nodes) — a rich native diagram; or `mermaid` `sequenceDiagram` as a quick low-fidelity fallback | `sequence` | | State machine / lifecycle | `flow`, labeled transition edges (`TB`) | `state-machine` | | ER / schema | `flow` **entity** nodes (typed `fields`), `TB` | `er-diagram` | | Class / type hierarchy | `flow` **entity** nodes, `BT` (parents on top) | `class-diagram` | diff --git a/plugin/skills/termchart/SKILL.md b/plugin/skills/termchart/SKILL.md deleted file mode 100644 index 597a89d..0000000 --- a/plugin/skills/termchart/SKILL.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -name: termchart -description: Use when you want to show a diagram (flowchart, sequence, state, class, ER, or xy chart) directly in the terminal/chat as ASCII or Unicode text instead of an image. Renders Mermaid deterministically via the `termchart` CLI — no PNGs, no browser, no Mermaid handoff. ---- - -# 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. - -> **Want a rich, interactive diagram on a live screen/iPad instead of inline text?** Use the -> remote viewer (`/termchart:diagram-remote` + the `diagram-recipes` skill). If no viewer is -> configured, run **`termchart serve`** to spin up a local one — it prints the URL to open and the -> `export TERMCHART_VIEWER_URL=… TERMCHART_VIEWER_TOKEN=…` lines to paste before pushing. - -## Choosing the diagram type - -Pick the type that fits what the user wants to show. The type is declared in the -Mermaid header, so choosing it *is* choosing the first line of the source. - -| If they want to show… | Use | Header | -|---|---|---| -| branching logic / a process / a decision | flowchart | `graph TD` (top-down, preferred) | -| who-calls-whom over time, a protocol/handshake | sequence | `sequenceDiagram` | -| a lifecycle / status transitions | state | `stateDiagram-v2` | -| types, inheritance, fields/methods | class | `classDiagram` | -| a data model / tables & relationships | ER | `erDiagram` | -| metrics / counts / trends | xy chart | `xychart-beta` | - -**Ask only when genuinely ambiguous.** If the request clearly implies one type, -just render it. Only ask the user when two types fit equally well (e.g. "show the -order process" could be a flowchart *or* a state diagram). Don't interrogate for -obvious cases. - -## Choosing the layout (adapt to the graph — don't rely on a fixed default) - -Look at the graph you're about to draw and pick options to fit it, rather than -always using the defaults: - -- **Direction (prefer top-down):** default to `graph TD` — it's the flowchart convention - and reads top-to-bottom, and wide fan-out (many siblings) spreads horizontally. Switch to - `graph LR` only when TD doesn't fit: a long linear chain (A→B→C→D) is shorter and more - readable wide, and a very tall TD graph can overflow the terminal. If one direction - overflows, try the other. -- **Fit the target width:** in a terminal/chat, the readable width is ~80 cols. Use - `--fit` (auto-targets terminal width, or 80 when piped) or `--width ` so the - diagram doesn't wrap. If `--fit` warns it can't fit, switch direction, shorten - node labels, or split the diagram. -- **Spacing:** the default spacing is already generous — only override - `--padding-x/--padding-y` to *tighten* a diagram that's too tall/wide (e.g. - `--padding-y 1` on a tall `TD` chain), not to fix the default. -- **Style:** `--rounded` for softer corners; `--color none` for anything pasted - into chat/PRs/issues (ANSI escapes corrupt text there); reserve color modes for a - live interactive terminal. - -Measure before pasting: if the rendered output is wider than ~80 cols or very tall, -re-render with a different direction / `--fit` / tighter padding before showing it. - -## 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. - -```bash -# 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: - -```bash -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 ` | Color output (default `auto`: color on a TTY, plain when piped) | -| `--theme ` | One of: `zinc-light`, `zinc-dark`, `tokyo-night`, `catppuccin-mocha`, `nord`, `dracula`, `github-dark`, `one-dark`, … | -| `--padding-x ` / `--padding-y ` | Spacing between nodes | -| `--rounded` | Rounded corners/elbows (`╭╮╰╯`); incompatible with `--ascii` | -| `--fit` | Auto-compact spacing to fit terminal width (or 80 cols when piped) | -| `--width ` | Fit within `` 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 supported (avoid — `lint` errors, render refuses) - -In sequence diagrams these are **unsupported** and make both `lint` and render exit -1 (the renderer mangles them rather than omitting them cleanly): `note over/left -of/right of`, `loop`, `alt`, `opt`, `par`, `activate`/`deactivate`. Keep sequence -diagrams to plain messages (`A->>B: msg`). If you need that structure, model it as -a flowchart instead. - -### Authoring tips for clean output (from a UX comprehension study) - -- **ER relationship labels render in full.** Multi-word labels (e.g. `"ordered in"`) - are supported; the renderer widens the inter-entity gap to fit them. (Very long - labels widen the whole diagram — use `--fit` if it overflows.) -- **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. -- **Avoid fullwidth characters (CJK / emoji) in labels.** The renderer's grid - allots one cell per character, so wide glyphs misalign box borders. `lint` warns - when they're present. Prefer ASCII labels for clean alignment. - -## 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.