Canvas requests with an external AI agent
A canvas request is a mark you leave on a card or on one point under it, asking a connected AI app to keep thinking from exactly there. The request stays with the card as data, the app reads it on its next visit, and its answer comes back as new cards hanging off the branch you pointed at. MindMax does not wake the app up: marking a request copies one sentence for you to paste into your app. That is the whole handoff — a sentence, not a queued job.
This is the path for work that grows over several rounds. If you want a question opened up in one pass, open a hard question on the canvas with your agent is the shorter read; thinking on the canvas covers the board itself.
Before you start
- A canvas in the folder MindMax has open, with at least one card you want to pull on.
- An app connected with Collaborate access — adding cards is a write.
- The canvas brought to the front, so "this card" has an unambiguous meaning.
Mark a request
- Hover a point under a card and press Hand to {app}, or open the card's ⋯ menu and choose Hand to {app}… for the whole card. These entries appear only when a writable external app is connected.
- Write what you want — "compare these two options", "what would have to be true for this to fail?" — or leave the text empty. An empty request means keep thinking from here.
- The card gets a small signed strip showing how many requests are waiting, and a toast offers Copy that sentence. The canvas bar has the same Copy prompt next to the waiting count.
Handle the requests I marked on the canvas "Q3 pricing options" in MindMax, and add your cards under the ones I marked.
Paste that into your app and send it. Copying changes nothing: the canvas keeps the request in its waiting state until an app actually reads and answers it. See handing work to an agent for why the button is a sentence-writer and not a submit button.
What the app reads
| Step | What happens | Tool |
|---|---|---|
| "This one" | MindMax reports the canvas in front, the selected card, the point last clicked and the branch path to it | get_active_context with canvasSelection |
| The waiting requests | A list of canvas_request items, by default only the pending ones, with ids like canvas-ask:<id>@<path> | get_annotations |
| Only what changed | Pass back the "Read at" timestamp from the last read to get just the delta | read_canvas {since} |
| The whole board | Cards, who wrote each one, the points under them and the relations drawn — including your answers and which branches you dug into | read_canvas |
The app then writes cards with add_canvas_cards, attaching them to the card (and point) you marked,
naming the request ids in answering. That marks the requests handled and points them at the new
cards. A short answer can instead go through reply_to_comment with the canvas-ask: id. On the
card, the strip changes to show the reply and a link to the new cards; you can reopen a request if
the answer missed, or delete it.
What you will see, by host
show_canvas is called once at the end of a round. All three tiers can call it — the difference is
only how the picture is shown:
| Host | What you see | What the app tells you |
|---|---|---|
| Hosts with interactive cards (including ChatGPT desktop) | The canvas as a clickable card in the chat; click a card to ask the app to keep exploring it | A line or two on what was added and where to look |
| Most other desktop hosts | A picture of the whole canvas after the text, with the new cards highlighted | A line or two on what was added |
| Terminal hosts (Claude Code, Codex) | No picture in the chat. MindMax brings the canvas to the front in its own window | "It is open there (link), and here is what the new cards say" |
Not seeing a picture does not mean nothing was drawn. The cards are in the canvas file either way. In a terminal host, switch to MindMax and the board is already in front with the new cards in view. The tier is decided at connection time from what the host says it can display — there is no setting to change it.
What the app may change
It can add cards and points, draw support, contradiction or reference relations between cards
with link_canvas_cards, and revise cards it wrote itself with revise_canvas_card. On cards
MindMax generated it may only append points; on cards you wrote, revision is refused. Moving cards,
changing colours, deleting cards and rewriting your cards have no tool at all — those stay yours in
MindMax. Question cards you answered can be graded with grade_canvas_answers, which adds a verdict
and a note to your answer.
When a branch is settled, create_document with fromCanvas {path, nodeId?} writes it up as a new
document and hangs a linked document card back on the canvas, so the board shows which branch became
which note. Brainstorm a product with your agent
walks that path end to end.
Common problems
The request is still waiting. You copied the sentence but did not send it, or the app used a read-only connection. Send it in the app, then look at the card's strip again.
New cards appeared at the top level instead of under my point. Name the card in the sentence and
keep it selected when you copy, so canvasSelection carries the branch.
The app tried to rewrite my cards. That is refused by design. Ask it to add a new card instead — the original stays yours.
Claude Code says the canvas is open but shows nothing. It is open in the MindMax window. Switch to it; the app's reply should include the link and a summary of the new cards.
Next
- Long jobs with an agent — when the thinking needs a whole method rather than one round of cards.
- Working with an external AI agent — the capability map.