Plugin Bootstrap Watcher

Name: Plugin Bootstrap Watcher
Rating: 3.5 (1 reviews)
Author: hchen13

By hchen13 👁 8 views ▲ 0 votes

OpenClaw plugin: hot-reload bootstrap files (AGENTS.md, SOUL.md, etc.) on change without gateway restart

GitHub

Install

npm install
```

Configuration Example

{
  "plugins": [
    {
      "path": "/path/to/plugin",
      "config": {}
    }
  ]
}

README

# openclaw-plugin-bootstrap-watcher

> Hot-reload agent bootstrap files (AGENTS.md, SOUL.md, etc.) on change — no gateway restart required.

[中文文档](./README.zh.md)

---

## Why

OpenClaw loads and caches agent bootstrap files (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, etc.) **once at gateway startup**. Editing these files while the gateway is running has no effect — the agent keeps using the stale cached content until you run `/reset` or restart the gateway entirely.

This plugin solves the problem by watching those files with [chokidar](https://github.com/paulmillr/chokidar) and automatically injecting fresh content into the next session bootstrap, with zero downtime.

---

## How It Works

```
File change on disk
       │
       ▼
  chokidar watcher detects change
       │
       ▼
  workspace marked "dirty" in memory
       │
       ▼
  Next agent session starts  →  agent:bootstrap hook fires
       │
       ▼
  Plugin checks dirty flag  →  reloads files from disk
       │
       ▼
  event.context.bootstrapFiles replaced with fresh content
       │
       ▼
  Agent receives up-to-date bootstrap context ✓
```

**Lifecycle:**

1. **`gateway_start`** — The plugin enumerates all agent workspace directories from `openclaw.json`, then starts a chokidar watcher on the known bootstrap filenames in each directory.
2. **File change** — When any watched file is created, modified, or deleted, the corresponding workspace is added to a `dirtyWorkspaces` set.
3. **`agent:bootstrap` hook** — Before each agent session starts, the plugin checks whether that agent's workspace is dirty. If yes, it reads all bootstrap files from disk, replaces `event.context.bootstrapFiles` in-place, and clears the dirty flag.

**Watched filenames** (in each agent workspace directory):

- `AGENTS.md`
- `SOUL.md`
- `TOOLS.md`
- `IDENTITY.md`
- `USER.md`
- `MEMORY.md`
- `memory.md`
- `HEARTBEAT.md`
- `BOOTSTRAP.md`

---

## ⚠️ Important Caveat

This plugin hooks into OpenClaw's internal event system via:

```
globalThis.__openclaw_internal_hook_handlers__
```

This is an **undocumented private interface**. It is not part of the public Plugin SDK and **may break with any OpenClaw version upgrade**. Use at your own risk.

If a future version of OpenClaw exposes an official `agent:bootstrap` hook in its public SDK, this plugin should be updated to use that instead.

---

## Installation

### 1. Clone or copy this plugin

```bash
git clone https://github.com/hinton-g/openclaw-plugin-bootstrap-watcher.git /path/to/plugin
cd /path/to/plugin
npm install
```

### 2. Register the plugin in `openclaw.json`

Add the plugin entry to your `openclaw.json`:

```json
{
  "plugins": [
    {
      "path": "/path/to/plugin",
      "config": {}
    }
  ]
}
```

> **Note:** Replace `/path/to/plugin` with the absolute path where you cloned/copied the plugin directory.

### 3. Restart the gateway

```bash
openclaw gateway restart
```

After restart, the watcher is active. Any edits to bootstrap files in your agent workspace directories will be picked up automatically on the next session start — no further restarts needed.

---

## For AI Agents

**Plugin ID:** `bootstrap-watcher`

**What it does:** Intercepts `agent:bootstrap` events and replaces stale cached bootstrap file content with freshly-read disk content when a workspace has been modified since the gateway started.

**Inputs consumed:**
- `event.context.workspaceDir` (string) — path to the agent's workspace
- `event.context.bootstrapFiles` (array) — mutated in-place with fresh content

**Side effects:**
- Registers a chokidar file watcher on `gateway_start`
- Maintains a `dirtyWorkspaces: Set<string>` singleton in plugin module scope
- Clears the dirty flag for a workspace after successful reload

**No plugin-level config required** — the plugin has no custom options; `config: {}` is sufficient in `openclaw.json`. However, you still need to register the plugin in `openclaw.json` (see [Installation](#installation) above).

**Hook mechanism:** Uses `globalThis.__openclaw_internal_hook_handlers__` (private, undocumented) to register the `agent:bootstrap` handler, since the public Plugin SDK does not expose this event.

---

## Compatibility

| Requirement | Version |
|-------------|---------|
| OpenClaw    | `>= 2026.2.0` |
| Node.js     | `>= 18` |

---

## License

MIT

tools