Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript

feat: add OpenClaw native plugin compatibility (v0.5.0)

Sol Aitken553a7e5c918b
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 2e46e333..bcf07c89 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.4.2",
+ "version": "0.5.0",
"description": "Plugin-first second brain package for AI agents and humans.",
"author": "Open Second Brain contributors",
"license": "MIT",
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 430fafe8..44ec7db8 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "open-second-brain",
- "version": "0.4.2",
- "description": "Plugin-first second brain package for Codex, Hermes, Claude Code, and other agent runtimes.",
+ "version": "0.5.0",
+ "description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"skills": "./skills",
"keywords": ["second-brain", "obsidian", "agents", "skills", "event-log", "mcp"]
}
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index c752256b..b9ba6d81 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -76,6 +76,7 @@ jobs:
set -euo pipefail
python -m json.tool .claude-plugin/plugin.json >/dev/null
python -m json.tool .codex-plugin/plugin.json >/dev/null
+ python -m json.tool openclaw.plugin.json >/dev/null
python -m py_compile plugins/hermes/__init__.py
bash -n scripts/o2b
bash -n scripts/vault-log
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5c05ba1c..4389e50a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+## [0.5.0] - 2026-05-07
+
+### Added
+
+- OpenClaw native plugin compatibility through `openclaw.plugin.json` manifest at
+ the project root. OpenClaw discovers the plugin via the Bundle format
+ (auto-detecting `.claude-plugin/` and `.codex-plugin/`) combined with the
+ static manifest for cold discovery. The MCP server serves as the runtime tool
+ bridge. See `docs/architecture.md` for the adapter layout.
+- `check_openclaw_manifest` health check in `doctor.py` that validates
+ `openclaw.plugin.json` has required fields (`id`, `configSchema`) and that the
+ declared tool names match the MCP tool table.
+- `openclaw_manifest` check in the Hermes adapter health report
+ (`plugins/hermes/__init__.py`).
+- OpenClaw installation and configuration section in `README.md`.
+- OpenClaw post-install steps in `after-install.md`.
+- OpenClaw adapter section in `docs/architecture.md`.
+- Validation of `openclaw.plugin.json` in the CI release workflow
+ (`.github/workflows/release.yml`).
+- `tests/test_openclaw_plugin.py` covering manifest validity, required fields,
+ tool name consistency with the MCP server, and installability invariants.
+
+### Changed
+
+- Bumped package, plugin, MCP server, and Claude/Codex manifest versions to 0.5.0.
+- Updated `pyproject.toml` description to mention OpenClaw alongside Hermes,
+ Claude Code, and Codex.
+- Updated `.codex-plugin/plugin.json` description to mention OpenClaw.
+
## [0.4.2] - 2026-05-06
### Changed
@@ -105,7 +134,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Sandbox vault and plugin manifest fixtures for tests.
- GitHub release workflow for tag-based and manually dispatched releases.
-[unreleased]: https://github.com/itechmeat/open-second-brain/compare/v0.4.2...HEAD
+[unreleased]: https://github.com/itechmeat/open-second-brain/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/itechmeat/open-second-brain/compare/v0.4.2...v0.5.0
[0.4.2]: https://github.com/itechmeat/open-second-brain/compare/v0.4.1...v0.4.2
[0.4.1]: https://github.com/itechmeat/open-second-brain/compare/v0.4.0...v0.4.1
[0.4.0]: https://github.com/itechmeat/open-second-brain/compare/v0.3.1...v0.4.0
diff --git a/README.md b/README.md
index faa4b250..0a545580 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@ OpenSecondBrain gives Hermes Agent a small, filesystem-first second brain for Ob
It is built for Hermes first: install it as a Hermes plugin, point it at a vault, and let Hermes use deterministic commands for the parts that should not depend on model reasoning β€” setup checks, vault bootstrap, daily event logging, safe config export, and wiki indexing.
-Claude Code and OpenAI Codex are supported through lightweight adapter manifests, but Hermes is the primary runtime.
+Claude Code, OpenAI Codex, and OpenClaw are supported through lightweight adapter manifests and the MCP tool server. Hermes is the primary runtime.
## What it does today
@@ -17,7 +17,17 @@ Claude Code and OpenAI Codex are supported through lightweight adapter manifests
OpenSecondBrain does not run a daemon, replace your vault, or write hidden background state outside the configured vault/config paths.
-## Install in Hermes
+## Installation
+
+> **Agent-assisted install (recommended):** The easiest way to install this plugin is to send your agent the following prompt with a link to the installation guide:
+>
+> ```
+> Install the open-second-brain plugin following the instructions at https://raw.githubusercontent.com/itechmeat/open-second-brain/main/install.md
+> ```
+>
+> The guide at `install.md` contains exact commands for both Hermes and OpenClaw runtimes. Below are the same instructions for manual installation.
+
+### Install in Hermes
In the Hermes Dashboard:
@@ -36,9 +46,41 @@ Hermes also supports the same flow from the CLI:
```bash
hermes plugins install itechmeat/open-second-brain --enable
+hermes gateway restart
+```
+
+Then initialize the vault, register the MCP server, and verify:
+
+```bash
+o2b init --vault /path/to/vault --name "My Second Brain"
+hermes mcp add open-second-brain --command o2b --args mcp --vault /path/to/vault
+hermes gateway restart
+o2b doctor --vault /path/to/vault --repo .
+```
+
+### Install in OpenClaw
+
+OpenClaw supports this project through the **Bundle format**: OpenClaw auto-detects the `.claude-plugin/` and `.codex-plugin/` adapter directories and maps them to OpenClaw features. The `openclaw.plugin.json` manifest at the project root provides static discovery metadata.
+
+Install from Git:
+
+```bash
+openclaw plugins install git:github.com/itechmeat/[email protected]
+```
+
+Or from a local checkout:
+
+```bash
+openclaw plugins install ./open-second-brain
+```
+
+After installing, register the MCP tool server so OpenClaw can route tool calls:
+
+```bash
+o2b mcp --vault /path/to/vault
```
-Hermes documentation describes plugin install identifiers as a Git URL or `owner/repo` shorthand; the dashboard field accepts the same formats.
+The MCP server exposes five tools: `second_brain_status`, `second_brain_query`, `second_brain_capture`, `event_log_append`, `vault_health`. OpenClaw discovers these through the MCP protocol at runtime. The `openclaw.plugin.json` `contracts.tools` field declares them for cold discovery when the MCP server is not yet running.
## First run
diff --git a/after-install.md b/after-install.md
index 22ba9842..c48277f3 100644
--- a/after-install.md
+++ b/after-install.md
@@ -78,3 +78,27 @@ yourself with normal filesystem tools if that is what you want.
- `README.md` β€” full feature description and CLI reference.
- `docs/mcp.md` β€” MCP tool server, registration, update/remove flows.
- `docs/architecture.md` β€” config model, vault layout, security rules.
+
+## OpenClaw
+
+If you are using OpenClaw instead of (or in addition to) Hermes, the plugin
+is already discoverable through the Bundle format. OpenClaw auto-detects the
+`.claude-plugin/` and `.codex-plugin/` directories.
+
+The `openclaw.plugin.json` manifest at the project root declares the plugin ID
+(`open-second-brain`), a configuration schema, and the five tool names the MCP
+server exposes. To register the MCP server with OpenClaw, follow the same
+pattern as Hermes β€” point OpenClaw's MCP configuration at the `o2b mcp`
+command:
+
+```bash
+o2b mcp --vault /path/to/vault
+```
+
+Run the doctor to verify the OpenClaw manifest is valid:
+
+```bash
+o2b doctor --vault /path/to/vault --repo .
+```
+
+The doctor output should include `[OK] openclaw_manifest`.
diff --git a/docs/architecture.md b/docs/architecture.md
index e18c8781..3bb4e46f 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -25,7 +25,7 @@ The core should eventually provide deterministic operations for:
- running migrations;
- querying known indexes where available.
-The core should not depend on Hermes, Claude Code, Codex, or Obsidian internals.
+The core should not depend on Hermes, Claude Code, Codex, OpenClaw, or Obsidian internals.
## Runtime adapters
@@ -74,6 +74,34 @@ assets/ # later, optional
v0 should keep Codex support simple: plugin manifest plus shared skills and scripts.
+### OpenClaw adapter
+
+OpenClaw recognizes two plugin formats: **Native** (TypeScript/JS runtime module with `openclaw.plugin.json`) and **Bundle** (adapter directories like `.codex-plugin/`, `.claude-plugin/` mapped to OpenClaw features).
+
+Since Open Second Brain is a Python project, it uses the **Bundle format** combined with a static `openclaw.plugin.json` manifest:
+
+```text
+openclaw.plugin.json # static discovery metadata (id, configSchema, contracts.tools)
+.claude-plugin/ # auto-detected by OpenClaw Bundle format
+.codex-plugin/ # auto-detected by OpenClaw Bundle format
+scripts/o2b # CLI entry point
+src/open_second_brain/mcp.py # MCP server (runtime tool bridge)
+```
+
+The OpenClaw integration does **not** add a TypeScript entry point or `package.json`. Instead:
+
+1. **Cold discovery**: `openclaw.plugin.json` declares the plugin ID, version, configuration schema, and the list of tool names the MCP server provides.
+2. **Feature mapping**: OpenClaw auto-detects `.claude-plugin/` and `.codex-plugin/` directories and maps their commands and skills to OpenClaw features.
+3. **Runtime bridge**: The MCP server (`o2b mcp`) serves as the tool runtime. OpenClaw discovers tool schemas and executes tool calls through the MCP protocol (stdio JSON-RPC 2.0).
+
+Installation:
+
+```bash
+openclaw plugins install git:github.com/itechmeat/[email protected]
+```
+
+The OpenClaw adapter must not introduce Node.js/TypeScript dependencies, must not add `package.json`, and must remain compatible with the Hermes, Claude Code, and Codex adapters.
+
## Configuration model
Open Second Brain separates immutable package code from mutable user configuration and data.
diff --git a/install.md b/install.md
new file mode 100644
index 00000000..3eb812c6
--- /dev/null
+++ b/install.md
@@ -0,0 +1,154 @@
+# open-second-brain β€” Agent Installation Guide
+
+> **Version 0.5.0**
+> Repository: https://github.com/itechmeat/open-second-brain
+
+This guide is written for an **AI agent**, not a human. It contains the exact commands and decision logic needed to install and configure the **open-second-brain** plugin autonomously. Follow exactly one of the two branches below based on the target runtime (Hermes or OpenClaw). Complete every step in the chosen branch.
+
+If at any point you are missing information β€” for example, the vault path is unknown, a required tool is not installed, or the runtime version is unclear β€” stop and ask the user for clarification. Offer concrete options where possible (e.g. suggest a default vault path, list supported Python versions, or propose an alternative runtime).
+
+---
+
+## Branch A β€” Hermes
+
+### 1. Install the plugin
+
+```bash
+hermes plugins install itechmeat/open-second-brain --enable
+```
+
+Alternatively, use the Hermes Dashboard: open **Plugins β†’ Install from GitHub URL** and paste:
+
+```
+https://github.com/itechmeat/open-second-brain
+```
+
+After install, restart the gateway:
+
+```bash
+hermes gateway restart
+```
+
+### 2. Initialize the vault
+
+Replace `/path/to/vault` with the actual vault path.
+
+```bash
+o2b init --vault /path/to/vault --name "My Second Brain"
+```
+
+### 3. Register the MCP server
+
+```bash
+hermes mcp add open-second-brain --command o2b --args mcp --vault /path/to/vault
+hermes gateway restart
+```
+
+### 4. Verify the installation
+
+```bash
+o2b doctor --vault /path/to/vault --repo .
+```
+
+All checks must pass. If any check fails, report the failure output to the user before continuing.
+
+### 5. Update
+
+```bash
+hermes plugins update open-second-brain
+hermes gateway restart
+o2b doctor --vault /path/to/vault --repo .
+```
+
+### 6. Uninstall
+
+Run in this order:
+
+```bash
+# Step 1 β€” dry-run review
+o2b uninstall
+
+# Step 2 β€” deregister MCP and remove plugin
+hermes mcp remove open-second-brain
+hermes plugins remove open-second-brain
+hermes gateway restart
+
+# Step 3 β€” optionally remove local config directory
+o2b uninstall --apply-local
+```
+
+The vault and its Markdown files are never deleted by the uninstall process.
+
+---
+
+## Branch B β€” OpenClaw
+
+### 1. Install the plugin
+
+From Git (pin to a version tag):
+
+```bash
+openclaw plugins install git:github.com/itechmeat/[email protected]
+```
+
+Or from a local checkout:
+
+```bash
+openclaw plugins install ./open-second-brain
+```
+
+After install, restart the gateway:
+
+```bash
+openclaw gateway restart
+```
+
+### 2. Initialize the vault
+
+Replace `/path/to/vault` with the actual vault path.
+
+```bash
+o2b init --vault /path/to/vault --name "My Second Brain"
+```
+
+### 3. Register the MCP server
+
+The MCP server is started via:
+
+```bash
+o2b mcp --vault /path/to/vault
+```
+
+Point the OpenClaw MCP configuration at this command. The exact config method depends on the OpenClaw MCP setup in use β€” register `o2b mcp` as an stdio MCP server with the `--vault` argument.
+
+### 4. Verify the installation
+
+```bash
+o2b doctor --vault /path/to/vault --repo .
+openclaw plugins inspect open-second-brain --runtime --json
+```
+
+Both commands must succeed. If any check fails, report the failure output to the user before continuing.
+
+### 5. Update
+
+```bash
+openclaw plugins update open-second-brain
+openclaw gateway restart
+o2b doctor --vault /path/to/vault --repo .
+```
+
+### 6. Uninstall
+
+```bash
+openclaw plugins uninstall open-second-brain
+openclaw gateway restart
+```
+
+Optionally remove the local config directory:
+
+```bash
+o2b uninstall --apply-local
+```
+
+The vault and its Markdown files are never deleted by the uninstall process.
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
new file mode 100644
index 00000000..7cc05df1
--- /dev/null
+++ b/openclaw.plugin.json
@@ -0,0 +1,34 @@
+{
+ "id": "open-second-brain",
+ "name": "Open Second Brain",
+ "description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Provides vault management, event logging, wiki indexing, and an MCP tool server.",
+ "version": "0.5.0",
+ "contracts": {
+ "tools": [
+ "second_brain_status",
+ "second_brain_query",
+ "second_brain_capture",
+ "event_log_append",
+ "vault_health"
+ ]
+ },
+ "configSchema": {
+ "type": "object",
+ "additionalProperties": false,
+ "properties": {
+ "vault": {
+ "type": "string",
+ "description": "Absolute path to the Obsidian-compatible vault directory."
+ },
+ "instanceName": {
+ "type": "string",
+ "description": "Human-readable name for this second brain instance."
+ },
+ "mcpEnabled": {
+ "type": "boolean",
+ "default": true,
+ "description": "Whether to enable the MCP tool server."
+ }
+ }
+ }
+}
diff --git a/plugin.yaml b/plugin.yaml
index d6398c54..251dc937 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.4.2"
+version: "0.5.0"
description: "Hermes plugin entrypoint for OpenSecondBrain vault health checks and the optional MCP tool server."
author: "OpenSecondBrain contributors"
kind: standalone
diff --git a/plugins/hermes/__init__.py b/plugins/hermes/__init__.py
index dead4a38..ca590177 100644
--- a/plugins/hermes/__init__.py
+++ b/plugins/hermes/__init__.py
@@ -72,6 +72,7 @@ def health(repo_root: str | Path | None = None) -> HealthReport:
"hermes_manifest": _check_text_manifest(root / "plugins" / "hermes" / "plugin.yaml"),
"claude_manifest": _check_json(root / ".claude-plugin" / "plugin.json"),
"codex_manifest": _check_json(root / ".codex-plugin" / "plugin.json"),
+ "openclaw_manifest": _check_json(root / "openclaw.plugin.json"),
"o2b_script": _check_file(root / "scripts" / "o2b", executable=True),
"vault_log_script": _check_file(root / "scripts" / "vault-log", executable=True),
}
diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml
index 62d834fb..cb601865 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.4.2"
+version: "0.5.0"
description: "Hermes adapter for OpenSecondBrain vault health checks and optional MCP tool server."
author: "OpenSecondBrain contributors"
kind: standalone
diff --git a/pyproject.toml b/pyproject.toml
index 24ca8517..6c32a4f3 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
[project]
name = "open-second-brain"
-version = "0.4.2"
-description = "Hermes-first second brain package for Obsidian-compatible Markdown vaults."
+version = "0.5.0"
+description = "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw."
readme = "README.md"
requires-python = ">=3.11"
license = "MIT"
diff --git a/src/open_second_brain/__init__.py b/src/open_second_brain/__init__.py
index 482ab77c..f8433b4e 100644
--- a/src/open_second_brain/__init__.py
+++ b/src/open_second_brain/__init__.py
@@ -1,3 +1,3 @@
"""Open Second Brain core package."""
-__version__ = "0.4.2"
+__version__ = "0.5.0"
diff --git a/src/open_second_brain/doctor.py b/src/open_second_brain/doctor.py
index 0046c378..3ced1dd0 100644
--- a/src/open_second_brain/doctor.py
+++ b/src/open_second_brain/doctor.py
@@ -142,6 +142,24 @@ def check_hermes_manifest(path: Path) -> CheckResult:
return CheckResult("hermes_manifest", True, f"readable Hermes manifest: {path}")
+def check_openclaw_manifest(path: Path) -> CheckResult:
+ result, data = _load_json_manifest(path, "openclaw_manifest")
+ if data is None:
+ return result
+ problems: list[str] = []
+
+ # Required top-level fields
+ if "id" not in data or not isinstance(data["id"], str) or not data["id"].strip():
+ problems.append("missing or empty field 'id'")
+ schema = data.get("configSchema")
+ if not isinstance(schema, dict) or not schema:
+ problems.append("missing or empty field 'configSchema'")
+
+ if problems:
+ return CheckResult("openclaw_manifest", False, f"schema invalid: {path} ({'; '.join(problems)})")
+ return CheckResult("openclaw_manifest", True, f"valid OpenClaw manifest: {path}")
+
+
def doctor(
*,
vault: Path,
@@ -162,5 +180,6 @@ def doctor(
results.append(check_claude_manifest(repo_root / ".claude-plugin" / "plugin.json"))
results.append(check_codex_manifest(repo_root / ".codex-plugin" / "plugin.json"))
results.append(check_hermes_manifest(repo_root / "plugins" / "hermes" / "plugin.yaml"))
+ results.append(check_openclaw_manifest(repo_root / "openclaw.plugin.json"))
return results
diff --git a/src/open_second_brain/mcp.py b/src/open_second_brain/mcp.py
index d6d83c41..9e206d00 100644
--- a/src/open_second_brain/mcp.py
+++ b/src/open_second_brain/mcp.py
@@ -29,7 +29,7 @@ from open_second_brain.vault import list_vault_pages, parse_frontmatter, write_f
PROTOCOL_VERSION = "2025-06-18"
SERVER_NAME = "open-second-brain"
-SERVER_VERSION = "0.4.2"
+SERVER_VERSION = "0.5.0"
JSONRPC_VERSION = "2.0"
# JSON-RPC 2.0 error codes used by the MCP server.
diff --git a/tests/fixtures.py b/tests/fixtures.py
index 1deb92b5..bc5492a4 100644
--- a/tests/fixtures.py
+++ b/tests/fixtures.py
@@ -60,8 +60,21 @@ def create_plugin_repo(root: Path, *, valid: bool = True) -> Path:
"name: test\nversion: \"1.0.0\"\ndescription: test manifest\n",
encoding="utf-8",
)
+ (repo / "openclaw.plugin.json").write_text(
+ """{
+ "id": "test-plugin",
+ "configSchema": {
+ "type": "object",
+ "additionalProperties": false,
+ "properties": {}
+ }
+}
+""",
+ encoding="utf-8",
+ )
else:
(repo / ".claude-plugin" / "plugin.json").write_text("{\"name\": \"test\"}", encoding="utf-8")
(repo / ".codex-plugin" / "plugin.json").write_text("{\"name\": \"test\"}", encoding="utf-8")
(repo / "plugins" / "hermes" / "plugin.yaml").write_text("name: test\n", encoding="utf-8")
+ (repo / "openclaw.plugin.json").write_text("{}", encoding="utf-8")
return repo
diff --git a/tests/test_doctor.py b/tests/test_doctor.py
index 7633fcf5..7a51fa6b 100644
--- a/tests/test_doctor.py
+++ b/tests/test_doctor.py
@@ -9,6 +9,7 @@ from open_second_brain.doctor import (
check_codex_manifest,
check_hermes_manifest,
check_json_manifest,
+ check_openclaw_manifest,
check_vault_writeable,
doctor,
)
@@ -81,6 +82,7 @@ class DoctorTests(unittest.TestCase):
self.assertTrue(check_claude_manifest(repo / ".claude-plugin" / "plugin.json").ok)
self.assertTrue(check_codex_manifest(repo / ".codex-plugin" / "plugin.json").ok)
self.assertTrue(check_hermes_manifest(repo / "plugins" / "hermes" / "plugin.yaml").ok)
+ self.assertTrue(check_openclaw_manifest(repo / "openclaw.plugin.json").ok)
def test_manifest_schema_checks_reject_missing_required_fields(self):
with tempfile.TemporaryDirectory() as tmp:
@@ -88,12 +90,15 @@ class DoctorTests(unittest.TestCase):
claude = check_claude_manifest(repo / ".claude-plugin" / "plugin.json")
codex = check_codex_manifest(repo / ".codex-plugin" / "plugin.json")
hermes = check_hermes_manifest(repo / "plugins" / "hermes" / "plugin.yaml")
+ openclaw = check_openclaw_manifest(repo / "openclaw.plugin.json")
self.assertFalse(claude.ok)
self.assertFalse(codex.ok)
self.assertFalse(hermes.ok)
+ self.assertFalse(openclaw.ok)
self.assertIn("schema invalid", claude.message)
self.assertIn("skills", codex.message)
self.assertIn("missing", hermes.message)
+ self.assertIn("'id'", openclaw.message)
if __name__ == "__main__":
diff --git a/tests/test_hermes_plugin.py b/tests/test_hermes_plugin.py
index cf8ce697..28f8b0b6 100644
--- a/tests/test_hermes_plugin.py
+++ b/tests/test_hermes_plugin.py
@@ -15,6 +15,7 @@ class HermesPluginTests(unittest.TestCase):
self.assertTrue(report["ok"], report)
self.assertIn("claude_manifest", report["checks"])
self.assertIn("codex_manifest", report["checks"])
+ self.assertIn("openclaw_manifest", report["checks"])
self.assertIn("o2b_script", report["checks"])
def test_check_health_alias(self):
diff --git a/tests/test_openclaw_plugin.py b/tests/test_openclaw_plugin.py
new file mode 100644
index 00000000..c5dcca4b
--- /dev/null
+++ b/tests/test_openclaw_plugin.py
@@ -0,0 +1,134 @@
+"""Tests for OpenClaw plugin compatibility (openclaw.plugin.json)."""
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+from open_second_brain.doctor import check_openclaw_manifest
+from open_second_brain.mcp import MCPServer
+
+from tests.fixtures import create_plugin_repo
+
+
+class OpenClawManifestValidityTests(unittest.TestCase):
+ """Validate the shipped openclaw.plugin.json."""
+
+ @classmethod
+ def setUpClass(cls):
+ cls.manifest_path = ROOT / "openclaw.plugin.json"
+ with cls.manifest_path.open("r", encoding="utf-8") as f:
+ cls.manifest = json.load(f)
+
+ def test_manifest_is_valid_json(self):
+ self.assertIsInstance(self.manifest, dict)
+
+ def test_manifest_has_required_id(self):
+ self.assertEqual(self.manifest["id"], "open-second-brain")
+
+ def test_manifest_has_config_schema(self):
+ schema = self.manifest["configSchema"]
+ self.assertIsInstance(schema, dict)
+ self.assertEqual(schema["type"], "object")
+
+ def test_manifest_has_version(self):
+ self.assertEqual(self.manifest["version"], "0.5.0")
+
+ def test_manifest_declares_tools(self):
+ tools = self.manifest["contracts"]["tools"]
+ self.assertIsInstance(tools, list)
+ expected = {
+ "second_brain_status",
+ "second_brain_query",
+ "second_brain_capture",
+ "event_log_append",
+ "vault_health",
+ }
+ self.assertEqual(set(tools), expected)
+
+ def test_manifest_tool_names_match_mcp_server(self):
+ """Every tool declared in openclaw.plugin.json must exist in the MCP server."""
+ with tempfile.TemporaryDirectory() as tmp:
+ server = MCPServer(vault=Path(tmp))
+ mcp_tools = set(server._tools.keys())
+ manifest_tools = set(self.manifest["contracts"]["tools"])
+ self.assertEqual(
+ manifest_tools,
+ mcp_tools,
+ f"OpenClaw manifest tools {manifest_tools} do not match MCP tools {mcp_tools}",
+ )
+
+
+class OpenClawManifestDoctorTests(unittest.TestCase):
+ """Test the doctor check for openclaw.plugin.json."""
+
+ def test_doctor_passes_on_valid_manifest(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ repo = create_plugin_repo(Path(tmp), valid=True)
+ result = check_openclaw_manifest(repo / "openclaw.plugin.json")
+ self.assertTrue(result.ok, result.message)
+ self.assertEqual(result.name, "openclaw_manifest")
+
+ def test_doctor_fails_on_missing_manifest(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ result = check_openclaw_manifest(Path(tmp) / "missing.json")
+ self.assertFalse(result.ok)
+ self.assertEqual(result.name, "openclaw_manifest")
+
+ def test_doctor_fails_on_empty_manifest(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ manifest = Path(tmp) / "openclaw.plugin.json"
+ manifest.write_text("{}", encoding="utf-8")
+ result = check_openclaw_manifest(manifest)
+ self.assertFalse(result.ok)
+ self.assertIn("field 'id'", result.message)
+
+ def test_doctor_fails_on_missing_config_schema(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ manifest = Path(tmp) / "openclaw.plugin.json"
+ manifest.write_text(
+ json.dumps({"id": "test-plugin"}),
+ encoding="utf-8",
+ )
+ result = check_openclaw_manifest(manifest)
+ self.assertFalse(result.ok)
+ self.assertIn("configSchema", result.message)
+
+ def test_doctor_passes_on_real_repo_manifest(self):
+ result = check_openclaw_manifest(ROOT / "openclaw.plugin.json")
+ self.assertTrue(result.ok, result.message)
+
+
+class OpenClawInstallabilityTests(unittest.TestCase):
+ """Invariants required for `openclaw plugins install` to succeed."""
+
+ @classmethod
+ def setUpClass(cls):
+ cls.manifest_path = ROOT / "openclaw.plugin.json"
+
+ def test_manifest_file_exists_at_project_root(self):
+ self.assertTrue(self.manifest_path.is_file())
+
+ def test_manifest_is_parseable_json(self):
+ data = json.loads(self.manifest_path.read_text(encoding="utf-8"))
+ self.assertIn("id", data)
+
+ def test_bundle_adapter_claude_exists(self):
+ """OpenClaw Bundle format auto-detects .claude-plugin/."""
+ self.assertTrue((ROOT / ".claude-plugin" / "plugin.json").is_file())
+
+ def test_bundle_adapter_codex_exists(self):
+ """OpenClaw Bundle format auto-detects .codex-plugin/."""
+ self.assertTrue((ROOT / ".codex-plugin" / "plugin.json").is_file())
+
+ def test_no_package_json(self):
+ """OpenClaw native plugins need package.json; we deliberately omit it
+ because we use the Bundle format instead. If package.json is ever added
+ for tooling (ESLint, etc.), this test should be updated or removed."""
+ self.assertFalse((ROOT / "package.json").is_file())
+
+
+if __name__ == "__main__":
+ unittest.main()