Public

Add and Preview Drawing Skill in TerminalPublic

The user wanted to add a drawing skill to the assistant and be able to view diagrams directly in the terminal interface. After installing the skill and attempting to render images in the terminal, technical limitations and errors prevented direct display. The assistant then adjusted the approach to export diagrams as image files for viewing outside the terminal, ensuring the user can create and access drawings successfully.

Agent

Model

Claude Haiku 4.5 (latest)

Shared

Mar 1, 9:32 PM

Messages67

https://github.com/rnjn/cc-excalidraw-skill

can you add this skill to yourself

I'll start by reading the relevant skill documentation and fetching the GitHub repo simultaneously.

Now let me fetch the GitHub repository to see its contents:

The repo has 5 files. Let me fetch all the reference docs simultaneously:

I now have everything I need. Let me create the skill directory with all the files:

Now write all the reference files in parallel:

The skill is installed. Here's a summary of what was done:

Installed: excalidraw skill at ~/.pi/agent/skills/excalidraw/

excalidraw/
├── SKILL.md                          # Main skill file (auto-loaded on trigger)
└── references/
    ├── best-practices.md             # Design tips, color theory, typography
    ├── diagram-patterns.md           # Professional patterns (flowcharts, sequence, mind maps, etc.)
    ├── element-reference.md          # Full property reference for all element types
    └── examples.md                   # Complete working JSON templates

What this skill enables:

Creating .excalidraw JSON files programmatically for flowcharts, architecture diagrams, sequence diagrams, mind maps, ERDs, wireframes, and more
Full knowledge of Excalidraw's element schema (rectangles, ellipses, diamonds, arrows, text, lines, frames)
Color palettes, styling conventions, arrow bindings, and grouping

Pi will automatically activate this skill whenever you ask to create a diagram, flowchart, architecture drawing, or anything in Excalidraw format. Use /reload if you're in an active Pi session to pick it up immediately.

is there a way to see the diagram in the TUI?

Let me check the Pi TUI documentation to see what's possible.

Not directly — but here's the full picture:

What Pi's TUI Can Do

Pi has an Image TUI component (in @mariozechner/pi-tui) that renders images using terminal graphics protocols (Kitty, iTerm2, Ghostty, WezTerm). It takes base64 image data:

typescript

So the rendering capability is there — but only for image formats (PNG, etc.), not for .excalidraw JSON directly.

The Gap

An .excalidraw file is JSON that needs a renderer to become a visual. To bridge that gap you'd need:

A converter — something that takes .excalidraw JSON → PNG/SVG. Options:
- @excalidraw/excalidraw (needs a browser/headless Chrome)
- excalidraw-cli (headless Chrome wrapper)
- Puppeteer/Playwright scripting excalidraw.com's export
A Pi extension — calls the converter, takes the resulting PNG, and shows it via the Image component as an overlay or widget

What You'd Get

A /preview-excalidraw <file.excalidraw> command (or auto-preview after generation) that pops up the rendered diagram in-TUI — but only in terminals that support the Kitty graphics protocol (Kitty, Ghostty, WezTerm, iTerm2). Standard terminals would see nothing or garbage.

TL;DR: No native support exists, but it's buildable as an extension. Want me to build one? I'd need to know: which terminal you use (to confirm graphics protocol support) and whether you're okay installing something like excalidraw-cli (which requires Chrome/Puppeteer).

ok try it out. im using tmux, u can use the excalidraw-cli with bun

Let me investigate the environment and excalidraw-cli first.

Let me test the export command and then look at how Pi renders images:

dont worry too much about the terminal support. just write it out assuming defaults

Good. Now I have everything I need. Let me build the extension:

Wait, there's a bug with the await in the IIFE. Let me fix the render script properly:

Now test the render script first before building the extension:

The scripts race with the IIFE. Let me fix the render script to use addScriptTag which awaits each script's load:

It works — 7060 chars of base64 PNG. Now let me build the Pi extension:

Now let's verify the extension loads cleanly with a quick type-check:

