🌐 日本語版: README.ja.md

Jiscribe

Let an agent draw, fix what bothers you by hand, and hand the rest back to the agent. An SVG engine that people and AI agents draw on together. Architecture diagrams, flowcharts, UI mockups, even posters and whole documents.

When the agent picks up again, nothing is regenerated from scratch and nothing you changed is lost, because what you draw is a plain object in your code and plain JSON (.jis) on disk — the canvas is one way to edit it, and an agent's tools are another.

Most of what you need to draw is already in the box. The core carries eight primitive types (rect / ellipse / text / polyline / polygon / group / connector / svg), and the richer shape sets — flowchart, UML, ER diagrams, tables, sticky, markdown, container, annotation, general pictograms, Lucide icons, AWS architecture — ship as plugins. More sets are on the way.

What you can make

| | | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | <br>UML and class diagrams — packages, interfaces, composition, multiplicities, notes | <br>Architecture diagrams — AWS icons and boundary groups, from region down to subnet | | <br>Infrastructure, drawn to scale — every solid is a native polygon on a 30° lattice | <br>UI mockups — a trading terminal: candles, order book, tape, at the fidelity a spec needs | | <br>Posters and print — a typographic grid is just shapes and text | <br>Flows and swimlanes — handoffs, decisions, exceptions, and the icon that says what each step touches | | <br>ER diagrams — IE notation; a relationship runs from a foreign key to the key it references | <br>Tables — every cell is a text of its own, with its own fill and type, and rows grow to fit |

Whole documents on one canvas — a postmortem: numbers, timeline, cause, action items

Every image in this gallery is a .jis.png: the exported picture carries the document that drew it, so it is an image wherever an image is needed and still a document when you open it in Jiscribe. None of it is a special mode. Each one is an ordinary document of shapes, text and connectors — the kind an agent can write and a person can move by hand.

Built for agents, not bolted onto them

• It edits one move at a time; it does not regenerate. 84 tools over stdio, the same moves you make in the editor: add and connect, align and distribute, group, restyle, reorder, select. An edit lands on the document you have, so what you placed by hand stays where you put it, and undo takes back only the agent's own moves.
• When starting from nothing, it writes the file. The format is small and explicit — eight primitives, named properties, coordinates in the open — so an agent can write a .jis directly, or generate one from a script when a 200-node graph or an isometric lattice is easier to compute than to place. Both ways are documented: the drawing guide for the tools, the format reference for the file.
• It checks before it says it is done. validate, diagnose and measure run headless in Node, in the same layout engine the editor uses — schema errors, parser errors, text that overflows its shape — and it can capture the canvas and look. The agent is told what the editor would tell you.
• You can both have it open. A local viewer follows the file as the agent writes it; drag something there and it is written back, so the agent's next read sees your hand. Writes to one file are serialized, and the agent's undo never rolls back yours.
• The format is written down, not guessed at. A JSON Schema and a generated reference ship with the shapes, and the Claude Code skill is generated from the same manifest — so the shape set an agent is told about is the shape set that exists.

Getting started

With an agent

Register the MCP server with whichever agent you use:

claude mcp add jiscribe -- npx -y jiscribe-mcp   # Claude Code
codex mcp add jiscribe -- npx -y jiscribe-mcp    # Codex
copilot mcp add jiscribe -- npx -y jiscribe-mcp  # GitHub Copilot CLI

Any other client that speaks stdio takes it by hand, under mcpServers — VSCode calls the same map servers:

{
	"mcpServers": {
		"jiscribe": { "command": "npx", "args": ["-y", "jiscribe-mcp"] },
	},
}

Node 22 or newer is required; nothing else is. The jiscribe-mcp package carries the server, the viewer and the fonts its text measurement needs. See apps/mcp for the tool list and the viewer's behaviour.

In Claude Code, the plugin does that for you and adds a drawing skill generated from the shape set:

