Build with the Eventmodelers BuildKit
Some teams already build their projects with the Eventmodelers BuildKit: a set of agent loops, prompts and skills that turn the slices of an event model into code on a stack such as Node.js, Axon or OpenCQRS. The Eventmodelers builder lets Studio hand such a project its slices. Studio keeps the board, the build loop and the statuses; the kit does the building, with its own agent, prompts and stack templates, and Studio’s builder protocol carries the work.
This page covers everything from installing the kit to following a build.
How it fits
Section titled “How it fits”Studio ─ build order ─► cratis build run ─► eventmodelers-builder.mjs ─► .slices/…/slice.json ─► the kit's agent loopStudio ◄─ outcome ───── cratis build run ◄─ eventmodelers-builder.mjs ◄─ slice status: Done ◄───── the kit's agent- The Cratis CLI connects to Studio, claims a slice and writes the build order.
- The Eventmodelers builder, a small generator the CLI runs with
--exec, turns the order’s slices into the slice files the kit looks for: oneslice.jsonfor each slice, under.slices/<feature>/<slice>/, with the statusPlanned, the slice type, the specifications and the order’s Screenplay model beside it. - It starts the kit’s own agent loop in local mode, with no board attached, and watches the slice files.
- The kit’s agent builds the slice on the project’s stack and sets the slice’s status as it goes.
- When every slice is
Done(orReview, orWaitingfor the kit’s user interface step), the builder reports built. A slice the kit sets toBlockedis reported blocked, with its reason. A kit that stops, or runs out of time, is reported failed. - The CLI verifies, commits on the branch Studio names, pushes and reports, exactly as for any builder.
Nothing of the kit is copied into Studio or the builder: it runs from the project. The adapter keeps .slices/ and .build-kit/ out of Git by listing them in the repository’s local exclude file, so the commit holds only the code the kit wrote.
Before you start
Section titled “Before you start”- The Cratis CLI, connected to Studio and approved:
cratis build connect --studio --organization <name>. See Connect a builder and approve it. - Node.js 20 or later.
- A Git repository for the application, clean, with credentials that can push to it.
- The Eventmodelers BuildKit installed in it for the stack you want:
npx @eventmodelers/cli initThe kit’s own documentation describes the stacks, the project it scaffolds and the agents it can drive. Its README is the reference for init, and for the .build-kit folder. Check the kit’s licence before you use it; it is not Cratis software.
Run it
Section titled “Run it”The adapter is a single script with no dependencies, packaged in the builder image at /opt/eventmodelers/eventmodelers-builder.mjs. To run it outside the image, copy the script and its slices.mjs from the image. Then, in the project:
export EVENTMODELERS_AGENT_COMMAND="codex exec --json --full-auto"cratis build run --exec "node /opt/eventmodelers/eventmodelers-builder.mjs" --verify "npm test"--verify runs after the kit is done, so a slice is only reported built when your own tests pass.
Choose the agent
Section titled “Choose the agent”The kit drives a coding agent for each slice. Choose it with the variable the builder reads:
| Variable | Meaning |
|---|---|
EVENTMODELERS_AGENT_COMMAND |
The agent command the kit runs with each prompt: codex exec --json --full-auto, opencode run --standalone --auto --format json or gemini --yolo --output-format stream-json -p. The kit appends the prompt. With it set, the builder runs the kit’s ralph-exec.js |
EVENTMODELERS_RUNNER |
The kit entry point to run, inside .build-kit. Defaults to ralph-exec.js when an agent command is set, and ralph-claude.js otherwise, which drives Claude Code |
EVENTMODELERS_KIT_DIR |
Where the kit is installed. Defaults to .build-kit in the project |
EVENTMODELERS_TIMEOUT_MINUTES |
How long the kit may take for one order. Defaults to 30 |
Agents run with their own permission model. The kit decides what an agent may do inside the project, so review the kit’s agent settings before you run it unattended.
Model calls through Studio
Section titled “Model calls through Studio”The kit’s agents normally sign in to their own provider. Run the builder with --ai studio and they call Studio’s AI gateway instead, on the organization’s providers, with usage counted in Studio:
export EVENTMODELERS_AGENT_COMMAND="codex exec --json --full-auto"cratis build run --exec "node /opt/eventmodelers/eventmodelers-builder.mjs" --ai studioThe CLI starts a bridge on the machine’s loopback address and puts OPENAI_BASE_URL, OPENAI_API_KEY, ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY in the environment of everything it runs. The adapter passes its environment to the kit and the kit to its agent, so any agent that reads those variables, Codex, OpenCode, Claude Code and others, is routed to Studio without a change to the kit. The bridge only answers while a slice is being built, under that slice’s lease. See The AI gateway.
An agent that does not read those variables, or a kit that sets its own provider, keeps using its own. Check the usage in Studio after a first run: calls that went through the gateway are counted there.
In Docker
Section titled “In Docker”cratis build run --exec "node /opt/eventmodelers/eventmodelers-builder.mjs" --docker --image cratis/studio-eventmodelers-builderThe image is the Cratis builder image with Node.js and the adapter at /opt/eventmodelers. The project, with its installed kit, is mounted at /workspace. Pass the agent’s sign-in variables, or use --ai studio so none is needed. The image is built from the Cratis Grip repository, versioned with it and published to Docker Hub with every Grip release. Name it without a tag and the CLI uses its newest version, tells you when a newer one is out, and cratis update pulls it.
Follow a build
Section titled “Follow a build”On the slice in Studio you see the same things as for any builder: In progress while the kit works, then Built with the commit and branch, Blocked with the kit’s reason, or Failed. The CLI’s log shows the kit’s own output.
What the adapter maps
Section titled “What the adapter maps”| Studio | Eventmodelers |
|---|---|
Slice type stateChange, stateView, automation, translation |
STATE_CHANGE, STATE_VIEW, AUTOMATION, TRANSLATION |
| The feature of the order | The context folder under .slices and current_context.json |
| The slice’s specifications | specifications on the slice, by id and name |
| Slice status | Planned at the start. Done, Review and Waiting finish it, Blocked blocks it |
The adapter writes the slice descriptor and the Screenplay model. It does not draw the elements of an Eventmodelers board (commands, events and read models) from Screenplay: a kit that needs them reads the Screenplay model, which is the source of truth in Studio.
Troubleshooting
Section titled “Troubleshooting”| You see | Cause and remedy |
|---|---|
The Eventmodelers BuildKit is not installed in the project |
.build-kit/<runner> is missing. Run npx @eventmodelers/cli init, or set EVENTMODELERS_KIT_DIR or EVENTMODELERS_RUNNER |
did not finish within … minutes |
The kit did not settle every slice. Raise EVENTMODELERS_TIMEOUT_MINUTES, or look at the kit’s output |
stopped with exit code … before finishing |
The kit’s loop ended. Read its output in the log, usually a missing agent command or sign-in |
blocked on a slice |
The kit could not build it and said why. Answer in Studio and mark the slice ready again |
No usage in Studio with --ai studio |
The agent ignores the base URL variables. Give it the provider through its own configuration, or choose an agent that reads them |