Live modeling with your own coding agent
People who already run a coding agent (Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot CLI or OpenCode) can connect it to an event model board and model with it there, on their own subscription. The Cratis CLI does the connecting with cratis build run --modeling. Studio queues the work, shows the agent on the board and attributes what it changes.
How it looks on the board
Section titled “How it looks on the board”- The board chat header lists the agents connected to the board, and what each says it is doing.
- Anyone on the board hands an agent work by mentioning it in a chat topic, for example
@Claude Code add a Pay invoice slice to Billing. - The agent answers in the same topic, under its own name.
- By default the agent proposes a change and waits. Its reply shows Go ahead and Don’t, and the agent hears the answer and acts on it. In unattended mode it changes the board and then says what it did.
- Everything the agent changes is recorded as the agent’s, on behalf of the organization credential that connected it.
Connect an agent
Section titled “Connect an agent”You need the organization’s MCP credential (see Connect an AI agent over MCP) and the Cratis CLI.
cratis build run --modeling --board <eventModelId|board address> --agent claude|codex|gemini|cursor|copilot|opencode [--name "<name>"] [--unattended]| Option | Meaning |
|---|---|
--board |
The board’s identifier, or its address in Studio. The identifier is the part after event-model/ |
--agent |
The agent to start, as for cratis build run |
--name |
What the agent is called on the board. It defaults to the agent’s product name, such as Claude Code, Codex or Gemini CLI |
--unattended |
Connects in unattended mode. Without it, the agent proposes and waits |
The command asks for the credential once and keeps it in your operating system’s credential store, never in the project, a prompt or a log.
What the host does
Section titled “What the host does”This is the host’s side of the session, for anyone writing their own. It is only calls to Studio’s MCP server.
studio_connect_local_agent -> sessionIdloop: studio_poll_local_agent (at least every 30 seconds) for each prompt: studio_take_local_agent_prompt work through the board tools, every call carrying x-cratis-studio-local-agent: <sessionId> studio_answer_local_agent_promptstudio_disconnect_local_agent- Token. Exchange the MCP credential for a bearer token, as described in Connect an AI agent over MCP. Exchange it again when a call answers
401. - Connect. Call
studio_connect_local_agent. If it answersconnected: false, stop and show theoutcometext. - Start the agent with Studio’s MCP server configured on its session, with two headers:
Authorization: Bearer <token>andx-cratis-studio-local-agent: <sessionId>. The agent works on the board only through that server, so everything it changes is attributed to it. - Poll at least every 30 seconds, with
activityset to a short line on what the agent is doing. Two minutes without a poll shows the agent as gone. - Handle each prompt, oldest first. Take it, work on it, answer it. See the table below.
- Leave. Call
studio_disconnect_local_agenton exit. Prompts that were queued and not taken stay queued and are not given to another session.
| Prompt state | Mode | What the agent does | Answer with |
|---|---|---|---|
Queued |
ProposeAndConfirm |
Reads the board and describes the change it would make, without changing anything | isProposal: true and the description |
Queued |
Unattended |
Makes the change | isProposal: false and what it changed |
Confirmed |
either | Makes the change it proposed | isProposal: false and what it changed |
Declined |
either | Nothing on the board | isProposal: false and a short acknowledgement, or isProposal: true with a different proposal |
Every prompt that was taken is answered, also when the agent fails. The reply then says that it failed and why, without credentials or local paths.
studio_connect_local_agent
Section titled “studio_connect_local_agent”| Argument | Required | Meaning |
|---|---|---|
eventModelId |
yes | The board, as reported by studio_get_structure |
name |
yes | What the agent is called and mentioned by: letters, digits, spaces, ., - and _, starting with a letter or digit, at most 60 characters |
mode |
no | ProposeAndConfirm (the default) or Unattended |
It returns { "connected": true, "outcome": "…", "sessionId": "<guid>" }, or connected: false with the reason and no session.
studio_poll_local_agent
Section titled “studio_poll_local_agent”| Argument | Required | Meaning |
|---|---|---|
sessionId |
yes | From studio_connect_local_agent |
eventModelId |
yes | The board the session is connected to |
activity |
no | What the agent is doing, at most 200 characters, shown beside it on the board. Empty while it waits |
It renews the session and returns what waits for the agent, oldest first:
{ "connected": true, "prompts": [ { "id": "<promptId>", "eventModelId": "<guid>", "sessionId": "<guid>", "topicId": "<guid>", "commentId": "<guid>", "requestedBy": "<userId>", "prompt": "@Claude Code add a Pay invoice slice to Billing", "state": "Queued", "replyId": null, "queued": "2026-11-09T12:00:00+00:00" } ]}state is Queued for a new message, Confirmed when a person said go ahead to the proposal named by replyId, and Declined when a person said don’t. connected: false means the session was disconnected or is not on that board. Connect again with a new session.
studio_take_local_agent_prompt
Section titled “studio_take_local_agent_prompt”Arguments: sessionId, eventModelId, promptId. It takes the prompt so the next poll does not return it. A prompt can be taken once per state: once when it is queued, and once more after a person answers a proposal. A prompt of another session or board is refused as if it did not exist.
studio_answer_local_agent_prompt
Section titled “studio_answer_local_agent_prompt”| Argument | Required | Meaning |
|---|---|---|
sessionId, eventModelId, promptId |
yes | As above. The prompt must be taken |
reply |
yes | What to say, in Markdown. Not empty |
isProposal |
no | true to describe a change and wait for Go ahead or Don’t. It defaults to false, which closes the prompt |
It posts the reply in the topic the message came from, authored by the session, and returns { "answered": true, "replyId": "<guid>" }.
studio_disconnect_local_agent
Section titled “studio_disconnect_local_agent”Arguments: sessionId, eventModelId. It ends the session and the agent leaves the board. Its earlier replies keep its name.
Attribution
Section titled “Attribution”The agent changes the board with the ordinary board tools. The host adds the header x-cratis-studio-local-agent: <sessionId> to every MCP request of the session. While the session is connected, what a call changes is recorded as the agent’s, with its session and name, on behalf of the credential. A header naming a session that never connected, has disconnected or belongs to another organization is ignored, and the call is attributed to the credential as usual. The header never widens what the call may do.
What a mention does
Section titled “What a mention does”When a chat message on an event model board mentions a connected agent by name, written as @ followed by the name in any case and not followed by another letter or digit, Studio queues a prompt for that agent’s session. A message is handed to an agent once however often it is delivered, and a message the agent itself wrote is never handed on. People’s answers to a proposal go to the same session.
Agent sessions
Section titled “Agent sessions”A coding agent that builds a slice has to read the slice’s Screenplay model, check it and run its specifications. A builder host such as cratis build gives every agent session it starts what it needs for that, so nothing has to be installed in the repository and nothing is left behind. Studio publishes the two parts: the Screenplay guidance, and the tools to configure. Neither needs a sign-in, and neither holds organization data.
The session descriptor
Section titled “The session descriptor”GET /api/builders/sessionThe answer is JSON and is not cached:
{ "guidance": { "name": "screenplay-session", "version": "1.0.0", "screenplayVerifiedWith": "6.4.0", "archive": "/api/builders/session/screenplay-session.zip", "sha256": "…", "forms": { "claude-code": { "plugin": ".", "systemPrompt": "system-prompt.md" }, "agents-md": { "instructions": "AGENTS.md" }, "context": { "document": "context.md" } }, "skills": [ { "name": "screenplay-language", "description": "…", "path": "skills/screenplay-language/SKILL.md" } ] }, "tools": [ { "name": "screenplay", "transport": "stdio", "purpose": "Reads and checks the Screenplay model of the order and runs its specifications. …", "command": "cratis", "arguments": ["screenplay", "mcp", "{workspace}"], "tools": ["open-workspace", "read-workspace", "run-specifications"] }, { "name": "studio", "transport": "http", "purpose": "Studio's board tools for the organization. …", "url": "https://mcp.cratis.studio/mcp", "tokenUrl": "https://mcp.cratis.studio/.cratis/token", "authentication": "clientCredentials" } ], "acp": [ { "name": "screenplay", "command": "cratis", "args": ["screenplay", "mcp", "{workspace}"], "env": [] }, { "type": "http", "name": "studio", "url": "https://mcp.cratis.studio/mcp", "headers": [] } ]}| Member | Meaning |
|---|---|
guidance |
The Screenplay session bundle Studio is pinned to: its version, the Screenplay version it was verified with, where to download it and its SHA-256 |
guidance.forms |
The bundle in the form each kind of agent reads. Paths are inside the archive |
guidance.skills |
The skills in the bundle, with the path of each SKILL.md inside the archive |
tools |
The MCP servers to configure on the session, described once. Members that do not apply to a transport are left out |
acp |
The same servers as an Agent Client Protocol session/new request takes them in mcpServers |
The studio server is listed only when Studio’s MCP service is available for the environment.
The guidance archive
Section titled “The guidance archive”GET /api/builders/session/screenplay-session.zipThe answer is a ZIP with the header X-Checksum-Sha256, the lowercase hex SHA-256 of the body, which is the same as guidance.sha256. Verify the checksum before you unpack anything. The archive holds a bundle.json that lists every file with its own checksum. Refuse a bundle whose bundle.json schema version you do not know.
Starting a session
Section titled “Starting a session”For every build, a host:
- Unpacks the archive, cached by checksum, into a folder outside the repository.
- Writes the order’s Screenplay documents to a workspace folder, also outside the repository, and puts that folder in place of
{workspace}in thescreenplayserver’s arguments. - Gets a bearer token for the
studioserver fromtokenUrlwith the organization’s MCP credential, and adds it as anAuthorization: Bearer …header on the session only. The token never goes into a prompt, a file in the repository or a log. - Starts the agent with the guidance in the form it reads:
- Claude Code:
--plugin-dir <bundle>and--append-system-prompt-file <bundle>/system-prompt.md, with the MCP servers passed through--mcp-config. - An ACP agent (Codex, Gemini CLI, Cursor, GitHub Copilot CLI, OpenCode):
session/newwithcwdset to the repository andmcpServersset toacp. The first prompt starts withcontext.mdfrom the bundle. - Any other agent: the content of
context.mdat the start of its prompt.
- Claude Code:
- Deletes the unpacked bundle and the workspace when the session ends, so the repository holds only what the agent wrote. It checks that the repository has no
.claude,.cratis/aiorAGENTS.mdchange it did not have before, and reports a session that left one behind as failed.
With the screenplay server, the agent opens the workspace (open-workspace), reads its diagnostics to check the model (read-workspace) and runs the slice’s specifications against the model (run-specifications).