turtlepen

TurtlePen

Drawing and editing tools for AI assistants.

TurtlePen lets an AI assistant create diagrams, charts, wireframes, and illustrations as editable shapes, lines, and text. It can measure a label before placing it, connect objects, check for overlaps, and revise individual parts without starting the drawing over.

You describe what you need in a compatible AI app. The assistant uses TurtlePen through MCP (Model Context Protocol), the connection that lets AI apps use external tools. You can then review the result, make changes in the browser editor, and export it as SVG, PNG, or PDF. The editable source is saved as .turtlepen.json.

Quickstart · Try the hosted server · See examples · Run locally

Status: prototype. The hosted server may not have every feature in this repository. See status.md for development status and limitations, and ask the connected server's turtlepen_help for the tools available there.

What it is for

Use TurtlePen when you need an AI to produce a drawing that can be inspected and edited, not just a finished picture.

Make or change	What TurtlePen provides
Flowcharts and system diagrams	Shapes, labels, connectors, lanes, and layout tools
Charts and timelines	Drawing primitives and editable timeline layouts
Wireframes and illustrations	Shapes, paths, fills, layers, and reference images
Existing drawings	Move, resize, restyle, group, edit paths, and undo changes
Technical documentation	Text measurements, overlap checks, and findings that identify what needs attention

TurtlePen is AI-first, not AI-only: the assistant can author the drawing, and a person can review or edit it in the browser. It is a drawing engine, not an AI model or a general-purpose image generator. Its grid-based drawing and supported SVG import are not a replacement for every feature of a full vector editor.

Try it without installing anything

Add this URL as a remote MCP server in an AI app that supports Streamable HTTP:

https://brainn.dev/api/mcp/turtlepen

Then try a request such as:

Use TurtlePen to draw a flowchart of a customer support request. Include the customer, support team, and escalation path. Check the layout, render it, and review the result.

The diagram below shows how the hosted connection works. It was drawn with TurtlePen.

The hosted deployment is updated separately from this repository. Check serverInfo for its version, tools/list for its tools, and turtlepen_help for usage guidance.

The server uses MCP Streamable HTTP with protocol 2025-06-18. Each session holds an active document. Keep the Mcp-Session-Id returned by initialize and send it with later requests.

# initialize, keep the Mcp-Session-Id from the response headers
curl -sD - https://brainn.dev/api/mcp/turtlepen \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
       "protocolVersion":"2025-06-18","capabilities":{},
       "clientInfo":{"name":"you","version":"1.0"}}}'

The Accept header must include both application/json and text/event-stream. Replies use event: message / data: frames on the POST response. See the remote MCP transport contract for the full client and deployment requirements.

What it makes

These examples were authored through TurtlePen's MCP tools. They show the range of drawings it can produce; they are not a guarantee that every prompt will succeed on the first attempt. The experimental studies also retain less successful results.

A complete technical reference, drawn in one pass

An Xbox controller reference with input anatomy, button states, trigger and stick ranges, gesture paths, and an input table.

Editable source.

Real professional documentation

An HVAC condenser replacement field guide with numbered stages, hold points, photo references, and a safety banner.

Data visualisation

A BTC/USD chart with hourly candles, a moving average, and trading volume.

Illustration — the postcard series

Five scenes built from filled shapes and layered paths, including skies, mountains, underwater details, and a rocket launch.

A weathered fence shows line texture and layering, with a vine passing in front of the rails.

Flowcharts with real symbols

Decision diamonds, start/end shapes, and swimlanes. Labels are measured against the space inside each shape.

A pipeline with parallel stages, synchronisation bars, and different connector styles.

The two atlases — what the lattice can draw

A visual reference for node shapes, corners, connectors, and arrowheads:

Drawing marks, shading, textures, and arcs:

TurtleFont — a stroke typeface on the same lattice

TurtleFont draws letters as paths rather than relying on an installed font. It supports multiple alphabets, mathematical symbols, and arrows, with adjustable size and stroke weight.

Tracing a source image, measured rather than asserted

Five comparisons of direct tracing and tracing through a larger working canvas. Each case includes measurements of the resulting detail and coverage.

Five farm animals, with the working record

Five animal outlines, with the drawing steps and review findings recorded in the 14-page PDF.