Builds clean. Let's do a quick end-to-end test of the full render → display pipeline to make sure the PNG is valid:

Valid PNG, 220×120px. Now let's do the final sanity check on the full extension structure:

Everything is in place. Here's what was built:

How it works

render.ts — A standalone Bun/Playwright script that:

Loads React + @excalidraw/excalidraw from jsDelivr CDN into a headless Chromium page
Calls exportToBlob() on the diagram elements
Prints the base64 PNG to stdout

index.ts — The Pi extension that:

Enables tmux passthrough (tmux set -g allow-passthrough on) automatically before rendering
Runs render.ts as a subprocess
Builds a custom TUI component that emits raw Kitty image sequences using encodeKitty from @mariozechner/pi-tui (bypassing the tmux capability detection)
Presses any key to close the preview overlay

Usage

Manually:

/preview-diagram path/to/diagram.excalidraw

Automatically by the AI: After creating a .excalidraw file, Claude can call the preview_excalidraw tool directly to show it to you without any extra prompting.

⚠️ One requirement

Your outer terminal (the one running tmux) must support the Kitty graphics protocol — Kitty, Ghostty, WezTerm, or iTerm2 all work. Run /reload in Pi to pick up the extension, then try it with /preview-diagram on a diagram.

try it out. the reload worked

Let me create a quick test diagram and fire the preview tool!

Did the image pop up? You should have seen two rounded rectangles connected by an arrow — "Hello from Pi!" → "It works! 🎉".

If nothing appeared, the most likely culprit is the outer terminal not supporting the Kitty graphics protocol. What terminal emulator are you running tmux inside?

preview_excalidraw
Previewed /tmp/hello.excalidraw

Rendering /tmp/hello.excalidraw …

i saw this. didnt see the image. we can try to fix it step by step. lets try to render any image to the terminal first

Good, let's debug step by step. First let's check the environment and try blasting a raw Kitty sequence straight to the terminal:

DISPLAY=:0 and ImageMagick supports sixel! Let me check if xterm has sixel enabled and test a raw sixel render:

Sixel bytes look correct (\x1bP DCS prefix). Let me update the extension to try sixel via ImageMagick, since that's what xterm understands:

Now swap the TUI component to use sixel:

Verify it still builds clean:

Good. Do /reload in Pi then run:

/preview-diagram /tmp/hello.excalidraw

The extension now tries sixel (xterm's native format) via ImageMagick before falling back to Kitty. Since tmux allow-passthrough is already on and DISPLAY=:0, the DCS sixel sequences should pass through tmux to xterm. Let me know what you see — even garbled output is useful info.

file:///home/lakshyaag/.bun/install/global/node_modules/@mariozechner/pi-tui/dist/tui.js:854
throw new Error(errorMsg);
^

Error: Rendered line 1162 exceeds terminal width (15867 > 144).

This is likely caused by a custom TUI component not truncating its output.
Use visibleWidth() to measure and truncateToWidth() to truncate lines.

Debug log written to: /home/lakshyaag/.pi/agent/pi-crash.log
at TUI.doRender (file:///home/lakshyaag/.bun/install/global/node_modules/@mariozechner/pi-tui/dist/tui.js:854:23)
at file:///home/lakshyaag/.bun/install/global/node_modules/@mariozechner/pi-tui/dist/tui.js:281:18
at process.processTicksAndRejections (node:internal/process/task_queues:85:11)

this is the error. i thinkw e can skip rendering the preview in the terminal, but ewnsure that the skill knows how to export an excalidraw file to png and save it in the same directory

Got it. Let me strip the TUI display out entirely and make it a clean export-to-PNG tool, then update the skill to always use it.

Now update the skill to always export after creating a diagram:

Also update the preview_excalidraw reference at the bottom of the skill:

Verify the build is clean:

Do /reload and then ask me to draw something — I'll write the .excalidraw file and immediately call export_excalidraw, which saves the PNG right next to it. You can open the PNG in any image viewer (xdg-open, display, etc.).

try it out