Excalidraw Copilot 🎨
A VS Code extension that generates beautiful, editable diagrams from natural language using your GitHub Copilot subscription. No API keys needed — just describe what you want.
✨ Features at a Glance
📸 See It in ActionChat Participant —
|
| Command | Example | What It Does |
|---|---|---|
| (none) | @excalidraw design a Twitter architecture |
Auto-detects the best pipeline and generates a diagram |
/new |
@excalidraw /new coffee brewing process |
Start a fresh diagram (ignores previous conversation) |
/diagram |
@excalidraw /diagram how cheese is made |
Force the Semantic DSL pipeline |
/architecture |
@excalidraw /architecture microservices with API gateway |
Force the Mermaid pipeline |
/file |
@excalidraw /file #file:src/server.ts |
Diagram a file's internal structure (classes, functions, imports) |
/folder |
@excalidraw /folder src/api |
Diagram a folder's architecture (scans code, dependencies, imports) |
/project |
@excalidraw /project |
Diagram the entire workspace project |
/selection |
@excalidraw /selection |
Diagram the current code selection (select code first) |
Pipeline Override (--mermaid / --dsl)
By default, /file uses DSL and /folder//project use Mermaid. Override with a flag:
@excalidraw /folder src/models --dsl → DSL instead of Mermaid
@excalidraw /project --dsl → DSL instead of Mermaid
@excalidraw /file --mermaid #file:server.ts → Mermaid instead of DSL
@excalidraw /selection --mermaid → Mermaid for selected code
@excalidraw draw a coffee process --mermaid → force Mermaid on free-text
No flag = sensible default for that command.
Conversational Refinement
After generating a diagram, just keep typing — follow-up messages automatically refine the current diagram:
User: @excalidraw design a microservices architecture
Bot: ✅ Diagram ready! 8 nodes, 7 connections
💬 Type any changes you want or use /new to start fresh.
User: add a caching layer between API and database
Bot: ✅ Diagram updated!
User: /new how to make cheese step by step
Bot: ✅ Diagram ready! (fresh diagram, previous one ignored)
Followup suggestions are contextual — architecture diagrams suggest things like "Add a caching layer", while recipe/process diagrams suggest things like "Add ingredient quantities".
📋 Commands (Right-Click & Command Palette)
The classic flow uses the Command Palette and right-click context menus. It includes a model picker and pipeline picker (QuickPick dialogs).
| Command | How to Trigger | What It Does |
|---|---|---|
| Generate Diagram | Ctrl+Shift+P → "Generate Diagram" |
Free-text prompt → diagram |
| Diagram This Folder | Right-click folder in Explorer | Scans that folder's code, generates architecture |
| Diagram This Project | Right-click folder / Ctrl+Shift+P |
Scans entire workspace, full project architecture |
| Diagram This File | Right-click file in Explorer / editor | Diagrams a file's internal structure |
| Diagram This Selection | Select code → right-click in editor | Diagrams the selected code snippet |
| Open Canvas | Ctrl+Shift+P → "Open Canvas" |
Opens a blank Excalidraw canvas |
💾 Diagram Gallery
Every diagram you generate is automatically saved as an .excalidraw file in the .excalidraw-copilot/ folder of your workspace. A dedicated Excalidraw Diagrams panel appears in the Activity Bar (sidebar).
Auto-Save
- Enabled by default — disable in settings:
excalidraw-copilot.autoSave - Saves after initial generation and after refinement
- Fresh generation refinement overwrites the same file (same session)
- Gallery refinement saves as a copy with
-refinedsuffix (original preserved) - Filenames:
{prompt-slug}_{timestamp}.excalidraw
Gallery Actions
| Action | How | What it does |
|---|---|---|
| Open | Click diagram in gallery | Loads the diagram + offers refinement popup |
| Refine | Right-click → "Refine Diagram" | Opens diagram + focuses chat for natural refinement |
| Rename | Right-click → "Rename Diagram" | Rename the file |
| Delete | Right-click → "Delete Diagram" | Delete with confirmation |
| Reveal | Right-click → "Reveal in Explorer" | Opens the file location |
Refinement from Gallery
When you open a saved diagram, a "Any changes?" popup appears — same as after generation. You can describe changes and the LLM refines the diagram. The original file is preserved; the refined version saves as {name}-refined.excalidraw.
You can also refine through @excalidraw chat — the gallery sets refinement context automatically.
.excalidraw File Format
Files use standard Excalidraw JSON with additional metadata:
elements— Excalidraw shapes (empty for Mermaid diagrams)graph— Semantic DSL graph JSON (for DSL refinement)mermaidSyntax— Mermaid source code (for Mermaid refinement)metadata— prompt, pipeline, model, timestamp, node/connection counts
Custom Editor
Double-clicking any .excalidraw file in the Explorer opens it in the Excalidraw Copilot editor.
Git Integration
On first save, the extension asks whether to add .excalidraw-copilot/ to .gitignore (remembers your choice).
🎯 Complete Usage Guide
Two ways to use Excalidraw Copilot:
- Chat Participant — type
@excalidrawin the Copilot Chat panel. See the Chat Participant section above.- Command Palette / Right-click — classic flow with QuickPick dialogs. Detailed below.
Free-Text Prompts
Type anything — the extension figures out the best approach:
Draw the architecture of Twitter
How to make cheese step by step
Create a flowchart for user registration with email verification
Design a microservices system with API gateway and message queue
Smart Project Detection
Type prompts like "diagram this project" or "show the architecture of this app" in the prompt bar — the extension automatically scans your open workspace (files, dependencies, imports) and passes the real analysis to the LLM. No need to right-click.
Diagram Your Code (Folder)
- Right-click any folder in Explorer → "Excalidraw Copilot: Diagram This Folder"
- The extension deep-scans that folder's code:
- File structure and directory layout
- Component roles — entry points, controllers, services, models, components, state/stores, utilities
- Import/dependency graph — who imports whom
- External services — databases (PostgreSQL, MongoDB, Redis), queues (Kafka, RabbitMQ), cloud services
- HTTP endpoints — REST routes detected from code
- Frameworks — React, Express, NestJS, .NET, Flask, and more
- Infrastructure — Dockerfile, docker-compose analysis
- Supports:
.ts,.tsx,.js,.jsx,.py,.cs,.java,.go - The analysis is sent to the LLM — you get a diagram of your actual codebase, not a generic template
Diagram Entire Project
- Right-click any folder → "Excalidraw Copilot: Diagram This Project" (or use Command Palette)
- Always scans the entire workspace root — gives you the full project architecture with all layers, components, and connections
- Great for getting a high-level overview of a new codebase
Diagram a Single File
- Right-click a file → "Excalidraw Copilot: Diagram This File"
- Shows classes, interfaces, functions, inheritance, method calls, and external dependencies
Diagram a Code Selection
- Select code in the editor — a function, class, code block, or any lines
- Right-click → "Excalidraw Copilot: Diagram This Selection"
- Or use
@excalidraw /selectionin the Chat panel - Auto-detects the programming language for better prompts
- Great for understanding complex logic, visualizing control flow, or documenting tricky code
Sequence Diagrams
The Mermaid pipeline supports sequence diagrams out of the box. Three ways to get one:
- From chat — type
@excalidraw /architecture draw a sequence diagram of user authentication with JWT - From scratch — use "Generate Diagram", type a prompt like "Draw a sequence diagram of user authentication with JWT", and pick the Mermaid pipeline
- Via refinement — after any diagram, type "now show this as a sequence diagram" — works in both chat and the Command Palette feedback loop
Great for showing interactions between components, API call flows, and request/response patterns.
Conversational Refinement
After every diagram, you can refine by describing changes:
"Add a caching layer between API and database"
"Step 3 is wrong — it should be pasteurize not boil"
"Remove the queue and connect directly"
"Add a step after step 2 for validation"
"Group all the databases together"
In Chat: just keep typing — follow-up messages automatically refine the current diagram. Use /new to start fresh.
In Command Palette: a feedback popup appears after each diagram:
- Up to 10 refinement rounds per session
- Press Escape to finish — a "Continue Refining" notification lets you re-enter the loop anytime
- Step numbers are automatically renumbered when you add or remove steps
Model Selection
In Chat: select the model from the Chat panel's model dropdown (top of the chat window).
In Command Palette: a model picker appears before each generation:
- Claude Sonnet — ⭐ Recommended for architecture diagrams. Clean, well-structured output
- GPT-4o — ⭐ Also great for architecture. Fast and produces readable layouts
- Claude Opus — Best for detailed process diagrams and step-by-step flows. Can be too detailed for architecture (many nodes/connections), so prefer Sonnet or GPT-4o for system design
- Any other model available through your Copilot subscription
💡 Tip: For architecture diagrams ("Design Twitter", "Diagram this project"), use Sonnet or GPT-4o — they produce cleaner, more readable layouts. Save Opus for detailed process flows and tutorials where extra detail is a plus.
Pipeline Selection (Mermaid vs DSL)
In Chat: auto-detected from the prompt, or forced with /architecture, /diagram, --mermaid, --dsl.
In Command Palette: after choosing a model, you pick a rendering pipeline. The extension recommends one based on your prompt:
| 🎨 Semantic DSL | 🧜 Mermaid | |
|---|---|---|
| Best for | Process diagrams, recipes, tutorials | Architecture diagrams, system design |
| Output | Editable Excalidraw shapes | Native Mermaid preview → convert to Excalidraw |
| Detail | 15-30 nodes with emojis, colors, descriptions, pro tips | 15-25 nodes with subgraphs, clean layers |
| Speed | ~30-40 sec | ~15-20 sec |
| Layout | Custom grid engine with snake wrapping | Mermaid's dagre layout engine |
| Colors | Rich semantic palette (7 colors × 3 shades) | Per-node style directives (6 color categories) |
Mermaid Preview Mode
When using the Mermaid pipeline, diagrams render as native Mermaid first (better layout and arrow routing than direct conversion). The preview includes:
- Zoom —
Ctrl+Scrollto zoom in/out, or use the+/−buttons - Pan —
Alt+Dragor middle-click drag to pan around - Reset — Click the
%label or⊡button to reset zoom and pan - Export SVG — Download the diagram as a vector SVG file
- Export PNG — Download as a high-resolution PNG (2× for crisp output)
- Convert to Excalidraw — Click the green button to convert to editable Excalidraw elements
DSL Internals (For the Curious)
The Semantic DSL pipeline generates a JSON graph:
{
"title": "Twitter Architecture",
"direction": "TB",
"nodes": [
{"id": "gateway", "type": "service", "label": "API Gateway", "emoji": "🚪", "semanticColor": "primary"},
{"id": "redis", "type": "cache", "label": "Redis Cache", "emoji": "⚡", "semanticColor": "warning"}
],
"connections": [{"from": "gateway", "to": "redis", "style": "dashed"}]
}
Node types: service (blue), database (green), cache (orange), queue (purple), external (gray), user (cyan), process (yellow), decision (red diamond)
Semantic colors: primary (blue), secondary (purple), success (green), warning (amber), danger (red), info (cyan), neutral (gray)
🔧 Development
Build
npm install
npm run compile # Build extension (webpack)
npm run watch # Auto-rebuild on changes
Webview (React/Excalidraw)
cd webview-ui
npm install
npm run build # Production build (vite)
npm run dev # Dev mode with hot reload
Project Structure
src/
extension.ts # Commands, pipeline routing, feedback loops, auto-save, gallery
chat/
ChatParticipant.ts # @excalidraw Chat Participant — slash commands, refinement, selection
gallery/
DiagramStore.ts # Save/load/list/delete .excalidraw files, auto-save, gitignore prompt
GalleryProvider.ts # TreeView data provider for sidebar gallery, file watcher
editor/
ExcalidrawEditorProvider.ts # Custom editor for .excalidraw files
analysis/
folderAnalysis.ts # Folder/file/project/selection analysis, prompt builders, role detection
llm/
SemanticDiagramService.ts # Two-pass LLM generation (think → generate), refinement, Mermaid prompts
dsl/
types.ts # Semantic graph types (nodes, connections, groups)
prompt.ts # LLM system prompts with schema + examples
layout/
engine.ts # Grid layout, snake wrapping, arrow routing, decision sizing
render/
shapes.ts # Semantic graph → Excalidraw elements, decision diamond layout
styles.ts # Color palette (7 colors × 3 shades)
execution/
StateManager.ts # Canvas state management
webview/
WebViewPanel.ts # VS Code WebView panel management
types/
messages.ts # Extension ↔ WebView message protocol
webview-ui/
src/
App.tsx # React app: Excalidraw canvas + Mermaid preview mode
hooks/useMessageBridge.ts # WebView ↔ Extension messaging hook
docs/ # Plans and design documents
🐛 Troubleshooting
"GitHub Copilot is not available"
- Install the GitHub Copilot extension
- Sign in to GitHub in VS Code
- Make sure your Copilot subscription is active
Canvas not loading
- Check Output panel:
Ctrl+Shift+U→ "Excalidraw Copilot" - Open WebView DevTools:
Ctrl+Shift+P→ "Developer: Open Webview Developer Tools"
Diagram shows generic architecture (not my project)
- Use right-click → "Diagram This Folder" for code-aware analysis
- Or type
@excalidraw /projectin Chat, or "diagram this project" in the prompt bar — it auto-detects and scans your workspace - Check the Output channel for
Project prompt detection: true
Diagram looks wrong or incomplete
- Use the feedback loop to refine: "move X to the right", "add Y"
- Try a different model (Opus produces the most detailed results)
- Try the other pipeline (Mermaid vs DSL) for a different perspective
- Check the Output channel for the generated graph/Mermaid
Mermaid preview not rendering
- Open WebView DevTools to check for console errors
- Check the Output channel for the generated Mermaid syntax
Build errors on F5
- Run
npm run compilemanually to see actual errors - The "preLaunchTask errors" dialog is usually a false alarm — click Debug Anyway
⚠️ Known Limitations
- Mermaid → Excalidraw conversion quality — The "Convert to Excalidraw" button uses the third-party
@excalidraw/mermaid-to-excalidrawlibrary, which can produce degraded arrow routing, overlapping labels, and spacing issues compared to the native Mermaid preview. For best visual results, use the Mermaid preview mode (with zoom, pan, and SVG/PNG export) and only convert to Excalidraw when you need to hand-edit individual elements. - Complex DSL diagrams (20+ nodes) — Arrow overlaps can occur on dense diagrams with many cross-layer connections. Use the feedback loop to simplify or regroup.
- LLM variability — Results vary by model. Claude Opus produces the most detailed and accurate diagrams. Smaller models may oversimplify or hallucinate components.
🤝 Contributing
We welcome contributions! See CONTRIBUTING.md for architecture details, development setup, and known issues to work on.
Check out the open issues — look for the good first issue label if you're new.
📄 License
MIT
Made with ❤️ for developers who think visually.
⭐ Star on GitHub · 📦 Install from Marketplace