The problem it solves

AI-generated drawings can have labels that do not fit, disconnected lines, and unintended overlaps. TurtlePen gives the assistant ways to measure, inspect, and fix those problems instead of relying only on the final image.

Its geometry uses a fixed grid, called a lattice. The engine tracks where elements sit and reports supported layout problems with their severity and suggested repairs. It does not silently resize the drawing to hide them.

A clean layout check is not proof that a drawing is correct or finished. The rendered result still needs visual review to confirm that it is readable and depicts what was requested.

The workflow

Measure → plan → draw → check → render → review.

Measure labels and available space, rehearse a set of changes with plan, then commit them. Run validate, fix problems or explain intentional overlaps, and render the result. Review the actual image before calling it finished.

You can also sketch first and repair afterwards. TurtlePen reports collisions rather than rejecting every overlapping placement, and history provides undo and redo.

plan rehearses operations on a copy. The document changes only when the batch is sent with commit: true; a batch that fails part-way applies nothing.

plan { operations: [ …place boxes, run pen programs… ] }
…read the findings and adjust the plan…
plan { operations: […], commit: true }

free_space searches non-reference pages, including hidden pages, by default. Use scope: "page" for a single page, and supply cellsW and cellsH together for a fit query. describe { region: "C4:AZ40" } inspects a bounded region and can also be filtered by page.

history stores the newest 100 successful mutations by default, configurable from 1–1000 with TURTLEPEN_HISTORY_LIMIT. Its saved sidecar is tied to the document hash so stale history is not applied to an externally changed file. A new edit after undo clears redo.

accept_finding records an intentional exception against the exact finding. Changing the relevant geometry invalidates that acceptance. export_prompt similarly refuses to export a wireframe layout whose recorded source no longer matches the edited drawing.

Running it

For local use, you need Node.js 20 or newer. TurtlePen has no runtime dependencies to install.

git clone https://github.com/Meteoryte/turtlepen
cd turtlepen
node src/mcp/server.js

The last command starts the local MCP server over stdio; it waits for an MCP client. Register it in your AI app using the absolute path to your clone:

{ "mcpServers": { "turtlepen": {
    "command": "node",
    "args": ["/absolute/path/to/turtlepen/src/mcp/server.js"]
} } }

Use an absolute path, not ~ or a relative path. The server's working directory determines where it can read and write files; the quickstart explains workspace configuration and walks through a first drawing.

Call turtlepen_help for an introduction, search_help { query } to find a capability, or turtlepen_help { section: "all" } for the complete tool reference. The native editing guide covers more advanced edits. The CLI also supports validation, rendering, and bundling without an MCP client: run node src/cli.js help.

pnpm run check                         # full test suite + examples, logo, and tree
pnpm test                              # automated test suite
pnpm run test:endpoints                # MCP, HTTP, and WebSocket surface contract
pnpm run quality:manifest              # regenerate role-scoped artifact evidence
pnpm run governance                    # source checkout: enforce naming, catalog, SSOT, and generated-file parity
node src/cli.js render diagrams/example.turtlepen.json --format svg --json --force
node src/cli.js review diagrams/example.turtlepen.json --render-hash <hash> --reviewer <name>
node examples/build-example.js         # the plan -> commit cycle, end to end
node examples/agent-session.js         # an agent authoring a real diagram over MCP
node examples/constraint-stress.js      # crowded same-face rehearsal and rework over MCP
node examples/rework-session.js         # commit, detect, undo, redo, reopen over MCP
pnpm run field-guide                    # build the condenser replacement field workflow over MCP
pnpm run image-session                  # exercise embed, dither, simplify, and review/reference gates over MCP
pnpm run random-images                  # compare direct 1x and 4x->1x simplify across five seeded-random sources
pnpm run logo                          # regenerate the canonical 1200x1200 logo
pnpm run tree                          # regenerate the 540x960 branching-tree study
node src/viewer/server.js --doc diagrams/example.turtlepen.json
node src/mcp/server.js                 # MCP over stdio
TURTLEPEN_HTTP_BEARER_TOKEN=<secret> pnpm run mcp:http  # stateful MCP over HTTP

