soul-guardian

soul-guardian

Use this skill to detect and respond to unexpected edits in the workspace files that the agent auto-loads.

Installation Options

You can get soul-guardian in two ways:

Option A: Bundled with ClawSec Suite (Recommended)

If you've installed clawsec-suite, you may already have this!

Soul-guardian is bundled alongside ClawSec Suite to provide file integrity and drift detection capabilities. When you install the suite, if you don't already have soul-guardian installed, it will be deployed from the bundled copy.

Advantages:

• Convenient - no separate download needed
• Standard location - installed to ~/.openclaw/skills/soul-guardian/
• Preserved - if you already have soul-guardian installed, it won't be overwritten
• Single verification - integrity checked as part of suite package

Option B: Standalone Installation (This Page)

Install soul-guardian independently without the full suite.

When to use standalone:

• You only need file integrity monitoring (not other suite components)
• You want to install before installing the suite
• You prefer explicit control over soul-guardian installation

Advantages:

• Lighter weight installation
• Independent from suite
• Direct control over installation process

Continue below for standalone installation instructions.

---

What it protects (default policy)

• Auto-restore + alert: SOUL.md, AGENTS.md
• Alert-only: USER.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md, MEMORY.md
• Ignored by default: memory/*.md (daily notes)

Policy is stored in the guardian state directory as policy.json.

Quick start (first run)

Recommended: onboard an external state dir, then initialize baselines there.

python3 skills/soul-guardian/scripts/onboard_state_dir.py --agent-id <agentId>
python3 skills/soul-guardian/scripts/soul_guardian.py --state-dir ~/.clawdbot/soul-guardian/<agentId> init --actor sam --note "first baseline"

(Full step-by-step + scheduling options are in README.md.)

Commands

Run from the agent workspace root:

python3 skills/soul-guardian/scripts/soul_guardian.py status
python3 skills/soul-guardian/scripts/soul_guardian.py check
python3 skills/soul-guardian/scripts/soul_guardian.py check --no-restore
python3 skills/soul-guardian/scripts/soul_guardian.py approve --file SOUL.md
python3 skills/soul-guardian/scripts/soul_guardian.py restore --file SOUL.md
python3 skills/soul-guardian/scripts/soul_guardian.py verify-audit

State directory

• Default (backward compatible): memory/soul-guardian/
• Recommended external override:

python3 skills/soul-guardian/scripts/soul_guardian.py --state-dir ~/.clawdbot/soul-guardian/<agentId> check

Cron pattern

Keep the existing gateway cron pattern: run check every N minutes and notify only when drift is detected.

For onboarding/migration to an external state directory, see README.md and:

python3 skills/soul-guardian/scripts/onboard_state_dir.py