# Trace: Add and Preview Drawing Skill in Terminal

Agent: pi | Model: Claude Haiku 4.5 (latest) | Project: .pi

---

## User

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

can you add this skill to yourself

## Assistant

## Assistant

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

## Assistant

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

## Assistant

## Assistant

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

## Assistant

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

## Assistant

Now write all the reference files in parallel:

## Assistant

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.

## User

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

## Assistant

## Assistant

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

## Assistant

## Assistant

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
const image = new Image(base64Data, "image/png", theme, { maxWidthCells: 80, maxHeightCells: 24 });
```

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:

1. **A converter** — something that takes `.excalidraw` JSON → PNG/SVG. Options:
   - [`@excalidraw/excalidraw`](https://github.com/excalidraw/excalidraw) (needs a browser/headless Chrome)
   - [`excalidraw-cli`](https://github.com/tommywalkie/excalidraw-cli) (headless Chrome wrapper)
   - Puppeteer/Playwright scripting excalidraw.com's export
   
2. **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).

## User

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

## Assistant

## Assistant

Let me investigate the environment and excalidraw-cli first.

## Assistant

## Assistant

## Assistant

## Assistant

## Assistant

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

## Assistant

## Assistant

## Assistant

## User

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

## Assistant

## Assistant

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

## Assistant

## Assistant

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

## Assistant

Now test the render script first before building the extension:

## Assistant

## Assistant

## Assistant

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

## Assistant

## Assistant

## Assistant

## Assistant

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

## Assistant

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

## Assistant

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

## Assistant

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

## Assistant

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

---

## How it works

**`render.ts`** — A standalone Bun/Playwright script that:
1. Loads React + `@excalidraw/excalidraw` from jsDelivr CDN into a headless Chromium page
2. Calls `exportToBlob()` on the diagram elements
3. 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.

## User

try it out. the reload worked

## Assistant

## Assistant

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

## Assistant

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?

## User

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

## Assistant

## Assistant

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

## Assistant

## Assistant

## Assistant

## Assistant

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

## Assistant

## Assistant

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

## Assistant

Now swap the TUI component to use sixel:

## Assistant

Verify it still builds clean:

## Assistant

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.

## User

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

## Assistant

## Assistant

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.

## Assistant

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

## Assistant

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

## Assistant

Verify the build is clean:

## Assistant

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.).

## User

try it out

## Assistant