Skip to content

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.

Studio ─ build order ─► cratis build run ─► eventmodelers-builder.mjs ─► .slices/…/slice.json ─► the kit's agent loop
Studio ◄─ outcome ───── cratis build run ◄─ eventmodelers-builder.mjs ◄─ slice status: Done ◄───── the kit's agent
  1. The Cratis CLI connects to Studio, claims a slice and writes the build order.
  2. The Eventmodelers builder, a small generator the CLI runs with --exec, turns the order’s slices into the slice files the kit looks for: one slice.json for each slice, under .slices/<feature>/<slice>/, with the status Planned, the slice type, the specifications and the order’s Screenplay model beside it.
  3. It starts the kit’s own agent loop in local mode, with no board attached, and watches the slice files.
  4. The kit’s agent builds the slice on the project’s stack and sets the slice’s status as it goes.
  5. When every slice is Done (or Review, or Waiting for the kit’s user interface step), the builder reports built. A slice the kit sets to Blocked is reported blocked, with its reason. A kit that stops, or runs out of time, is reported failed.
  6. 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.

  • 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:
Terminal window
npx @eventmodelers/cli init

The 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.

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:

Terminal window
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.

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.

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:

Terminal window
export EVENTMODELERS_AGENT_COMMAND="codex exec --json --full-auto"
cratis build run --exec "node /opt/eventmodelers/eventmodelers-builder.mjs" --ai studio

The 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.

Terminal window
cratis build run --exec "node /opt/eventmodelers/eventmodelers-builder.mjs" --docker --image cratis/studio-eventmodelers-builder

The 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.

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.

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.

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