# Tldraw

> tldraw — draw on a live canvas

- Skill: `codejunkie99/tldraw` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add codejunkie99/tldraw`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codejunkie99/tldraw/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: codejunkie99 (https://skillmd.com/u/codejunkie99)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/codejunkie99/tldraw

---


# tldraw — draw on a live canvas

The tldraw MCP server exposes a live canvas at `http://localhost:3030`.
You draw into it; the user watches it fill in. Worthwhile drawings can
be snapshotted to disk and recalled in future sessions via this skill's
local store (`store.py`).

## When this skill loads

Any time the user asks to visualize, diagram, sketch, lay out, or map
something graphically. If they are clearly asking for prose, do not draw.

## Before drawing, once per session

Tell the user:

> Open `http://localhost:3030` to see the canvas.

If any tool returns `No tldraw browser connected`, repeat the hint and
stop until they confirm.

## Opt-in MCP setup

This beta does not install MCP wiring during default adapter setup. After the
user enables `tldraw` in `.agent/memory/.features.json`, they must add the
server to their harness MCP config. Use this local block as the source of truth:

```json
{
  "mcpServers": {
    "tldraw": {
      "command": "npx",
      "args": ["-y", "@tldraw-mcp/server"]
    }
  }
}
```

For Claude Code and Antigravity this usually lives in `.mcp.json`; for Cursor
it usually lives in `.cursor/mcp.json`. If a config already exists, merge the
`tldraw` server entry rather than overwriting the file.

## Tools

| tool | purpose |
|---|---|
| `create_shape({ shapes: [...] })` | add new shapes |
| `update_shape({ updates: [{ id, props }] })` | change shapes by id |
| `delete_shape({ ids: [...] })` | remove shapes |
| `get_canvas()` | return all current shapes |

Always `get_canvas` first when the user says "add to", "next to",
"modify", or refers to something already drawn — you need the real ids.

## Coordinate system

- Origin `(0, 0)` top-left. `+x` right, `+y` down.
- Stay inside `0 <= x <= 1600`, `0 <= y <= 900` unless told otherwise.
- Default sizes: boxes ~160x80, icons ~60x60.

## Shape vocabulary

| type | required | optional |
|---|---|---|
| `geo` | `x, y, w, h` | `geo` (rectangle/ellipse/triangle/diamond/star/...), `color`, `fill`, `text` |
| `text` | `x, y, text` | `color`, `size` (s/m/l/xl) |
| `arrow` | `x, y, end:{x,y}` | `color`, `text` (label) |
| `line` | `x, y, end:{x,y}` | `color` |
| `draw` | `x, y, points:[{x,y}]` | `color` (freehand, at least 2 points) |
| `note` | `x, y, text` | `color` (sticky note) |

Colors: `black, grey, light-violet, violet, blue, light-blue, yellow, orange, green, light-green, red`.
Fills: `none, semi, solid, pattern`.

## Persisting drawings

When a drawing is worth keeping across sessions (architecture decisions,
recurring diagrams, reference material), snapshot it:

```bash
# fetch current shapes via MCP get_canvas and pipe the JSON in
python3 .agent/skills/tldraw/store.py snapshot \
    --label "auth-flow-v1" --tags architecture,auth \
    --note "login + refresh token flow agreed 2026-04-21"
```

The store reads canvas JSON on stdin, writes a snapshot file under
`snapshots/`, appends metadata to `snapshots.jsonl`, and re-renders
`INDEX.md` — all within a single file lock. Later sessions recover a
drawing with `list` / `load`. Use `archive` to retire a snapshot; the
JSONL is append-only semantic, so archived records move to
`snapshots/archive/` rather than being deleted.

## Pitfalls

- `text` shapes need non-empty `text`.
- `arrow.end` is an absolute point, not a delta.
- Split large scenes into multiple `create_shape` calls (<= 200 each).
- Always `get_canvas` before an edit; never assume ids.

## Self-rewrite hook

After any failure, or every 5 uses:
1. Read the last N tldraw-tagged entries from `memory/episodic/AGENT_LEARNINGS.jsonl`.
2. If a constraint was violated (shape cap, id-before-edit rule), escalate
   a candidate lesson to `semantic/LESSONS.md` via `tools/learn.py`.
3. Commit: `skill-update: tldraw, <one-line reason>`.