Sentinel - AI Agent State Guardian

Use this skill to protect AI agent workspaces from corruption, accidental changes, and data loss. Sentinel hashes your critical files, detects unexpected changes, creates rolling backups, and restores from backup when corruption is detected.

When to Use This Skill

Invoke this skill when:

• A user wants to protect their agent workspace from accidental overwrites
• You need to detect if critical files (agent config, memory/, state files) were modified unexpectedly
• Auto-backup is needed before any destructive operation
• You need to restore a workspace to a known-good state after corruption

Setup

# Copy config_example.py to sentinel_config.py and edit it:
WORKSPACE_ROOT = "/path/to/workspace"
BACKUP_DIR = "/path/to/backups"
STATE_FILE = "/path/to/sentinel_state.json"
CRITICAL_FILES = ["agent.md", "memory/*.md", "config/*.json"]
CHECK_INTERVAL_SECONDS = 600   # check every 10 minutes
MAX_BACKUP_VERSIONS = 10       # keep 10 rolling backups per file
AUTO_RESTORE_ON_CORRUPTION = True
DEBUG = False

Core Operations

Run Monitoring Cycle

import sentinel_config as config
from sentinel import Sentinel

s = Sentinel(config)
s.run_once()          # one monitoring pass
s.run_continuous()    # continuous loop (blocks)

CLI Usage

python3 sentinel.py --once          # run one cycle and exit
python3 sentinel.py --continuous    # run continuous monitoring
python3 sentinel.py --status        # show current status

Generate Workspace Manifest

import sentinel_config as config
from sentinel_manifest import ManifestGenerator

generator = ManifestGenerator(config)
manifest = generator.generate_manifest()
generator.save_manifest(manifest, Path("workspace_manifest.json"))

Compare Two Manifests

diff = generator.compare_manifests(old_manifest, new_manifest)
generator.print_diff_summary(diff)
# diff has: added_files, deleted_files, modified_files, added_dirs, deleted_dirs

Restore from Backup

import sentinel_config as config
from sentinel_restore import RestoreTool
from pathlib import Path

tool = RestoreTool(config)

# List all backups
tool.list_all_backups()

# Restore latest backup of a file
tool.restore_latest(Path(config.WORKSPACE_ROOT) / "memory/state.json")

# Interactive restore (lets you pick from backup list)
tool.interactive_restore(Path(config.WORKSPACE_ROOT) / "memory/state.json")

# Find latest backup path without restoring
backup_path = tool.find_latest_backup(Path(config.WORKSPACE_ROOT) / "memory/state.json")

CLI Restore

python3 sentinel_restore.py --file memory/state.json --latest
python3 sentinel_restore.py --file memory/state.json --interactive
python3 sentinel_restore.py --list

Integrity Violation Responses

When violations are detected, Sentinel can:

• Alert only — log and notify, take no action
• Auto-restore — revert changed files from latest clean snapshot
• Quarantine — move changed files to quarantine dir, restore originals

Configure in sentinel_config.py:

ON_VIOLATION = "alert"     # "alert" | "restore" | "quarantine"

What Sentinel Detects

• File content changes (hash mismatch)
• Deleted files that should exist
• New files in monitored directories
• Permission changes on critical files

See README.md for full configuration reference and advanced scheduling options.