Bootstrap a Mendix App in an Empty Repo

When to Use This Skill

Use this when a repo has no Mendix project yet and you have been asked to provision one with mxcli — typically from the empty-repo seed prompt, which does nothing but install mxcli, run mxcli init --sync-skills, and send you here.

Everything the seed prompt used to spell out lives here instead, so the prompt stays short enough to paste from a phone and this procedure can be fixed by shipping a new mxcli rather than by re-pasting a longer prompt.

If an .mpr already exists, this is the wrong skill: run mxcli init in the app folder and go straight to the work.

Related skills: run-local (the warm dev loop this ends in), mdl-entities and create-page (building the model you propose at the end), migrate-design-prototype (when a design was handed to you), assess-quality (reading the report this takes a baseline with), test-microflows and test-app (the two gates that prove behaviour rather than syntax).

---

Step 0 — interview, and WAIT for the answers

Ask all of these in ONE message, numbered, each with the default you would pick, so the user can reply "defaults" or answer only what they care about. Do not provision anything until they reply.

The interview comes first for a reason: the app name becomes the .mpr file name, the Studio Pro app name and the path baked into the SessionStart hook, so it is far cheaper to ask than to rename afterwards. The rest of the answers are the brief — they get written into the repo, so the session that resumes after an idle reap knows what it is building.

1. One app, or a solution of several? One Mendix app is the default. "Solution" means several apps in one repo — e.g. a backend that owns the data and publishes OData/REST, and a frontend that consumes it. If so, ask for each app's name and one line on what it owns, and follow "If this is a solution" below.

2. App name. Becomes the .mpr file name, the app name in Studio Pro, and the path in the session hook, so it is awkward to change later. One PascalCase word, letters and digits only — OrderPortal, FieldService, ClubAdmin. Propose one derived from the answer to Q3.

3. What is the app for? One or two sentences: who uses it, and what it lets them do. If the answer is vague ("a tool for work"), ask one follow-up — everything below is derived from this.

4. What does it keep track of? Three to six nouns that will become entities, and a word on how they relate (e.g. "a Job has many Visits; each Visit has Photos"). For a solution, also ask which app owns each noun. Ask two follow-ups here, because both change the model rather than decorate it: does anything go through steps someone has to act on (approval, hand-off, review, a deadline), and is there a number or count across records anyone needs to see. The first is a workflow and the second a view entity — see "Two choices to make deliberately" below.

5. Who logs in? The user roles, and roughly what each may do (e.g. "Requester creates and sees their own; Approver sees everything and approves").

6. Look and feel. One of the bundled themes: signal (light, high contrast), ledger (light, dense, data-heavy), console (dark), or none for stock Atlas. Default signal.

7. Mendix version. Default to whatever the session environment already provides — see below — and otherwise the newest version on the CDN (today 11.14.0).

8. Do you have requirements to work from? A specification document, a prototype, a wireframe, a long description — anything that is the source of truth but is not in this repo. Default: yes, record them. If they say yes, ask them to paste or point at it; if they say "just build it", say in one line that you will record the slices you derive as you go, and carry on.

   This one is not cosmetic. Requirements that live in a Word document, a Figma file or a chat window leave no trace in git: not in an issue, not in a commit message. A session that resumes after an idle reap has no idea what it was building towards, and neither does the next person. Recording them costs a minute now and is unrecoverable later.

If the user says "defaults" or ignores a question, choose something sensible for it, say what you chose in one line, and keep going — do not block on them twice.

Choosing the Mendix version

Prefer a version the environment already has. A Claude Code session image may bake in an MxBuild, and using it turns a multi-hundred-MB download into no download at all. There is no environment variable for this — the cache directory is the signal:

ls ~/.mxcli/mxbuild/ 2>/dev/null | sort -V | tail -1   # e.g. 11.13.0, or empty

If that names a version, use it and say so in one line ("using 11.13.0, already cached in this environment"). If the user asked for a specific version, they win — check it on the CDN as below and accept the download.

Otherwise take the newest version on the CDN. Everything mxcli does starts with downloading MxBuild, so "supported" means "on the CDN", and run --local needs the runtime tarball as well. At the time of writing the newest is 11.14.0 (11.15.0 is not published). Do not trust that number — it ages. Confirm the one you land on, and walk backwards a minor if it 404s:

V=11.14.0
curl -sI -o /dev/null -w '%{http_code}\n' https://cdn.mendix.com/runtime/mxbuild-$V.tar.gz
curl -sI -o /dev/null -w '%{http_code}\n' https://cdn.mendix.com/runtime/mendix-$V.tar.gz

Both have to answer 200. Run the same check for any version the user names.

