Cavepaintings
Experimental -- This project is in active development and should be considered in public testing. APIs, features, and behavior may change between releases. Feedback and bug reports are welcome via GitHub Issues.
A browser-based interactive drawing canvas that integrates with Claude Code. Draw diagrams, paste and annotate images, and submit canvas snapshots directly into your Claude Code conversation over a persistent WebSocket connection.
Dark-themed canvas with left toolbar, floating properties panel, zoom indicator, and submit bar. The architecture diagram shows the bidirectional data flow -- submissions go from canvas to Claude, and the push API sends objects back.
Features
Drawing Tools
- Shapes -- rectangles (R), ellipses (E), arrows (A), lines (L), polygons (P)
- Freehand draw (D) -- pencil brush with customizable color and width
- Text (T) -- click to place, double-click to edit inline
- Image (I) -- file picker, clipboard paste (Ctrl+V), drag-drop, or paste a URL
- Connectors (C) -- lines that attach to object anchor points and follow when objects move, with automatic routing around obstacles
Canvas Management
- Object list panel (O) -- see all objects, click to select, drag to reorder z-index, double-click to rename, keyboard navigation
- Properties panel (Q) -- fill, stroke, opacity, font size, z-ordering; always visible with an empty-state prompt when nothing is selected
- Snap-to-grid (G) -- toggle a dot grid; objects snap to 24px increments when moved
- Zoom & pan -- scroll wheel to zoom (0.1x--10x), Alt+drag or middle-click to pan, zoom indicator with click-to-reset
- Undo/redo -- 50-state stack with Ctrl+Z / Ctrl+Y
- Copy/paste -- Ctrl+C / Ctrl+V to duplicate objects (multi-select supported)
Export & Persistence
- Export -- PNG (2x HiDPI), SVG, and JSON
- Import -- JSON re-import to restore diagrams
- Auto-save -- canvas state persists in localStorage across browser refreshes
- Dark/Light theme -- toggle between themes, persists across sessions
Claude Code Integration
- Submit to Claude -- sends 2x HiDPI PNG + Fabric.js JSON + optional message over WebSocket; Ctrl+Enter shortcut from the prompt field
- Automatic notifications -- a UserPromptSubmit hook detects new submissions and injects them into Claude's context with prompt text and object summaries
- Canvas push API -- Claude can programmatically place objects on the canvas via
POST /api/canvas - Submissions API -- harness-agnostic
GET /api/submissions?since=<timestamp>endpoint for polling - Connection status -- green/red indicator with automatic reconnect (exponential backoff)
Responsive & Touch
- Tablet layout -- at viewport widths below 768px, the toolbar moves to a horizontal top bar with 44px touch targets, and panels become bottom sheets
- Touch gestures -- pinch to zoom, two-finger drag to pan, long-press for context menu, double-tap to edit text
Security
- HTTP security headers -- Content-Security-Policy, X-Content-Type-Options, X-Frame-Options, Referrer-Policy on all responses
- Input validation -- schema validation on POST /api/canvas with 5 MB body limit
- WebSocket origin checking -- accepts only localhost origins, blocks cross-site hijacking
- File permissions -- submissions and state files written with restrictive permissions (0700 dirs, 0600 files)
- Rate limiting -- sliding window limits on all API endpoints and WebSocket messages
- Path traversal protection -- static file server validates against traversal attacks
Accessibility
- aria-labels on all controls with keyboard shortcut hints
- aria-pressed states on toggle buttons
- Label associations on all inputs
- Keyboard navigation in object list panel (arrow keys, Alt+Arrow to reorder, Delete to remove)
- Toast notifications use
role="alert"for screen reader announcements
Quick Start
Cavepaintings is designed to be installed as a Claude Code plugin. Once installed, use /cavepaintings and /cavepaintings-stop inside any Claude Code session -- no manual server management needed.
Prerequisites: Node.js (v18+) and npm. Dependencies install automatically on first launch.
1. Register the marketplace
Add to your Claude Code settings (~/.claude/settings.json):
{
"extraKnownMarketplaces": {
"cavepaintings-marketplace": {
"repo": "RCellar/cavepaintings",
"branch": "master"
}
}
}
Or ask Claude Code: "Add RCellar/cavepaintings as a custom marketplace called cavepaintings-marketplace"
2. Install the plugin
In Claude Code, run /plugins, navigate to Discover, find cavepaintings, and install it.
3. Use it
/cavepaintings # opens the canvas in your browser
/cavepaintings-stop # stops the server