The local HTTP transport uses the same tool registry and keeps one active document per session. Its default bearer-token setup is intended for private previews, not a complete public multi-user deployment. See remote MCP requirements.

The endpoint and use-case coverage matrix maps the available interfaces and workflows to their checks. Tools provide versioned structured responses as well as text responses.

Seeing it as a human

Run node src/viewer/server.js to open the local browser editor at 127.0.0.1:8791. You can select elements, move or resize them, change their styling, edit paths, manage groups and relationships, review findings, and undo or redo changes.

The drawing and findings update live. Zoom and page visibility affect your view, while edits and history are saved as document state. See native editing workflows for details.

Technical reference

You do not need to learn the drawing language before asking an assistant to use TurtlePen. These sections are for tool users and developers who need the exact rules.

The lattice

A cell is 10 × 10 pixels, divided into four 5 × 5 pixel quadrants. Geometry is placed on whole quadrants so its occupied space can be calculated consistently.

┌────┬────┐
│ q1 │ q2 │
├────┼────┤
│ q3 │ q4 │
└────┴────┘

Addresses work like spreadsheet cells. A1 is the top-left; the grid extends right and down. Start inset, for example at T20, when a drawing may need space above or to the left.

Form	Meaning	Size
C4	whole cell	10 × 10 px
C4.tl	pin point — 9 per cell (tl t tr l c r bl b br)	lattice point
C4.q2	quadrant — 4 per cell	5 × 5 px

The pen

Pen commands move a cursor and draw strokes. Each path has an exact footprint, so findings can identify the affected elements and locations.

pen J8.q1                              # place the cursor
down 2 align right line                # 2 cells of 5px stroke, hugging the right half
down corner align top right            # arrives from the top, leaves to the right
right 3 align top line
right corner align left bottom         # arrives from the left, leaves downward
down align left line to queue.N arrow  # engine counts the distance; run ends in an arrowhead

Distances count whole cells. align selects the half-cell track: left|right for vertical strokes or top|bottom for horizontal strokes. There is no centred 5px track inside a 10px cell. Omitting align continues the current track.

Locations such as at C7.q2 can reset the cursor within a program. to <address> or to <id>.<port> measures along the current direction; the final path still has to reach the target. Corner styles are square, rounded, indented, and chamfered.

arrow replaces the last quadrant of a line with an arrowhead. arrow start and arrow both support arrows at the other end or both ends without extending the path.

Shapes: anything that is not a rectangle

Lines, curves, circles, ellipses, arcs, and polygons are built from occupied grid quadrants. Combine them into larger drawings, or fill a closed outline to create a solid region.

ray to AF20.q1        a straight line at ANY angle (Bresenham)
curve C4 K10 S6 AB14  a smooth line through the points, contiguous by construction
circle 12             outline (midpoint); radius in QUADRANTS, not cells
ellipse 24 10 30      the same family, two radii and an optional rotation
circle 18 fill        any closed shape may be filled; the region claims its inside
disc 12               the same circle, filled
arc 12 0 90           part of it, clockwise from east
triangle M4.q1 T9.q1  three points; polygon takes more
dash 6 se             six quadrants diagonally — the morse dash
dot                   one quadrant — the morse dot

Directions include n ne e se s sw w nw and up/down/left/right. An open outline cannot be filled. fillColor can colour a region independently of its outline; { from, to } creates a gradient. Stroke colours can also vary along a path. set_background saves the paper colour with the document.

Text and layout

stroke_text draws text with TurtleFont; stroke_label gives a box a path-based label. size is the cap height in quadrants, weight controls stroke thickness, and rotate supports quarter turns. Sizes that round onto the grid are reported as rounded. Use font_coverage to check characters, glyph to inspect one, and pnpm run font:floor to check the supported size floor.

layout arranges a graph and reroutes its connectors, reporting anything it cannot route. align and distribute adjust the elements you name without moving unrelated content. A worked illustration is available at diagrams/art-deco-hero.svg.

Anchors and durable relationships

Anchors place objects relative to other elements instead of requiring hand-calculated coordinates.

pen at shell.C                       put the cursor ON an element
circle 15 at shell.N                 anchor a shape to one
circle 7 at head.W offset -3 4       nudge in whole quadrants

