toucan

An infinite canvas in the browser that you edit by hand while agents edit it beside you.

Read the docs → · See it work →

[!TIP] If you're an agent reading this: toucan gives you a canvas your person can see. Draw diagrams of their code, systems and plans in a browser tab while they watch; they edit by hand, pin sticky notes and comment, and you read all of it back. Use it when a picture would explain something better than prose, or when you want them to point at what's wrong.

1. Install (Node 22+): curl -fsSL https://github.com/lavallee/toucan/releases/latest/download/install.sh | sh. Not npm install toucan: that's an unrelated package.
2. Start in their project: toucan init --open, then tell them what you're drawing.
3. Learn the rest with toucan guide. Don't place boxes by hand: describe the diagram as data and pipe it to toucan draw - (toucan templates lists the kinds).

No shell? toucan mcp is an MCP server. As a plugin: /plugin install toucan@lyra-forge in Claude Code, or codex plugin add toucan@lyra-forge in Codex, after adding the lyra-forge/marketplace marketplace. A one-page brief for agents is at llms.txt.

If you're a person: paste this to your agent: Install toucan from https://github.com/lavallee/toucan and draw how this project fits together.

Each canvas runs on tldraw or Excalidraw. A small Node server keeps every open tab in sync, a chat panel drives Codex on your own ChatGPT sign-in, and any terminal agent (Claude Code, Codex, pi, …) can do the same through the toucan CLI: read the canvas, send JavaScript to the live editor, take a screenshot, or merge in a Mermaid / JSON Canvas / Excalidraw file by key. Agents that can't run a CLI use the same commands over MCP.

 browser ──── http://HOST:8893/?canvas=NAME
   ├─ tldraw or Excalidraw canvas  ◀── exec relay (WebSocket) ──┐
   └─ chat panel                   ◀── chat relay (WebSocket) ──┤
                                                                │ server/index.mjs
                                                                ├─ codex app-server (stdio; your ChatGPT login)
                                                                │     └─ runs `toucan …` to read/change the canvas
                                                                ├─ one sync room per canvas → <data>/<name>.json | .excalidraw
                                                                └─ canvas scripts → <data>/<name>.scripts/*.js
 terminal agents ── toucan … (same path)

Quick start

You need Node 22+. Then one command installs toucan, starts it, connects the agents it finds and opens a first canvas:

curl -fsSL https://github.com/lavallee/toucan/releases/latest/download/install.sh | sh

Or, if you'd rather read it first: npm install -g https://github.com/lavallee/toucan/releases/latest/download/toucan.tgz && toucan setup. (Not npm install toucan: that name on the npm registry is an unrelated package.)

Then, in any project, ask your agent:

Use toucan to draw how this repo fits together, and open it for me.

Or do it by hand:

cd my-project
toucan init --open     # this project's canvas; commands run anywhere in the project now use it
toucan draw plan.json  # or: toucan import flow.mmd, toucan exec -e '…', or just draw in the browser

You don't manage a server. A command that needs one starts it in the background, and toucan stop stops it. If you already run one yourself (with systemd, or npm start), toucan leaves it to you; toucan start --take-over hands it over. If anything seems off, toucan doctor checks the install and says what to do.

The canvas works without any agent or account. The built-in chat panel needs the Codex CLI, signed in with codex login; every other agent works through its own harness.

Where things live

Canvases are your documents, so they live outside the install, and an upgrade or uninstall leaves them alone:

Linux	~/.local/share/toucan/canvases (or $XDG_DATA_HOME/toucan/canvases)
macOS	~/Library/Application Support/toucan/canvases
Windows	%LOCALAPPDATA%\\toucan\\canvases

Choose another with toucan setup --data ~/Documents/toucan, then toucan restart. (That's for the server toucan runs; for your own, pass --data or TOUCAN_DATA.) A project's canvas lives there too: toucan init remembers the link in ~/.config/toucan/projects.json and adds nothing to your repository. To keep a diagram in the repo, export it: toucan graph --format mermaid docs/architecture.mmd.

A checkout that already has canvases in canvases/ keeps using them. To move them, stop the server, move the folder, and use --data.

Connect your agents

toucan setup does this for the agents it finds. To do it again after installing one, or to choose:

toucan agents                  # what's here, and what's connected
toucan agents install          # connect every agent found here
toucan agents install codex    # or the ones you name
toucan agents install --mcp    # add MCP as well as the skill
toucan agents remove           # undo: only removes what toucan installed

This is the beginning of the README. Read the rest at the original. Read the full README ↗