In a solution, give every app the same version: they share the ~/.mxcli/mxbuild cache, and a mismatch means a second multi-hundred-MB download and two runtimes to keep straight — which also means the cached-version rule applies to the solution as a whole, not per app.

---

Provision

Substitute the answers for <AppName>, <version> and <theme> throughout. For a solution, do steps 1–3 once per app and read "If this is a solution" first. The commands below say ./mxcli because that is where the seed prompt puts the binary — drop the ./ if it came pre-installed on PATH.

1. Create the app at the repo root — that is where .claude/ and the ./mxcli binary have to live for future sessions to self-bootstrap. mxcli new refuses to write into a directory that is not empty, and a git repo always has .git, so create it in a subfolder and move it up:

   ./mxcli new <AppName> --version <version> --theme <theme>
   rm -f <AppName>/mxcli        # a hardlink to the ./mxcli you just ran; mv would
                                # refuse it as "the same file". Still needed when
                                # mxcli is already on PATH — `new` hardlinks it
                                # into the project either way.
   rm -rf .ai-context           # the seed prompt's own `mxcli init --sync-skills`
                                # wrote this; `mxcli new` writes its own copy from
                                # the same binary, so the one here is a stale
                                # duplicate and `mv` fails with
                                #   mv: cannot overwrite './.ai-context': Directory not empty
   shopt -s dotglob && mv <AppName>/* . && rmdir <AppName>
   

   mxcli new also runs mxcli init, which writes .claude/settings.json with a SessionStart hook plus the .claude/bootstrap-mxcli.sh it runs — check that the .mpr named in the script is right after the move.

2. Confirm the Claude tooling: ./mxcli init --tool claude. Idempotent — it is what step 1 already ran, and re-running it is the cheapest way to be sure the hook, skills and commands are in place.

3. Bring prerequisites up: ./mxcli run --local --setup --ensure-db -p <AppName>.mpr (caches MxBuild + runtime, starts Postgres, creates the app database).

4. Write the brief to README.md at the repo root: the app name(s), the answers to Q3–Q5 in the user's words, and the theme and Mendix version used. For a solution, say which app owns what and how they talk to each other. This is what tells the next session — after an idle reap, with none of this conversation — what it is building. Keep it short enough that it stays true.

5. Start a FINDINGS.md at the repo root and keep appending to it as you work. Log anything surprising or broken: an mxcli command that errored, a workaround you applied, a mxcli check that passed but a real mx check later flagged. Note the Mendix + mxcli versions and how each finding was verified. This is durable context for the next session, and the most useful thing to share back to improve mxcli.

6. Record the plan in the brain — unless the user opted out at Q8:

   ./mxcli brain init -p <AppName>.mpr
   ./mxcli brain capture "<one requirement, in the user's words>" \
     --slice 01-<first-slice> -a @<AppName>Module.<WhatWillImplementIt> \
     -p <AppName>.mpr
   ./mxcli brain staged -p <AppName>.mpr    # then promote each
   

   Split the requirements into slices you could deliver one at a time, named with a numeric prefix so they sort into a roadmap: 01-accounts, 02-approvals. Anchor each requirement at what will implement it — the entity, microflow or page you are about to create. The anchor points forward, so naming something that does not exist yet is correct here, and it is what makes ./mxcli brain plan a real progress report instead of a checklist.

   Read .ai-context/skills/project-brain/SKILL.md before doing this.

   Two things to keep straight, because they are easy to conflate:

   • README.md is the brief — what the app is, in the user's words, for a human landing on the repo. One page, written once.
   • docs/brain/plan/ is the scope — the individual requirements, anchored and countable, appended to as they emerge.

   Never write a status or a tick-box next to a requirement. Whether it is built is computed by ./mxcli brain plan from the model; a hand-maintained status is wrong the moment anyone builds anything, and nothing will tell you.

7. COMMIT everything now — <AppName>.mpr, .devcontainer/, .claude/ (the SessionStart hook and .claude/bootstrap-mxcli.sh), README.md, FINDINGS.md and docs/brain/. This step is mandatory, not housekeeping: the seed prompt is a one-time seed, and committing its output is what makes every later session bootstrap from files instead of from a re-paste. The mxcli binary itself stays git-ignored (~85 MB); the bootstrap script is what fetches it back into a fresh clone, so committing the script is what makes the hook survive a reap.

8. Boot and verify: ./mxcli run --local -p <AppName>.mpr in the background, then confirm the app answers HTTP 200 at http://localhost:8080/ and report.

9. Take the quality baseline — run the two gates that score the project, on the blank app, before any of your own work is in it:

   ./mxcli lint -p <AppName>.mpr
   ./mxcli report -p <AppName>.mpr --format markdown
   

   Report the warning count and the six category scores, and put them in FINDINGS.md with the date. This is the only moment the numbers mean "what the template ships with" — afterwards every figure is yours plus the template's, and there is nothing to subtract. A blank app is not expected to score zero warnings; knowing which ones it starts with is what stops you chasing them later. Read .ai-context/skills/assess-quality/SKILL.md before interpreting the report — it covers what each category means and which findings are worth acting on.

10. (Optional) browser preview from a cloud session: ./mxcli run --hub https://hub.mxcli.org -p <AppName>.mpr, and report the preview URL it prints. Needs MXCLI_HUB_KEY on the environment; without it, continue as a normal local run. --hub ships in the Linux build only (a cloud session is a Linux container, so it works there); on a native Windows/macOS mxcli it fails with an explanatory message — continue as a normal local run.

---

If this is a solution (several apps in one repo)

Each app is a full Mendix project — one .mpr, one runtime, one database. Same steps, with these deltas:

• Layout. One subfolder per app, nothing at the repo root but README.md, FINDINGS.md and .claude/. Run mxcli new <AppName> --version <version> --theme <theme> once per app and leave each where it lands; do not move anything up.

• Ports. Every app defaults to 8080/8090/6543 and they will collide. Give the first app the defaults and the second --app-port 8180 --admin-port 8190 --serve-port 6643. Avoid 8081/8091/6544 — mxcli test --local uses those.

• Give each app its own hostname, not just its own port. Cookies are keyed on host name and ignore the port, so two apps on localhost:8080 and localhost:8180 share one cookie jar: logging into one can silently replace the other's XASSESSIONID. Two hostnames give two jars, and the differing ports do no harm. Add them to /etc/hosts —

  127.0.0.1  backend.local frontend.local
  

  — and browse http://backend.local:8080/ and http://frontend.local:8180/. The runtime binds 127.0.0.1 and serves any Host you send it, and the client uses relative URLs, so it works under any name that resolves to loopback. (*.nip.io works too if you would rather not touch /etc/hosts; prefer /etc/hosts in a locked-down container, where public wildcard DNS may not resolve — localtest.me resolves to ::1 in some of them.)

  Then record the name in each app's own configuration, so the runtime knows the URL it is reached at and generates absolute URLs — OIDC/SAML redirect URIs, deep links — against the host name rather than the listen address:

  alter settings configuration 'Default'
    ApplicationRootUrl = 'http://backend.local:8080/';
  

  run --local picks that up at boot and prints which configuration it came from. A blank app ships http://localhost:8080/ there, and that stock loopback value is deliberately ignored — otherwise every project would start advertising a URL, and the wrong port under --app-port. Only a real host name is passed through.

• Databases need no action: the name is derived from the .mpr file name, so differently-named apps get different databases.

• The session hook. mxcli init writes .claude/settings.json inside each app folder, but Claude Code reads the one at the repo root — and it will not add a second entry for you (it dedupes on the command, not on the project). Write the root one yourself, one line per app, e.g. test -x backend/mxcli && (cd backend && ./mxcli run --local --setup --ensure-db -p Backend.mpr) || true. Verify it by checking that a fresh shell can boot each app.

• Previews. Pass --hub-solution <SolutionName> to every run --hub so the apps appear grouped in the hub overview instead of as unrelated previews.

Wire the integration in dependency order — the producer must be running first. CREATE ODATA CLIENT fetches the $metadata at the moment you create it and caches it in the model; if the URL is unreachable it warns and leaves the client unvalidated, with no external entities to import. So: publish on the producer (CREATE ODATA SERVICE … publish entity …), boot it (run --local), and only then, on the consumer, CREATE ODATA CLIENT … MetadataUrl: 'http://backend.local:8080/odata/…/$metadata' followed by CREATE EXTERNAL ENTITIES FROM …. Use the hostname here too, so the cached contract and the constant below agree with what the browser sees. Point ServiceUrl at a constant (ServiceUrl: @Module.SvcUrl) so the address can be changed per environment without touching the model — it will not stay localhost. mxcli syntax odata.publish and mxcli syntax odata.consume have the full syntax; business events (mxcli syntax business-events) are the alternative when the link should be asynchronous.

---

Then propose the model — do not build it yet

The blank template ships a MyFirstModule; the app's own work belongs in a module named after it. From the brief, propose in chat:

• a module name, and the entities from Q4 with their attributes and associations
• the user roles from Q5 and what each may read/write
• the handful of pages that make it usable
• for a solution: which app owns each entity, and what crosses the boundary — publish only what the other app actually needs

Two choices to make deliberately — the lazy answer is wrong both times

Both of these are first-class in Mendix and both are easy to reinvent in microflows, because the microflow version works: it passes check, it builds, and nothing flags it. The cost lands later, on someone else.

• A business process with human steps is a WORKFLOW, not a status attribute and a handful of microflows. Approvals, hand-offs, "someone has to look at this", anything with a due date or a timer, anything that can sit waiting for days. You get the state machine, the user-task inbox (System.WorkflowUserTask), assignment and targeting, timers and boundary events, and a definition the business can read. Rebuild it from status attributes and every one of those is yours to write and maintain, and the process stops being inspectable — nobody can answer "where is this request" except by reading microflows. create workflow; see mxcli syntax workflow and the write-workflows skill.
• An aggregation is a VIEW ENTITY, not a microflow that retrieves the rows and counts them. Totals, counts per group, a figure on a dashboard, a report, anything joined across entities: a view entity is OQL the database executes — joins, GROUP BY, SUM/COUNT — returning rows a page binds to directly. The microflow version pulls every object into memory to produce one number, and it gets slower exactly as the app succeeds, which is the worst possible failure curve. Needs Mendix 10.18+ (show features confirms it). create view entity Mod.Name (…) as ( select … ) — see mxcli syntax view-entity for the shape, its oql and association subtopics for the rules that bite (every column needs an AS alias; ORDER BY needs a LIMIT; selecting an id under an alias makes an association, not an attribute), and the write-oql-queries skill for worked queries.

Name which of the two you are using in the proposal, with one line on why. Both are cheap to choose now and expensive to retrofit: the pages, security rules and tests all bind to whichever you picked.

Show it as MDL the user can read, and wait for their go-ahead before executing it. Name the elements the same way the plan's anchors do — if a requirement is anchored @<AppName>Module.ACT_Approve, propose that name — so ./mxcli brain plan starts counting the moment the work lands, without anyone editing the plan. If a design was handed to you, it is the source of truth for the model and the pages — see migrate-design-prototype.

---

After bootstrap — the inner loop

./mxcli run --local -p <AppName>.mpr --watch --screenshot   # warm dev loop + screenshots
./mxcli exec change.mdl -p <AppName>.mpr                     # edit the model; the loop hot-applies

The gates — the same list the project's CLAUDE.md publishes

mxcli init wrote these into the project's CLAUDE.md, so every later session has them in context. They are the definition of done, not a menu: run them in order, stop at the first that fails, and say what each one reported.

Run them once per change, not per edit — a change being a coherent unit of work, not a single statement and not a file write. Iterate with exec until the script is right, then run the gates once over the result. The whole list after every edit costs ~55s and five calls each time and proves nothing the one run at the end does not.

./mxcli check change.mdl -p <AppName>.mpr --references   # syntax + references (~2s)
./mxcli exec change.mdl -p <AppName>.mpr                 # apply
./mxcli lint -p <AppName>.mpr                            # rules (~3s)
./mxcli report -p <AppName>.mpr                          # scored quality report
./mxcli docker check -p <AppName>.mpr                    # mxbuild, the slow one (~25s)
./mxcli test tests/ -p <AppName>.mpr --local             # microflow tests (~30s cold, ~2s warm)
./mxcli run --local --watch -p <AppName>.mpr             # the app, hot-reloading

Two of them are easy to mistake for optional and are not:

• report is the quality report, and its six category scores are what the baseline in step 9 exists to be compared against. A score that fell is a finding, not a detail. assess-quality covers how to read it.
• test needs a suite to run. Write the first one with the first microflow you build — not "later", because later is after the code is written and the expected values have stopped being obvious. One tests/<Slice>.test.mdl per slice is the shape that keeps up; test-microflows has the annotations, and --local needs no Docker daemon. For pages and rendering, test-app drives a real browser: a page can serialize correctly, pass check, build clean and still render wrong.

Keep the plan current as you go — it is the only record of scope that outlives the conversation:

./mxcli brain plan -p <AppName>.mpr        # what is outstanding, counted from the model
./mxcli brain capture "<new requirement>" --slice <slice> -a @Mod.Thing -p <AppName>.mpr

Requirements arrive mid-build — the user says "and it should also…". Capture that when it is said, not later. Do not tick anything off: brain plan derives what is built from the model, so finishing the work is what moves the number.

In a solution, run one loop per app from its own folder, with the second app on the alternate ports, and start the producer first so the consumer's external entities resolve:

(cd backend  && ./mxcli run --local -p Backend.mpr --watch)
(cd frontend && ./mxcli run --local -p Frontend.mpr --watch \
                  --app-port 8180 --admin-port 8190 --serve-port 6643)

See run-local for the warm loop, --watch, --ensure-db, and the screenshot flags.