# toucan

> A canvas in the browser that a person and their agents share. The agent draws diagrams of code, systems and plans; the person watches, edits by hand, pins sticky notes and comments; the agent reads all of it back. It runs on the person's own machine. MIT licensed.

Use toucan when a picture would explain something better than prose: how a repository fits together, a process, an architecture, a plan, a timeline. It's also a way for the person to point at what's wrong instead of describing it.

## Install

Needs Node 22 or newer. This installs toucan, starts its server, connects the agents it finds, and opens a first canvas:

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

Don't run `npm install toucan`: that name on the npm registry is an unrelated package. `toucan doctor` checks an install. `toucan update` updates it.

As a plugin, which adds a skill that teaches the CLI: in Claude Code, `/plugin marketplace add lyra-forge/marketplace` then `/plugin install toucan@lyra-forge`; in Codex, `codex plugin marketplace add lyra-forge/marketplace` then `codex plugin add toucan@lyra-forge`. An agent without a shell can use `toucan mcp`, an MCP server with the same commands.

## Start

    toucan init --open          # the canvas for the project you're in, opened in the person's browser
    toucan templates            # kinds of diagram: flowchart, sequence, architecture, org chart, roadmap, kanban and more
    toucan templates show ID    # the form a diagram is described in
    toucan draw plan.json       # lays out a diagram described as data; pipe JSON to `draw -` instead
    toucan summary              # what's on the canvas, by key
    toucan routine run check-diagram    # a score out of 100, and what's wrong where
    toucan guide                # the full agent guide

Tell the person what you're drawing. Commands run anywhere inside the project use its canvas.

## Working with a person

- They may be editing while you work: look before you change, keep edits small and keyed, and never wipe their work.
- Don't place boxes by hand. Describe the diagram and let `draw` lay it out, or import a Mermaid flowchart with `toucan import flow.mmd`.
- Keep boxes short. Longer text goes in a box's `meta.detail`, which opens when it's clicked.
- A sticky note on the canvas is a message to you: `toucan notes`, act on it, then `toucan notes resolve KEY --reply "what you did"`.
- Comments are threads: `toucan threads`, and `toucan threads reply N "..."`.
- Asked for an opinion, answer as a proposal (`import --propose`): it's drawn dashed, and the person accepts or rejects it.
- `toucan say "what you're about to do" --at KEY` shows them, on the canvas, what you're working on.
- A canvas can work with a named agent instead of the chat panel's own: `toucan profiles` lists them, `toucan profiles add ID --workdir DIR` makes one from an agent's folder, and `toucan --canvas NAME meta --profile local/ID` binds it.
- Write research and notes for the canvas in its files folder (`toucan files`), then `toucan show files/NAME` opens it beside the canvas. `toucan show project/README.md` or `toucan show https://…` does the same for the project's files and the web.

## More

- [Agent guide](https://lavallee.github.io/toucan/agents.html): every command and helper.
- [See it work](https://lavallee.github.io/toucan/tour.html): screenshots of real runs.
- [Source](https://github.com/lavallee/toucan), with [AGENTS.md](https://raw.githubusercontent.com/lavallee/toucan/main/AGENTS.md) in plain text.