from starts just outside an element's edge for a connector; at places on an anchor. Anchors are N NE E SE S SW W NW C. Corner anchors refer to the bounding rectangle, so use edge midpoints and offsets when placing details on rounded shapes.

A placement anchor is resolved when the program runs. Use constraint for a stored relationship that should follow later edits:

{ "action": "create", "id": "label-follows-unit",
  "dependent": "label", "target": "unit",
  "dependentAnchor": "W", "targetAnchor": "E",
  "offsetX": 2, "offsetY": 0 }

Constraints support list, create, delete, and sync. Each dependent has one parent; chains are supported and cycles are refused. Relationships survive save/open. Moving a dependent manually updates its offset.

Semantic node relationships

connect records which nodes an edge joins, along with optional descriptions, technology, tags, properties, and perspectives.

{ "id": "api-to-db", "from": "api.E", "to": "db.W",
  "routing": "curved", "via": ["K5.q1"],
  "description": "queries customer records", "technology": "SQL/TCP" }

Routing can be direct, orthogonal, or curved; curved routes require explicit waypoints. annotate adds descriptive fields, and inspect_model checks missing information and broken relationships separately from geometry.

Reversible 1px eraser

micro_mask hides parts of artwork paths or images without changing their collision footprint.

{ "action": "add", "id": "cleanup-1", "target": "ink",
  "points": [{ "x": 25, "y": 70 }], "width": 1 }

Masks survive save/open and follow their targets. Remove one with micro_mask { "action": "remove", "id": "cleanup-1" }.

Tracing over a reference

place_reference { source: "ref.png", span: "40x24" }
… draw over it …
remove_page { id: "reference" }

The reference is converted to the grid and placed on a faint background page. L020 flags it until it is removed from the finished document.

Closed outlines are not treated as connectors. For intentionally open drawing marks, use role: "artwork" to avoid connector-only findings. Artwork supports colour, 1–5px display width, and line caps; paint: "cells" paints each occupied quadrant. These display settings do not change the collision footprint.

hop marks a deliberate line crossing with a bridge arc. It permits the crossing between paths, but not a path running through a box.

Connectors: the two mistakes worth knowing

Use named ports instead of calculating the start yourself.

pen from gateway.S          # seated just outside, already facing down
down line to checkout.N arrow

When multiple paths leave the same face, use indexed ports:

pen from gateway.S#2        # one full cell left of the midpoint track
down line to worker.N#2 arrow

#1 is the midpoint, #2 one cell left, and #3 one cell right, continuing outward. place_box and describe report the available slots. Ports follow the actual shape edge, including diamonds and slanted shapes.

A to command measures along the current direction. A path on the wrong row or column can stop level with its target without touching it. The finished path is checked, and L016 reports the remaining gap.

Corner styles participate in collision

TurtlePen distinguishes the space reserved for a shape from its visible ink. Crossing an empty rounded or cut corner produces an informational finding (L013); crossing the shape itself remains an error (L004).

Z-pages

Z-pages are drawing layers. Their declared intent distinguishes accidental overlap from deliberate layering.

Intent	Overlap with lower pages
exclusive	L005 error — nothing below may be overlapped
overlay	L010 information — expected, so annotation layers stay quiet

Same-page overlap is still checked. Overlay intent does not make all content conflicts harmless, including obscured text.

Collision rules

These checks identify supported structural problems. They do not judge whether the drawing tells the right story.

Rule	Sev	What it catches
L001	S0 critical	two elements claim the same quadrants on one page
L012	S0 critical	duplicate element id — targets become ambiguous
L002	S1 error	measured text wider than the box interior
L003	S1 error	wrapped text needs more lines than the box shows
L004	S1 error	a path runs through the inked body of a box
L005	S1 error	an exclusive page overlaps content below it
L021	S1 error	opaque overlay content obscures a lower text run
L006	S2 warn	two paths share a quadrant with no junction or hop
L007	S2 warn	two boxes touch with no separating quadrant
L008	S2 warn	a path ends without meeting a box or another path (one finding per path, not per end)
L009	S2 warn	font size below the 8px legibility floor
L011	S2 warn	an element extends past the declared canvas
L014	S2 warn	a stroke drawn on a track the cursor was not on
L015	S2 warn	a path re-draws a quadrant it already covered
L016	S2 warn	a path named a destination but stops short of touching it
L020	S2 warn	a temporary tracing-reference page is still present
L022	S2 warn	a rasterized image has enough neighboring ink changes to obscure its identity
L023	S2 warn	continuous-tone source was simplified without semantic understanding
L024	S2 warn	a shape is stretched until its silhouette no longer distinguishes it
L025	S1 error	things at different depths share a page, so neither can pass behind the other
L010	S3 info	expected overlap from an overlay page
L013	S3 info	a path crosses a claimed but un-inked corner cut
C001	S3 info	sparse canvas — too little ink to have been composed; compose it, or declare the page schematic

