AI assistants

An AI assistant, such as Claude, Gemini or Codex, can build a Terraflux model for you. You ask in plain words ("read my land use map of 2010, find the forest, and measure how fragmented it is with MSPA"), and the assistant adds the nodes, connects them, sets them, checks the model and runs it. If the model is open in the application, you watch every node appear on the canvas as it is added, and you can change or undo anything the assistant did.

The connection uses the Model Context Protocol (MCP), an open standard that lets an assistant use the tools of another program. terraflux mcp is a small server that gives the assistant Terraflux's tools. It runs on your computer: your maps stay where they are, and the assistant reads only what the tools return (the model, the problems found in it, and summaries of the results).

What the assistant can do#

Every edit is checked the way the application checks the edits you make yourself. A connection of the wrong type (a table into an input that takes a map), a setting the operator does not have, or a loop of nodes reading each other is refused, the reason is given to the assistant, and the model file is left as it was. After each edit the assistant is told the problems the model still has, so it can go on fixing them.

Guides, advice on the method, prompts#

An assistant knows a lot in general and little of your field's good practice in Terraflux. The server tells it that good practice where it is needed, rather than all at once:

• Guides. When it connects, the assistant gets short instructions (clients cut long ones) that send it to the guide of the field before it builds: the steps of a land change model (analyse the change, calibrate on the first period, simulate, validate on a date not used to calibrate, run several seeds), of connectivity, of landscape metrics, of conservation planning, of a species distribution model, and of putting the data on one grid, each step with its operators and templates.
• Advice on the method. check_model, and the reply to run_model, add what a reviewer of the paper would ask, each with what to do and the guide that tells more: a land change simulated but never compared with an observed map, or compared with the map it was calibrated on; a stochastic simulation run once; distances, areas or landscape metrics on maps in degrees; metrics of a continuous map; a species distribution model evaluated only on random folds. inspect_file says when a raster is in degrees or has no coordinate system.
• Prompts. Workflows you start by name, with their arguments: build_model (a goal, your data, the file), adapt_template (a template with your files in place of its drawn data), review_model (the method reviewed as a paper's reviewer would, without changing the model), explain_model and explain_cell. In Claude Code they are slash commands: /mcp__terraflux__review_model D:\forest\model.toml.
• Resources. The guides (terraflux://guide/land-change), the templates' files (terraflux://template/dinamica-ego) and any operator's documentation (terraflux://operator/woe.fit), for the clients that let you attach them to a message (@ in Claude Code).

The application's own assistant has the same guides and the same advice.

Connect an assistant#

The assistant starts terraflux mcp by itself whenever it needs it: you only tell it once where the program is.

{
  "mcpServers": {
    "terraflux": {
      "command": "C:\\Users\\you\\AppData\\Local\\Programs\\Terraflux\\terraflux.exe",
      "args": ["mcp"]
    }
  }
}

claude mcp add --scope user terraflux -- terraflux mcp

gemini mcp add -s user terraflux terraflux mcp

{ "mcpServers": { "terraflux": { "command": "terraflux", "args": ["mcp"] } } }

codex mcp add terraflux -- terraflux mcp

[mcp_servers.terraflux]
command = "terraflux"
args = ["mcp"]

If the assistant says it cannot find terraflux, give the full path to the program instead (see the Claude Desktop tab for where it is installed).

Work with it#

Start by opening the application, or ask the assistant to open the model there (open_in_app): the model opens in the Terraflux you have open, in place of its own, and the window comes to the front. A new window opens only when none is open, or when the model in yours has edits not saved (they are never lost). Then ask for what you want, as you would ask a colleague who knows Terraflux:

Make a model in D:\forest\fragmentation.toml that reads D:\forest\landcover_2020.tif, where class 3 is forest, and computes MSPA with an edge width of 2. Open it in Terraflux.

Add the forest's area density at three scales, and write the MSPA map to a GeoTIFF.

Run it and tell me how much of the forest is core.

A good way to work:

• Give full paths to your files and to the model. The assistant may not know which folder you mean.
• Name your classes. Say what each value of your maps means ("1 is pasture, 2 is forest"). The assistant cannot guess it from the file.
• Start from a template when one is close to what you want. Ask "which templates are there for connectivity?" and then "start from the habitat network template, with my map in place of the drawn one".
• Look at the canvas. The application follows the model's file: every edit appears there as it is made, and the status bar says so. Click the nodes to see their outputs, as with any model.
• Read the notes. Ask the assistant to write in each node's note why it is there. The notes stay in the model and are shown in the node's panel.

The application's own assistant#

The application has an assistant of its own too, in the Assistant pane (View > Assistant): a chat with a language model on a server you choose, which reads, explains, changes and runs the model open with the same tools as terraflux mcp. Its ⚙ (the server's settings) starts with a list of servers: HU Berlin (KI-Service), GWDG Chat AI (Academic Cloud), Ollama (this computer) and LM Studio (this computer) (offline, no key), OpenAI, Claude (Anthropic), and Other (any server of OpenAI's chat completions API). A key, when the server needs one, is kept in your system's store of credentials. Test the connection checks that the server answers, has the model, and lets it call tools.

While it works, the nodes it reads or changes glow on the canvas: a halo in the accent colour that widens and fades in a couple of seconds, so you can follow which part of the model it is looking at. Each change it makes is an edit of its own (Ctrl+Z undoes it), and its pane counts the changes not reviewed yet (3 change(s) to review), with Review, Accept all and Reject all.

Check what the assistant built#

An assistant can be wrong: it may choose an operator that does not fit your question, or a setting that does not suit your landscape. The checks catch a model that cannot run, and the advice on the method the most common slips, not a model that answers the wrong question. Before you use the results:

• read the model on the canvas, node by node, and make sure each step is one you would have chosen;
• check the settings that carry ecological meaning (an edge width, a dispersal distance, a threshold) against your species and your data;
• compare a result with what you know of the place, as you would for any model you built yourself.

The Changes pane: what the assistant changed#

When an assistant changes the model open in the application, Terraflux keeps the model as it was before the first change and lists what differs from it in the Changes pane, at the right of the window. When the change comes through terraflux mcp, the pane comes to the front as soon as the application reads the changed file; the application's own assistant counts its changes in its pane instead, and its Review opens them here. View > Changes opens the pane at any time. It works like the review of a pull request: you go through the changes one by one and keep or undo each.

Each change is a card, marked + for a node added, ~ for a node changed and − for a node removed; the model's inputs, its outputs and its record (its name, description, request, summary and author) have cards of their own. Under the title, a line per difference, before and after: setting edge_width: 1 → 2, input map: forest.map, a note or a why rewritten, a node added inside a loop. A node that was only moved on the canvas is not a change. On the canvas, the nodes added are outlined in green and the nodes changed in amber.

For a node added or changed, the card also shows what its first output gives, before the changes and now: two small maps side by side, drawn in the same colours, or two tables side by side, in which the cells that changed (matched by the row and by the column's name) are in amber, and a column only one of the tables has is in red (before) or green (now). The rows are matched by a key when the tables have one, said above them (rows matched by class): a column of both whose values are whole numbers or names, none twice, some in both (id, key, class, value, code, name... first, else the first such column), shown first. So a class taken away, added or moved to another row is not a whole table of changes: a row only the table before has is in red, a row only the table now has in green, and a row matched is compared cell by cell wherever it is. Without a key the rows are matched by their place. A number or a text is said in words. Before is what the last run before the changes gave; now fills in when the model runs again. This is the quickest way to see whether a new threshold changed the map a little or a lot.

On each card, ✔ keeps the change (it leaves the list), ✖ undoes it (the model as it was there, an edit that Ctrl+Z undoes in its turn), and Show selects the node on the canvas. Accept all keeps every change and Reject all puts the whole model back as it was. When no change is left, the review ends.

Terraflux keeps the model as a plain file, so the work stays reproducible: what the assistant built runs again with terraflux run, without the assistant.