# Excalidraw AI — Local Diagram Generator

Generate rich, annotated [Excalidraw](https://excalidraw.com) diagrams from plain English — entirely on your own machine. No cloud, no API keys, no internet required after setup.

Describe a topic and the tool runs a 4-phase LLM pipeline to produce a **paper-like vertical document**: hierarchical tree diagrams, per-node annotations, and a full educational summary — all saved as a `.excalidraw` file ready to open.

---

## One-Line Install

**Linux (Ubuntu · Debian · Fedora · Arch · Void) and macOS:**
```bash
curl -fsSL https://raw.githubusercontent.com/jeel00dev/exclalidraw_mcp/main/install.sh | bash
```

**Windows (PowerShell, run as Administrator):**
```powershell
iwr -useb https://raw.githubusercontent.com/jeel00dev/exclalidraw_mcp/main/install.ps1 | iex
```

The installer handles everything automatically — no manual steps:
- Installs Docker (per-distro: apt / dnf / pacman / xbps / brew)
- Clones this repo to `~/.excalidraw-ai/`
- Downloads the AI model (~1.2 GB, cached after first run)
- Pulls Docker images and starts all services
- Installs the `excalidraw-ai` command

---

## Usage

After install, generate diagrams with one command:

```bash
excalidraw-ai "machine learning pipeline" --type mindmap
excalidraw-ai "TCP/IP network stack" --type architecture --out tcp_ip
excalidraw-ai "user login with OAuth2 and JWT" --type flowchart
excalidraw-ai "photosynthesis in plants" --type mindmap --out plants
```

Then open **http://localhost:3333** in your browser, press `Ctrl+O`, and load the file from `~/excalidraw_diagrams/`.

### Service commands

```bash
excalidraw-ai start     # start all services
excalidraw-ai stop      # stop all services
excalidraw-ai status    # show container status + health
excalidraw-ai update    # pull latest code + images
excalidraw-ai help      # show all options
```

---

## What Gets Generated

Each diagram is a **vertical document** (reads top-to-bottom like study notes):

```
─── Section 1: Encoder ──────────────────────────────
  [Tree diagram — root → groups → detail nodes]

  • Input Embedding: Converts token IDs to dense vectors...
  • Positional Encoding: Adds position info since attention...
  ...

─── Section 2: Decoder ──────────────────────────────
  [Tree diagram]

  • notes...

─── Educational Summary ─────────────────────────────
  The Transformer architecture introduced in "Attention is All
  You Need" (2017) replaced recurrence with self-attention...
```

**Diagram structure:**
- **2-3 sections** per topic (auto-decomposed by the LLM)
- **Hierarchical tree** per section: root → category nodes → detail leaves
- **Shape variety**: rectangles (components), ovals (actors/terminals), diamonds (decisions)
- **Compact notes block** below each tree — 1-2 sentence explanation per node
- **Educational summary** — 400-500 word prose at the bottom

**Variable complexity** — the number of shapes scales with the topic:
- Simple topic (3-5 components) → 5-8 shapes per section
- Complex topic (many layers) → 12-16 shapes per section

---

## Examples

### Transformer Architecture
```bash
excalidraw-ai "attention is all you need encoder decoder" --type architecture
```
Produces two sections (Encoder, Decoder), each with a 3-level tree covering input embedding, positional encoding, multi-head attention, feed-forward networks, and normalization layers.

### Machine Learning Mindmap
```bash
excalidraw-ai "machine learning supervised unsupervised reinforcement" --type mindmap
```
Three sections, one per paradigm, each branching into algorithms, use cases, and key concepts.

### Network Stack
```bash
excalidraw-ai "TCP/IP network stack" --type architecture
```
Generates the full layer hierarchy: Application → Transport → Internet → Network Access, with specific protocols (HTTP, TCP, UDP, IP, Ethernet) as leaf nodes.

### OAuth2 Login Flow
```bash
excalidraw-ai "user login with OAuth2 JWT session management" --type flowchart
```
Decision-tree flowchart with diamond nodes for validation steps, success/failure branches, and JWT issuance.

---

## Diagram Types

| Type | Best for |
|---|---|
| `flowchart` | Processes, decision trees, algorithms |
| `mindmap` | Study notes, topic overviews, brainstorming |
| `architecture` | System designs, service maps, layer diagrams |
| `sequence` | API calls, message passing, protocol flows |
| `erd` | Database schemas, entity relationships |

---

## How It Works

```
Your description
      │
      ▼
Phase 0 — Decompose   topic → 2-3 focused sub-sections    (~150 tokens)
      │
      ▼  (per section)
Phase 1 — Structure   SHAPE + ARROW lines (tree hierarchy)  (~800 tokens)
Phase 2 — Notes       1-2 sentence annotation per shape     (~600 tokens)
      │
      ▼
Phase 3 — Summary     educational prose paragraph           (~600 tokens)
      │
      ▼
Layout engine → vertical document → .excalidraw file
```

Each phase is a separate, focused LLM call — works reliably on small (1.5B–7B) models.

**Layout engine:**
- Sections stack top-to-bottom (document layout, not a spreadsheet)
- Tree layout uses subtree-width centering — children center under their parent
- Dynamic column stride scales the tree to fit the 1400px document width
- Notes appear as a bullet-list block below each section's tree

---

## Docker Stack

The full stack runs as three Docker services:

| Service | Image | Port | Role |
|---|---|---|---|
| `excalidraw-ui` | `excalidraw/excalidraw:latest` | 3333 | Web viewer |
| `llama-server` | `ghcr.io/ggerganov/llama.cpp:server` | 8080 | LLM inference |
| `generator` | built from `Dockerfile` | — | CLI (run on demand) |

Start / stop manually:
```bash
cd ~/.excalidraw-ai
docker compose up -d excalidraw-ui llama-server
docker compose run --rm generator "your topic" --type mindmap
docker compose down
```

---

## Configuration

Edit `~/.excalidraw-ai/.env` to customise:

```bash
# AI model (filename inside MODELS_DIR)
MODEL_FILE=qwen2.5-1.5b-instruct-q5_k_m.gguf

# Storage paths
MODELS_DIR=/home/you/.excalidraw-ai/models
DIAGRAMS_DIR=/home/you/excalidraw_diagrams

# Ports
EXCALIDRAW_PORT=3333
LLAMA_PORT=8080

# If you already have llama-server running elsewhere:
# LLAMA_BASE_URL=http://192.168.1.10:8080
```

### Bring your own model

If you already have a GGUF model (e.g. DeepSeek-Coder-6.7B), copy or symlink it:
```bash
cp /path/to/your/model.gguf ~/.excalidraw-ai/models/
# Then update .env:
MODEL_FILE=your_model.gguf
docker compose restart llama-server
```

Recommended models:

| Model | Size | Notes |
|---|---|---|
| Qwen2.5-1.5B-Instruct Q5_K_M | 1.2 GB | Default auto-download — fast |
| Qwen2.5-3B-Instruct Q4_K_M | 1.9 GB | Better quality, still small |
| DeepSeek-Coder-6.7B-Instruct | 4 GB | Strong structured output |
| Qwen2.5-7B-Instruct Q4_K_M | 4.5 GB | Best quality |

---

## MCP Server (Claude Desktop / Cursor)

If you use Claude Desktop or Cursor, you can generate diagrams directly from chat.

**Linux** — edit `~/.config/claude/claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "excalidraw": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/exclalidraw_mcp", "run", "excalidraw-mcp"]
    }
  }
}
```

**macOS** — edit `~/Library/Application Support/Claude/claude_desktop_config.json` (same content).

Restart Claude Desktop, then ask: *"Generate a mindmap about photosynthesis"*

Available MCP tools:

| Tool | Description |
|---|---|
| `generate_diagram(description, diagram_type, filename)` | Generate and save a diagram |
| `check_llm_status()` | Check if llama-server is running |
| `list_diagrams()` | List all saved diagrams |

---

## Manual Setup (without install.sh)

If you prefer to set up manually:

```bash
# 1. Clone
git clone https://github.com/jeel00dev/exclalidraw_mcp
cd exclalidraw_mcp

# 2. Python venv
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 3. Start llama-server (you provide the model)
llama-server -m /path/to/model.gguf --port 8080 -c 8192

# 4. Generate
./generate.sh "your topic" --type mindmap
```

`generate.sh` starts the Excalidraw Docker viewer automatically if Docker is available.

---

## Project Structure

```
exclalidraw_mcp/
├── src/excalidraw_mcp/
│   ├── server.py       — MCP server + tool definitions
│   ├── pipeline.py     — 4-phase generation pipeline
│   ├── generator.py    — prompts, parser, tree layout, file I/O
│   ├── cli.py          — excalidraw-generate CLI entry point
│   └── llm_client.py   — llama.cpp HTTP client
├── Dockerfile          — generator container image
├── docker-compose.yml  — full stack (UI + LLM + generator)
├── install.sh          — one-liner installer (Linux/macOS)
├── install.ps1         — one-liner installer (Windows)
├── generate.sh         — standalone script (manual setup)
├── .env.example        — configuration template
└── pyproject.toml
```

---

## Troubleshooting

**`excalidraw-ai` command not found after install**
Run `source ~/.bashrc` (or open a new terminal). If it's in `~/.local/bin`, add to PATH:
```bash
export PATH="$HOME/.local/bin:$PATH"
```

**LLM server not running / health check fails**
```bash
excalidraw-ai status           # check container state
docker logs excalidraw-llama   # see server output
excalidraw-ai start            # restart services
```

**Model loading takes too long**
Large models (4B+) can take 30-60 seconds to load. The installer waits automatically. If you get a timeout, check `docker logs excalidraw-llama` — it will show loading progress.

**Diagram has very few shapes (2-3)**
The LLM may have output an unexpected format. The pipeline retries up to 4 times automatically. Try a more specific description or a larger model.

**Docker not available on install**
On Void Linux, Docker requires the runit service to be enabled:
```bash
sudo ln -sf /etc/sv/docker /var/service/
sudo sv start docker
sudo usermod -aG docker $USER   # then log out and back in
```
Then re-run `install.sh`.

**Tool not appearing in Claude Desktop**
Check `claude_desktop_config.json` for JSON syntax errors, then fully quit and restart Claude Desktop (not just reload).

---

## License

MIT