> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baimoqilin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Technical details

> Architecture, storage, limits, and runtime internals for MineClawd.

## 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

```text theme={null}
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 type          | Byte | Payload                                  |
| ------------------- | ---- | ---------------------------------------- |
| `START`             | `0`  | JSON with `sessionId` and `request` text |
| `DELTA`             | `1`  | Text fragment from the LLM               |
| `DONE`              | `2`  | Empty                                    |
| `ERROR`             | `3`  | Error message string                     |
| `TOOL_STATUS`       | `4`  | Name of the tool currently being called  |
| `TOOL_STATUS_CLEAR` | `5`  | Empty (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 behavior                | Value                  |
| ---------------------------------- | ---------------------- |
| Tool call limit range              | `1` to `20`            |
| Default tool call limit value      | `16`                   |
| Tool call limit default state      | disabled               |
| Ask-user max options               | `5`                    |
| Ask-user timeout                   | `60` seconds           |
| Failed-request retry token TTL     | `30` minutes           |
| Rate-limit retry count             | `2` retries            |
| Rate-limit retry backoff           | `1500ms * retry_index` |
| History max entries for book build | `300`                  |
| Overlay input bar max length       | `600` characters       |
| Asset categories                   | `5`                    |

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