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

gameDir/
  config/
    mineclawd.json5
  mineclawd/
    player-settings.json
    sessions/
      <owner>/
        active.json
        <id>.json
    assets/
      <owner>.json
    souls/
      default.md
      yuki.md
      <custom>.md
      .active/
        <owner>.txt
  kubejs/
    server_scripts/
      mineclawd/
        ...

​
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.
Event typeBytePayload
START0JSON with sessionId and request text
DELTA1Text fragment from the LLM
DONE2Empty
ERROR3Error message string
TOOL_STATUS4Name of the tool currently being called
TOOL_STATUS_CLEAR5Empty (clears the tool status indicator)
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

Setting or behaviorValue
Tool call limit range1 to 20
Default tool call limit value16
Tool call limit default statedisabled
Ask-user max options5
Ask-user timeout60 seconds
Failed-request retry token TTL30 minutes
Rate-limit retry count2 retries
Rate-limit retry backoff1500ms * retry_index
History max entries for book build300
Overlay input bar max length600 characters
Asset categories5

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