Using Claude Code

Claude Code can read, write and validate Mapper Idea maps for you. You describe what you want in plain language, and Claude edits the .mi files, runs the mi CLI and shows the result in Freemapper. This chapter lists what to install, the commands of the Mapper Idea plugin and examples of prompts.

What you need

Claude Code, with a Claude account: https://claude.com/claude-code
The Mapper Idea plugins for Claude Code (agent-kit and iadd): https://github.com/mapperidea/claude-plugins
The Mapper Idea CLI (mi) installed and signed in with an authorized user. Without it Claude can write maps, but cannot validate or generate anything. The links are on the Tips page.
Freemapper (optional), to see the maps change while Claude works and to open Claude Code inside it.

Installing the plugins

Inside Claude Code:

/plugin marketplace add mapperidea/claude-plugins
/plugin install agent-kit@mapperidea-iadd
/plugin install iadd@mapperidea-iadd

Or in a terminal:

claude plugin marketplace add mapperidea/claude-plugins
claude plugin install agent-kit@mapperidea-iadd
claude plugin install iadd@mapperidea-iadd

Open a new session after installing: a session that was already open does not see the new commands and answers Unknown skill. To update later, use /plugin marketplace update mapperidea-iadd.

Commands

Command	What it does
`/iadd:init`	Prepares the project: converts existing FreeMind maps (`.mm`) to `.mi`, finds the main map and installs the three agents, asking you what is specific to your domain. Run it once, at the root of the project.
`/iadd:init <agent>`	Installs or reinstalls one agent: `domain-mapper`, `generator-author`, `cli-runner` or `todos` (all). It asks before replacing anything.
`/iadd:mi` or `/iadd:mapperidea`	The `.mi` specialist: reads, writes, validates and explains business maps, architecture maps, generators, icons and types. Claude also calls it by itself when the subject is a `.mi` map.
`/agent-kit:agent-creator`	A wizard that interviews you and writes a new Claude Code agent for your project.

You do not have to type the commands to use them: asking in plain language ("convert my .mm maps to .mi") is enough, and Claude picks the right one.

The three agents

/iadd:init installs three agents in .claude/agents/. Each one owns one part of the work, so the one that models does not generate and the one that generates does not change the model:

Agent	Owns	Touches
`domain-mapper`	The business map: entities, attributes, relations, rules	Only the business `.mi` files
`generator-author`	The generators: how the map becomes code in your stack	Only the generator `.mi` files
`cli-runner`	The real validation and generation, through the `mi` CLI	Runs `mi`, does not edit maps

You talk to Claude as usual and it hands the task to the right agent. What the plugin writes in your project (agents, their memory, guides, hooks) is yours: it keeps working without the plugin and is meant to be edited and committed.

Claude in Freemapper

Freemapper can let Claude Code see the open maps: the selected node, the text of a map, a picture of the screen. Turn it on in Preferences > Environment > AI integration:

Let an AI assistant see and navigate the open maps starts a local server that only this computer can reach, protected by a token.
Also let the assistant change the maps adds the tools that insert, change and remove nodes. Every change appears on screen and can be undone with Ctrl+Z; nothing is saved until you, or Claude, save the map.

Restart Freemapper after changing these options. Then there are two ways to use Claude:

Inside Freemapper: View > AI Assistant (Alt+9) opens a panel with Claude Code running in the folder of the project, already connected to the maps. The panel can move to its own window, keeps one tab per project and can use other Claude accounts through profiles.
In your own terminal: the AI integration: copy the Claude Code command item copies a command; paste it in a terminal once, and from then on Claude Code sees the maps open in Freemapper.

When Claude changes a .mi file on disk, Freemapper reloads it and selects the node that changed.

Prompt examples

These are starting points: replace the names with the ones in your map. The more precise the prompt (which map, which package, which class), the less Claude has to guess.

Modeling the business

Add the Supplier entity to the sales package, with tax ID (key), company name and e-mail,
and a relation to City.

Read the story in docs/stories/cancel-order.md and update the business map with what is
missing. Show me the changes before writing.

Explain the Order class of main.mi, attribute by attribute, and point out what looks
inconsistent.

Writing generators

Write a generator that creates a TypeScript interface for each class of a package, with
the attribute types mapped to TypeScript types.

In the Java entity generator, make the attributes marked as key become @Id.

Which function do I use in a generator to turn CustomerOrder into customer_order?

Validating and generating

Push the maps and validate the Order class with the struct generator.

Generate the Quarkus entity of Order into src/main/java/sales/ and check the file for
EMI errors.

mi generate returns an empty file for Customer. Find out why.

In Freemapper

Explain the selected node.

Under this class, add the attributes birth date, phone and active.

Show me in the map where the Customer class is and open its branch.

Take a picture of the map and tell me which classes have no key attribute.

Tips

Say what Claude should not change ("only the sales package", "do not touch the generators").
Ask for the validation: a map is only checked when mi generate <project> struct xml runs on the class. The agents know this, but asking makes it explicit.
Claude asks before running mi push, because it sends the maps to the Mapper Idea cloud. To skip the question, say it in the prompt, as in "push the maps and generate...".
After generating, look for EMI in the output: a CLI error printed to the output goes into the generated file.
For a question about an XPath function, Claude can open the page of that function in this guide, such as mi:lower-case-add-underline.
The plugin manuals, with the whole method (docs/pipeline-iadd.md) and how to write a generator from scratch, come with the plugin; ask Claude to open them.