agentic-canvas

Agentic Canvas

Agentic Canvas is a local-first visual canvas that an AI agent drives through a local MCP server. It supports Excalidraw for freeform diagrams and JSON Canvas for portable semantic knowledge maps, while a single local Node process serves the browser app, exposes MCP over Streamable HTTP, and syncs scene changes over WebSocket.

Published package: @trohde/agentic-canvas

Executable: agentic-canvas

Prerequisites

• Node.js 20.19 or newer
• npm
• A modern browser
• An MCP-capable client, such as Codex, Claude Code, or Claude Desktop

Setup

npm install
npm run build

Run

npm start -- --canvas excalidraw
npm start -- --canvas jsoncanvas

For package usage after publishing:

npx @trohde/agentic-canvas --canvas excalidraw
npx @trohde/agentic-canvas --canvas jsoncanvas

Flags:

• --canvas <name>: canvas plugin, one of excalidraw, jsoncanvas
• --port <n>: port, default 3333
• --host <host>: bind host, default 127.0.0.1
• --workspace <dir>: root for save/open/screenshot files, default current directory
• --open / --no-open: open the browser on startup, default open

Optional environment overrides are AGENTIC_CANVAS_PORT, AGENTIC_CANVAS_HOST, and AGENTIC_CANVAS_WORKSPACE. save_canvas, open_canvas, and screenshot file writes are constrained to the configured workspace root. An HTTP MCP client config only points at an already-running server; it does not choose that server's current working directory. Start the server with --workspace <project> when files should be scoped to a project directory. No secrets or .env file are required.

Develop

For backend, MCP tool, plugin, or workspace changes:

npm run dev

For browser HMR, run the backend and Vite dev server in separate terminals:

npm run dev:server
npm run dev:web

Open http://127.0.0.1:5173 for the Vite UI. MCP clients should still connect to the backend at http://127.0.0.1:3333/mcp.

See docs/mcp-dev.md for Codex configuration, example profiles in docs/codex/, MCP Inspector usage, and restart expectations.

Connect An MCP Client

With the server running on the default port:

claude mcp add --transport http agentic-canvas http://127.0.0.1:3333/mcp

Codex example profiles are committed under docs/codex/ for readonly, authoring, and dangerous tool sets. Copy one into your local Codex config instead of committing an active .codex/config.toml.

Example tool flow:

1. Call get_canvas_state to identify the active canvas type.
2. Call get_canvas_capabilities to discover supported tool groups and preferred workflows.
3. For --canvas excalidraw, call apply_canvas_patch to create several nodes in one atomic change.
4. Call connect_objects to add bound arrows between the nodes.
5. Call auto_layout_objects or align_distribute_objects to clean up spacing.
6. Call find_objects to locate objects by type, label text, geometry, style, link, or metadata.
7. Select an object in the browser and call get_selected_objects; the tool returns the selected normalized object.
8. Call select_objects with an object id to select it from the MCP client.
9. Call screenshot; the tool returns a PNG image.
10. Call save_canvas with { "path": "demo" }; the file is written as demo.excalidraw inside the workspace.
11. Call clear_canvas, then open_canvas with { "path": "demo" }; the saved scene is restored.

save_canvas and open_canvas append the active canvas extension when no extension is provided and reject other extensions. screenshot appends .png for file writes and rejects other extensions.

For --canvas jsoncanvas, agents can use add_text_card, add_file_card, add_link_card, create_group, connect_cards, find_cards, find_edges, auto_layout_cards, and apply_jsoncanvas_patch. A typical JSON Canvas flow:

1. Call add_text_card for context, risks, decisions, and next steps.
2. Call connect_cards with labels such as causes, mitigates, or depends on.
3. Call create_group to frame related cards.
4. Call auto_layout_cards.
5. Call save_canvas with { "path": "architecture-review" }; the file is written as architecture-review.canvas.

The JSON Canvas plugin writes standards-compatible .canvas files without Agentic Canvas metadata. Default card sizes are intentional: text cards are 360x180, file/link cards are 360x120, and groups are 520x360. connect_cards defaults toEnd to "arrow"; pass toEnd:"none" for a plain line. auto_layout_cards treats layerSpacing and nodeSpacing as gaps added to measured card sizes, so small explicit spacing values should not overlap cards. It does not fetch link previews, index Obsidian vaults, or render arbitrary embedded media in this version.

Agent Plugins