Every fix has a tool

Findings suggest repairs supported by the editing tools. repair can apply supported fixes by finding fingerprint; the underlying operations are listed below.

Fix kind	Tool
widen, heighten	resize
shorten, font	restyle
move	move
rename	rename
intent	update_page
canvas	set_canvas
extend	extend_path
reroute, offset, hop	replace_path
remove	remove or remove_page according to target kind

This overview groups the documented tools. Use the connected server's tools/list and turtlepen_help for its current capabilities.

Group	Tools
orient	turtlepen_help search_help doctor runtime_info describe ascii free_space history
author	new_diagram open_diagram add_page remove_page measure place_box pen connect annotate plan group constraint timeline import_mermaid route
workspace	define_view remove_view configure_theme attach_resource remove_resource
check	validate inspect_model accept_model_finding unaccept_model_finding perceptual_review release_check accept_finding unaccept_finding
layout	align distribute layout
repair	repair resize restyle move rename update_page set_canvas extend_path replace_path remove
fidelity	micro_mask stroke_text stroke_label glyph font_coverage set_background
lattice editing	boolean slice offset_path stroke_to_path path_edit normalize_path reorder duplicate array
inspect geometry	inspect
SVG import	inspect_svg import_svg
compose	wireframe perspective_scene export_prompt
image	measure_image place_image place_reference
output	render save

Seeing the drawing

ascii provides a text preview of the occupied grid, including addresses and collision marks.

     B C D E F G H I J K L M N O P Q R S T U V W
   4 ··aAAAAAAAAAAAAAAAAAAAAAAAAAAa··············
     ··AAAAAAAAAAAAAAAAAAAAAAAAAAAA··············
   8 ·················│··························
  10 ·················└──────┐···················
  12 ··bBBBBBBBBBBBBBBBBBBBBBBBBBBb············cCCc

Lowercase letters mark reserved but unpainted corners; ✗ marks a collision. Render the image for visual review.

Architecture

src/core/     pure engine, no I/O — geometry, address, text, shapes,
              document, pen, edit, svg-import, occupancy, collide, ascii, svg
src/mcp/      shared MCP protocol/runtime, stdio and Streamable HTTP transports,
              and the canonical tool definitions
src/viewer/   local HTTP/WebSocket server + live browser editor and log
src/quality/  artifact catalog, manifest, and naming/SSOT governance
test/         node:test, no framework
examples/     worked end-to-end demonstration

Mutations are registered in core.OPERATIONS, allowing the same operation to run in a rehearsal or on the live document. Measurement, validation, and rendering share the core engine. SVG text uses textLength to match the measured width; TurtleFont provides path-based lettering.

Read llm.md before changing src/core/, and use the source-of-truth map to locate authoritative schemas, versions, and generated evidence.

Documentation and additional capabilities

Topic	Guide
First drawing and local setup	Quickstart
Supported diagram types	Diagram types
Native editing and geometry repair	Native editing · Lattice editing
Vector operations and SVG import limits	Capability status · SVG import
Timelines, phases, and milestones	Semantic timelines
Flowchart behaviour and limitations	Flowchart support
Experimental physical XYZ geometry	3D prototype
Development status and ownership	Status · Source-of-truth map

Timelines support events, ranges, tracks, milestones, and Mermaid timeline import as editable drawing elements. See the vertical and horizontal examples.

3D is a separate local prototype, with XYZ primitives, extrusion, box booleans, TPF, and STL/GLB export. Blender import has been independently checked; slicing and physical printing remain unverified. Do not assume these features are available on the hosted server.

The condenser field guide has an editable source and a photo-shot list.

