Working with an external AI agent in MindMax
A connected AI app works against the folder MindMax has open, on your own computer, using its own model. That is a two-way channel: the app reads your files and writes back into MindMax, and MindMax decides what it may see, what it may change, and where you review the result. A separate arrangement — the browser handoff connectors — is one-way: an app in a browser hands over one finished document or mind map, and nothing is stored. This guide is about the two-way channel in the desktop app, which is the one with a library behind it.
Nothing is uploaded, no MindMax model runs on this path, and no credits are spent. The cost is tokens in the account of the app you connected, and the app must be running on this machine: there is no remote endpoint and no mobile version of this arrangement. Those are the trade-offs, not fine print. Every change to a document you already wrote still arrives as a proposal you review — a capable model does not get to skip that step just because it lives in another app.
The capability map
Three things can come back from a request: an opinion (a comment or a reply), a change (a proposal shown on your text), or a new artifact (a document, canvas cards, or the result of a long method). Find the action you have in mind, then follow the link for the exact steps.
| What you want | An opinion | A change | A new artifact |
|---|---|---|---|
| Read a long book or a paper | get_annotations → reading and reviewing | — | reading_guide, doc_map_notes → long jobs |
| Review without editing | add_comments / reply_to_comment → reading and reviewing | — | writing-review, review-paper prompts → tool reference |
| Revise a draft | suggest_edits.answering replies in the thread → revising documents | suggest_edits → revising documents | create_document → tool reference |
| Think a question through | list_thinking_methods → follow the method in the app's reply | — | canvas_skill → canvas requests |
| Keep thinking on a canvas | get_annotations reads canvas_request → canvas requests | revise_canvas_card on the app's own cards | add_canvas_cards, create_document{fromCanvas} → canvas requests |
| Run a whole method | comment_answers, comment_insights → long jobs | translation, ocr → long jobs | start_pipeline → long jobs |
| Decide what it may do | — | — | Read only / collaborate → controlling access |
The tool names are what the app sees; you do not have to say any of them. Say the job in plain words — handing work to an agent shows what a good sentence looks like. The full list lives in the agent tool reference.
Two catalogues of methods, not one
This is the distinction most people miss when they first connect an app.
For a job on a document — proofread, review, verify claims, handle comments, prepare a book —
the app calls find_document_method with what you said. You name the job, never the method. Hosts
that show a / menu also offer ten ready-made prompts directly:
proofread | writing-review | resolve-comments | verify-claims | write-from-library |
|---|---|---|---|---|
comment-insights | prepare-book | review-paper | critical-read | study-guide |
For thinking that produces no document — brainstorming, root causes, weighing options, red
teaming, MECE, SWOT — the app calls list_thinking_methods. It reads one named method in full and
then does one of two things: follow that method in its own answer and tell you which one it used,
or start canvas_skill to lay the method out on a canvas. The second path is what
opening a hard question on the canvas with your agent
walks through; canvas requests covers leaving a mark
on a card and asking for the next round. Using skills explains the
methods themselves.
Seven methods it can run with its own model
MindMax normally runs these with its own model. A connected app can run the same ones step by step: MindMax plans, checks and saves; the app's model does the thinking.
| Method | What you end up with |
|---|---|
reading_guide | A full annotation pass with a guide, review, critique or study lens |
comment_answers | An answer in each waiting comment thread |
comment_insights | An insights note distilled from your highlights and comments |
doc_map_notes | Chapter notes written into a long book's map |
canvas_skill | One thinking method laid out on a canvas |
translation | A whole-document translation with one terminology list |
ocr | Recognised text for scanned pages, page by page |
The three calls that drive any of these — start_pipeline, get_step, submit_step — are in
long jobs with an agent.
Which app to use
Claude, Claude Code, Codex and the ChatGPT desktop app are verified end to end; Cursor, Windsurf and WorkBuddy can be connected in one click and are confirmed on their first real call. For a long book or a folder of papers, a command-line app with a large context (Claude Code or Codex) is the easier fit; a desktop chat app is fine for one document and a few rounds. ChatGPT desktop shares Codex's configuration entry, so restart it after connecting. The full per-app table is in connect an AI app.
A long document does not come back as a wall of text: MindMax returns a map of roughly 12k characters for a 550-page book, then the app reads the sections it needs whole. Figures, formulas and scanned pages need page images — a text layer alone cannot show them.
What it costs and what it cannot do
- Local. The server listens on
127.0.0.1only. MindMax must be running; it starts in the background if it is not. There is no remote endpoint, so an agent on a server or a phone cannot reach your library. - No MindMax credits. No MindMax model is called on this path. The tokens are billed to the account of the app you connected, roughly one pass over the material for a full reading guide.
- A review gate. A change to an existing document is proposed, never applied silently. You accept or reject it in groups. Nothing is overwritten and nothing is deleted.
- Visible. The status bar names the app while it works, each app has its own session entry, every write is attributed in version history, and calls stay in a local audit log for 30 days. Controlling agent access covers pausing and taking a proposal back.
The shortest path, four steps
- Connect an app and open the folder you care about.
- Say one sentence in the app: what to do, how, and what to hand back — see handing work to an agent.
- Come back to MindMax and look in the margin, the review card, the canvas or the reading panel — wherever that sentence said the result would land.
- Review once. Accept what holds, reject what does not, and reply on the same thread for the next round.
Common problems
The app answered in its chat window and nothing appeared in MindMax. Then it did not call a write tool — it just told you what it would do. Ask it to put the result in the library, or check common issues for a host that used its own file-writing tool instead.
You asked for a review and got a rewritten file. Say "leave comments, don't change the text". A change to an existing document still needs your acceptance before it is written.
It cannot see a chart or a scanned page. Ask for the page as an image; reading and reviewing shows the exact sentence.
The canvas looks unchanged in a terminal app. Some hosts cannot display images. MindMax opens the canvas in front instead and the app tells you where — see canvas requests.
Next
- Handing work to an agent — the sentence, the scope, and what "copy" does not mean.
- MindMax MCP — the reasoning behind the local connection and the review gate.