# Working with an external AI agent in MindMax

URL: https://mindmax.me/docs/guides/working-with-an-external-ai-agent/
Last verified: 2026-11-11

> A map of what a connected AI app can do in your MindMax folder — read, review, mark, think, run long jobs — and where each result lands for you to check.

## 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](https://mindmax.me/docs/guides/mind-maps-from-claude-and-chatgpt/) —
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](https://mindmax.me/concepts/edits-wait-for-you/) — a capable model does not get to skip that
step just because it lives in another app.

## The capability map[​](https://mindmax.me/#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](https://mindmax.me/docs/guides/handing-work-to-an-agent/) shows what a good
sentence looks like. The full list lives in the
[agent tool reference](https://mindmax.me/docs/reference/agent-tools/).

## Two catalogues of methods, not one[​](https://mindmax.me/#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](https://mindmax.me/use-cases/open-a-question-on-canvas-with-your-agent/)
walks through; [canvas requests](https://mindmax.me/docs/guides/canvas-requests-with-an-agent/) covers leaving a mark
on a card and asking for the next round. [Using skills](https://mindmax.me/docs/guides/using-skills/) explains the
methods themselves.

## Seven methods it can run with its own model[​](https://mindmax.me/#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](https://mindmax.me/docs/guides/long-jobs-with-an-agent/).

## Which app to use[​](https://mindmax.me/#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](https://mindmax.me/docs/getting-started/connect-an-ai-agent/).

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](https://mindmax.me/docs/guides/reading-and-reviewing-with-an-agent/) — a text
layer alone cannot show them.

## What it costs and what it cannot do[​](https://mindmax.me/#what-it-costs-and-what-it-cannot-do)

- **Local.** The server listens on `127.0.0.1` only. 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](https://mindmax.me/docs/guides/controlling-agent-access/) covers pausing and taking a
proposal back.

The whole arrangement starts here: one click in Settings → External AI, then one sentence in the app.

## The shortest path, four steps[​](https://mindmax.me/#the-shortest-path-four-steps)

- [Connect an app](https://mindmax.me/docs/getting-started/connect-an-ai-agent/) 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](https://mindmax.me/docs/guides/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[​](https://mindmax.me/#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](https://mindmax.me/docs/troubleshooting/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](https://mindmax.me/docs/guides/reading-and-reviewing-with-an-agent/) 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](https://mindmax.me/docs/guides/canvas-requests-with-an-agent/).

## Next[​](https://mindmax.me/#next)

- [Handing work to an agent](https://mindmax.me/docs/guides/handing-work-to-an-agent/) — the sentence, the scope, and
what "copy" does not mean.

- [MindMax MCP](https://mindmax.me/mcp/) — the reasoning behind the local connection and the review gate.

Last updated on **Nov 11, 2026**