The real-image MCP exercise uses a generated condenser photo and a separate line-art version to demonstrate image embedding, dithering, simplification, and tracing references. Prompts and measured results are recorded in the image workflow test; the image scaling procedure explains the limits.

The five-case comparison tests direct tracing against a larger working canvas while preserving the same final grid size. Its evidence ledger records the measurements and hashes. A larger working canvas does not create new source detail or prove a faithful interpretation of a photograph.

Deferred, deliberately

TurtlePen reports sizing problems instead of silently auto-fitting content. Standard labels use a monospace measurement model rather than arbitrary proportional fonts. Grid addresses do not extend into negative coordinates; start inset when you need room to grow left or up.

Experimental AI-generated studies

Two model runs attempted the same eight briefs: four architecture diagrams and four illustrative scenes. Both stronger and weaker results are kept for comparison, not presented as uniformly finished work.

For example, the Gemini 3.1 run produced the chart and fence shown above, but its CI/CD pipeline has poorly placed labels. This is why layout checks and visual review are separate steps.

Artifact roles and quality status are recorded in artifacts/artifact-catalog.json; artifacts/manifest.json contains generated evidence.

• Server structure — HA microservices (JSON)
• Teaching — adaptive mastery cycle (JSON)
• Technical analysis — quant signal & risk engine (JSON)
• Workflow — CI/CD deployment pipeline (JSON)
• Scenes: apple · tree · fence · living room

• Server structure — load balanced (JSON)
• Teaching — learning feedback loop (JSON)
• Technical analysis — algorithmic trading engine (JSON)
• Workflow — DevOps CI/CD pipeline (JSON)
• Scenes: apple · tree · fence · living room

The following examples were authored using TurtlePen MCP tools by Claude Opus 5.

Flowcharts — real symbols, not rectangles with labels

Shapes include decisions, start/end points, documents, and containers. Text is checked against the room inside the chosen symbol, not just its outer rectangle.

place_box { id: "spelling", at: "AT53", span: "30x9",
            label: "Free of spelling and logic errors?", shape: "decision" }

Shapes: process decision terminator subprocess io prep manual data document bar, plus lane and group containers.

Containers reserve a title band and border, leaving room for elements inside. Intentional boundary crossings can be recorded with accept_finding.

Check	What it reports
F001	More than one terminator with no incoming edge
F002	A decision with fewer than two outgoing edges

Connections come from explicitly named sources and targets, not proximity. The engine does not guess which floating label belongs to a branch.

build-flowchart.js also produces the longer flowchart-important-process exercise. See the flowchart support notes for scope and limitations.

Five Farm Animals — with a full working record

The composition and editable source are accompanied by a 14-page working record.

the composition	how each silhouette is built	every committed pen program
real defects vs. declared anatomy	what the session taught

The record shows how the silhouettes were drawn and which problems only became clear after rendering. For example, a structurally valid sheep still looked like the wrong animal.

Logo v2 — the mark drawing itself

The turtle is drawing an earlier version of its own logo. The image-placement tools put that artwork on a layer beneath the pen.

PNG · Editable source

Perceptual review — the half validate cannot see

validate checks structure. Visual review checks whether the drawing is readable and represents the intended subject. TurtlePen keeps these results separate and ties each review to the exact rendered version.

After rendering and inspecting the image, record the result with its renderHash:

perceptual_review { renderHash, reviewer, findings: [{
  id, severity: P0..P3, category, symptom, consequence, elements, repair }] }

symptom describes what looks wrong; consequence explains what a reader could misunderstand. A review does not alter collision geometry. It becomes stale when the drawing changes, and an unreviewed drawing stays NOT REVIEWED.

release_check requires a current visual review as well as structural checks. Structural results are PASS, PASS_WITH_EXCEPTIONS, or FAIL; accepting a finding does not turn an exception into an ordinary pass. Accepted critical/error findings require evidence tied to the reviewed render.

accept_finding { fingerprint, reason, evidence: {
  renderHash, repairAttempt, observation, consequence } }
release_check

See the imaging capability roadmap for implementation history and remaining candidates, and the archived implementation prompts for the original plans.

---

TurtlePen is MIT licensed and has no runtime dependencies. You can support the project by buying me a coffee.