.. _claude: ================= 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 :ref:`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: .. code-block:: text /plugin marketplace add mapperidea/claude-plugins /plugin install agent-kit@mapperidea-iadd /plugin install iadd@mapperidea-iadd Or in a terminal: .. code-block:: text 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 ~~~~~~~~ .. list-table:: :widths: 35 65 :header-rows: 1 * - **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 `` - 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: .. list-table:: :widths: 25 40 35 :header-rows: 1 * - **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** .. code-block:: text Add the Supplier entity to the sales package, with tax ID (key), company name and e-mail, and a relation to City. .. code-block:: text Read the story in docs/stories/cancel-order.md and update the business map with what is missing. Show me the changes before writing. .. code-block:: text Explain the Order class of main.mi, attribute by attribute, and point out what looks inconsistent. **Writing generators** .. code-block:: text Write a generator that creates a TypeScript interface for each class of a package, with the attribute types mapped to TypeScript types. .. code-block:: text In the Java entity generator, make the attributes marked as key become @Id. .. code-block:: text Which function do I use in a generator to turn CustomerOrder into customer_order? **Validating and generating** .. code-block:: text Push the maps and validate the Order class with the struct generator. .. code-block:: text Generate the Quarkus entity of Order into src/main/java/sales/ and check the file for EMI errors. .. code-block:: text mi generate returns an empty file for Customer. Find out why. **In Freemapper** .. code-block:: text Explain the selected node. .. code-block:: text Under this class, add the attributes birth date, phone and active. .. code-block:: text Show me in the map where the Customer class is and open its branch. .. code-block:: text 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 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 :ref:`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.