/plugin marketplace add gznnk/jiscribe
/plugin install jiscribe

In an editor

Jiscribe for VSCode opens .jis, .jis.png and .jis.svg as editable canvases next to your code, with diagnostics in the Problems panel. Pair it with the MCP server and the agent draws with its own checks — diagnose, measure, capture — while you watch the file take shape in VSCode.

If you just want to draw something by hand without installing anything, Jiscribe Web opens a canvas in the browser — no account, no upload, files stay on your machine.

Embedding the engine (not on npm yet)

The packages themselves are not on npm yet. @jiscribe/canvas and the rest are still being settled as an embedding surface, so the public API may move. The first release will go out as a GitHub Release — watch this repository under Custom → Releases to hear about it. What the API looks like today:

import { Canvas } from "@jiscribe/canvas";
import type { CanvasDoc } from "@jiscribe/canvas";

const doc: CanvasDoc = { version: 1, root: [] };

export function App() {
	return <Canvas doc={doc} />;
}

Shapes beyond the primitives come from plugins, registered per canvas:

import { Canvas } from "@jiscribe/canvas";
import type { CanvasConfig } from "@jiscribe/canvas";
import { flowchartPlugin } from "@jiscribe/plugin-flowchart-shapes";
import { umlPlugin } from "@jiscribe/plugin-uml-shapes";

const config: CanvasConfig = { plugins: [flowchartPlugin, umlPlugin] };

export function App() {
	return <Canvas doc={doc} initialConfig={config} />;
}

The document layer is a package of its own, @jiscribe/doc. It parses, validates, edits and measures a CanvasDoc without pulling in React or any DOM dependency — that is what the VSCode extension's diagnostics, the CLI and the AI tooling are all built on. If your product needs the document but not the canvas, that is the package to take.

How it fits together

| Package | What it is | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- | | @jiscribe/canvas | The engine: rendering, gestures, commands, state | | @jiscribe/doc | The headless document layer: the CanvasDoc model, its parser, its editing ops and its .jis.* file I/O | | @jiscribe/canvas-sdk | Shape-authoring kit for plugin authors, written against the canvas public API | | @jiscribe/geometry | Geometry types and calculations (rects, ellipses, transforms, intersections) | | @jiscribe/markdown | Markdown rendering used by the markdown shape | | @jiscribe/basic-validators | Primitive runtime validators | | @jiscribe/utility-types | Shared TypeScript utility types | | @jiscribe/doc-schema | Generated JSON Schema, AI reference and Claude Code skill for the shipped shape set | | @jiscribe/ai-tools | The canvas tool set an AI can call — declared free of any transport, and applied | | @jiscribe/ai-tools-sdk | The contract a plugin offers AI tools for its own shapes through; plugins take it from @jiscribe/canvas-sdk/tools | | @jiscribe/standard-shapes | The shipped shape set, bundled once for every host (doc + presentation entries) | | @jiscribe/doc-tools | Validate / measure / diagnose over the standard set (Node text measurer included) | | plugins/* | The shipped shape sets — flowchart, UML, ER, table, container, general, annotation, sticky, markdown, Lucide, AWS | | apps/canvas-examples | Integration examples (one example = one file) | | apps/cli | The jiscribe command: validate / diagnose / measure / render / preview | | apps/mcp | MCP server: the tool set over stdio, with a local canvas viewer | | apps/desktop | The MCP server as a desktop app (proof of concept): Streamable HTTP, the viewer in its own window | | apps/claude-plugin | The Claude Code plugin: the MCP server and a generated drawing skill | | apps/vscode-extension | The Jiscribe VSCode extension |

The plugins/ directory is deliberately treated as external: those packages may only use the public API of @jiscribe/canvas, @jiscribe/doc and @jiscribe/canvas-sdk, enforced by ESLint. If the shipped shapes can be written that way, so can yours.

Development

pnpm install

pnpm dev:examples      #