Skip to main content

​
Request lifecycle

  1. You run /mclawd ..., /mineclawd prompt ..., or type a request in the overlay input bar.
  2. MineClawd validates provider config and OP access.
  3. MineClawd loads or creates active session state.
  4. MineClawd sends a streaming request to the OpenAI-compatible or Vertex endpoint.
  5. Stream deltas are sent to the client in real time via the AGENT_STREAM_EVENT channel. The overlay renders each delta with a blinking cursor.
  6. Model responses can trigger tool calls. Tool results are fed back into the model loop.
  7. Final assistant output is rendered to chat (and the overlay) and session history is saved.

​
Runtime tool families

  • Command and script execution:
    • execute-command
    • apply-instant-server-script
  • Persistent script files:
    • list-server-scripts
    • read-server-script
    • write-server-script
    • delete-server-script
    • reload-game
    • sync-command-tree
  • Clarification:
    • ask-user-question
  • Asset tracking:
    • list-assets
    • upsert-asset-record
    • remove-asset-record
  • Web search (requires Tavily API key):
    • search
  • Mod information:
    • list_mods
    • list_commands
    • fetch_modrinth
    • fetch_url
  • Dynamic placeholders (only when enabled):
    • list-dynamic-content
    • register-dynamic-item
    • register-dynamic-block
    • register-dynamic-fluid
    • update-dynamic-item
    • update-dynamic-block
    • update-dynamic-fluid
    • unregister-dynamic-content

​
Storage layout

​
Session internals

  • Session id is a 4-character lowercase token.
  • Command token format is <id>-<title-slug>.
  • Session file stores OpenAI and Vertex histories separately.
  • Active session pointer is stored in active.json per owner.
  • Session title is generated after first successful round using summarize model.

​
LLM transport details

  • OpenAI-compatible request path: <endpoint>/chat/completions
  • Vertex request path: <endpoint>/<model>:generateContent?key=<api_key>
  • Both paths use 60-second request timeout.
  • Both paths support function-style tool calling.
  • Both paths support streaming. Stream deltas are forwarded to the client via the AGENT_STREAM_EVENT network channel.

​
Streaming architecture

Stream events use the AGENT_STREAM_EVENT channel with a request ID, event type byte, and payload string. The overlay receives these events and renders deltas incrementally. A blinking cursor follows the latest text until DONE or ERROR arrives. During generation, TOOL_STATUS events display an animated indicator showing which tool MineClawd is calling in real time. The indicator clears when TOOL_STATUS_CLEAR arrives. Active requests are tracked server-side in ACTIVE_REQUESTS and ACTIVE_NETWORK_REQUESTS maps. The /mineclawd stop command marks the request ID in CANCELLED_REQUEST_IDS and cancels in-flight HTTP connections.

​
Dynamic placeholder internals

  • Capacity: 30 item slots, 30 block slots, 30 fluid slots.
  • Fixed ids include:
    • mineclawd:dynamic_item_001
    • mineclawd:dynamic_block_001
    • mineclawd:dynamic_fluid_001
  • State sync uses sync_dynamic_content network payload.
  • State persistence uses world PersistentState id mineclawd_dynamic_content.
  • AUTO mode enables runtime placeholders in client runtime and disables them on dedicated servers.

​
Networking channels

MineClawd defines these packet identifiers:
  • mineclawd:client_ready
  • mineclawd:client_gui_pref
  • mineclawd:open_config
  • mineclawd:sync_broadcast_target
  • mineclawd:sync_assistive_touch
  • mineclawd:sync_dynamic_content
  • mineclawd:open_question
  • mineclawd:question_response
  • mineclawd:open_sessions
  • mineclawd:open_assets
  • mineclawd:open_history_book
  • mineclawd:agent_stream_event

​
Asset tracking internals

Asset records are stored per owner in mineclawd/assets/<owner>.json. Each record contains:
  • id — unique identifier
  • category — one of ENTITIES, ITEMS_BLOCKS_FLUIDS, SPECIAL_ITEMS, COMMANDS, GAME_MECHANICS
  • name, summary, scriptPath, details
  • Category-specific fields: contentId, specialItemId, specialItemNbt, command, entityUuid, entityDimension, entityX, entityY, entityZ
  • sessionId — the session that created the asset
  • createdAt, updatedAt — timestamps
The system prompt includes an asset tracking appendix so the LLM automatically catalogs creations through upsert-asset-record tool calls.

​
Limits and timers

​
Security model

  • Every command path is OP-gated.
  • KubeJS execution is real server execution, not simulation.
  • API keys must be treated as secrets.
  • Use trusted environments only.